@zlink-systems/framework-locations-redis 0.10.0

package/dist/opaque-redis-scripts.js

@@ -0,0 +1,330 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.BLOB_RENEW_SCRIPT = exports.BLOB_READ_SCRIPT = exports.BLOB_PUT_SCRIPT = exports.OPAQUE_SCAN_CONTINUE_SCRIPT = exports.OPAQUE_SCAN_START_SCRIPT = exports.OPAQUE_WRITE_SCRIPT = exports.OPAQUE_READ_SCRIPT = void 0;
+const PROLOGUE = `
+if redis.replicate_commands then redis.replicate_commands() end
+local time = redis.call('TIME')
+local nowMs = tonumber(time[1]) * 1000 + math.floor(tonumber(time[2]) / 1000)
+`;
+// Shared decode helper. Every opaque row is a Redis ZSET append-log; the
+// member with the highest score (the provider's monotonically increasing
+// INCR sequence) is current. Each member is a 1-byte format tag (0x01)
+// followed by a cmsgpack array {originalKey, rawBytes, version,
+// expiresAtMs, tombstone}. expiresAtMs == 0 means no expiry (unsigned int
+// family, never negative). tombstone is a real MessagePack bool.
+// Unrecognized format tags fail explicitly rather than guessing how to
+// read the value (21-location-runtime.md#2.4, 22-location-store-redis.md#7).
+const DECODE_HELPERS = `
+local function decodeMember(raw)
+    if string.byte(raw, 1) ~= 1 then
+        return redis.error_reply('zlink opaque record: unrecognized format tag')
+    end
+    return cmsgpack.unpack(string.sub(raw, 2))
+end
+
+local function liveRecordAt(rowKey, referenceMs)
+    local members = redis.call('ZREVRANGE', rowKey, 0, 0)
+    if #members == 0 then return nil end
+    local record = decodeMember(members[1])
+    local expiresAtMs = tonumber(record[4])
+    if record[5] == true or (expiresAtMs > 0 and expiresAtMs <= referenceMs) then
+        return nil
+    end
+    return record
+end
+
+local function encodeMember(originalKey, bytes, version, expiresAtMs, tombstone)
+    return string.char(1) .. cmsgpack.pack({
+        originalKey, bytes, version, expiresAtMs, tombstone
+    })
+end
+`;
+exports.OPAQUE_READ_SCRIPT = PROLOGUE + DECODE_HELPERS + `
+local record = liveRecordAt(KEYS[1], nowMs)
+if not record then return {0, nowMs} end
+return {1, nowMs, record[1], record[2], record[3], tostring(tonumber(record[4]))}
+`;
+// KEYS[1..6] = indexKey, mapKey, cleanupKey, sequenceKey, snapshotExpiryKey,
+// snapshotBoundaryKey (private auxiliary keys, not part of the public
+// contract). KEYS[7..] = the opaque record row keys referenced by
+// conditions/mutations, in the order fixed by ARGV[1]/ARGV[2].
+// ARGV[1] = JSON conditions: ['missing', keyIndex, originalKey]
+//           | ['version', keyIndex, originalKey, expectedVersion]
+// ARGV[2] = JSON mutation metadata (no raw bytes, JSON must stay text-safe):
+//           ['put', keyIndex, originalKey, retentionMsOrFalse]
+//           | ['delete', keyIndex, originalKey]
+// ARGV[3..] = one raw-bytes argument per 'put' mutation, in mutation order.
+exports.OPAQUE_WRITE_SCRIPT = PROLOGUE + DECODE_HELPERS + `
+local indexKey = KEYS[1]
+local mapKey = KEYS[2]
+local cleanupKey = KEYS[3]
+local sequenceKey = KEYS[4]
+local snapshotExpiryKey = KEYS[5]
+local snapshotBoundaryKey = KEYS[6]
+
+local expiredSnapshots = redis.call('ZRANGEBYSCORE', snapshotExpiryKey, '-inf', nowMs, 'LIMIT', 0, 128)
+for _, snapshotId in ipairs(expiredSnapshots) do
+    redis.call('ZREM', snapshotExpiryKey, snapshotId)
+    redis.call('ZREM', snapshotBoundaryKey, snapshotId)
+end
+local minimumBoundary = nil
+local boundaryEntry = redis.call('ZRANGE', snapshotBoundaryKey, 0, 0, 'WITHSCORES')
+if #boundaryEntry == 2 then minimumBoundary = tonumber(boundaryEntry[2]) end
+
+local due = redis.call('ZRANGEBYSCORE', cleanupKey, '-inf', nowMs, 'LIMIT', 0, 32)
+for _, original in ipairs(due) do
+    local rowKey = redis.call('HGET', mapKey, original)
+    local members = {}
+    if rowKey then
+        members = redis.call('ZREVRANGE', rowKey, 0, 0, 'WITHSCORES')
+    end
+    if #members == 0 then
+        redis.call('ZREM', indexKey, original)
+        redis.call('HDEL', mapKey, original)
+        redis.call('ZREM', cleanupKey, original)
+    elseif minimumBoundary then
+        local anchor = redis.call('ZREVRANGEBYSCORE', rowKey, minimumBoundary, '-inf', 'WITHSCORES', 'LIMIT', 0, 1)
+        if #anchor == 2 then
+            redis.call('ZREMRANGEBYSCORE', rowKey, '-inf', '(' .. anchor[2])
+        end
+        redis.call('ZADD', cleanupKey, nowMs + 1000, original)
+    else
+        local record = decodeMember(members[1])
+        local expiresAtMs = tonumber(record[4])
+        if record[5] == true or (expiresAtMs > 0 and expiresAtMs + 60000 <= nowMs) then
+            redis.call('DEL', rowKey)
+            redis.call('ZREM', indexKey, original)
+            redis.call('HDEL', mapKey, original)
+            redis.call('ZREM', cleanupKey, original)
+        else
+            redis.call('ZREMRANGEBYRANK', rowKey, 0, -2)
+            if expiresAtMs > 0 then
+                redis.call('ZADD', cleanupKey, math.max(nowMs + 1000, expiresAtMs + 60000), original)
+            else
+                redis.call('ZREM', cleanupKey, original)
+            end
+        end
+    end
+end
+
+local conditions = cjson.decode(ARGV[1])
+local mutations = cjson.decode(ARGV[2])
+
+for _, condition in ipairs(conditions) do
+    local record = liveRecordAt(KEYS[condition[2] + 6], nowMs)
+    local currentVersion = record and record[3] or nil
+    if condition[1] == 'missing' then
+        if currentVersion ~= nil then return {'conflict', nowMs} end
+    elseif currentVersion ~= condition[4] then
+        return {'conflict', nowMs}
+    end
+end
+
+for _, mutation in ipairs(mutations) do
+    local rowKey = KEYS[mutation[2] + 6]
+    if not minimumBoundary then
+        redis.call('ZREMRANGEBYRANK', rowKey, 0, -2)
+    end
+    if redis.call('ZCARD', rowKey) >= 128 then
+        return {'backlog', nowMs}
+    end
+end
+
+local sequence = tostring(redis.call('INCR', sequenceKey))
+local byteArg = 3
+local result = {'applied', nowMs}
+for _, mutation in ipairs(mutations) do
+    local rowKey = KEYS[mutation[2] + 6]
+    local originalKey = mutation[3]
+    if mutation[1] == 'put' then
+        local bytes = ARGV[byteArg]
+        byteArg = byteArg + 1
+        local retention = mutation[4]
+        local expiresAtMs = 0
+        if retention ~= false then expiresAtMs = nowMs + tonumber(retention) end
+        redis.call('ZADD', rowKey, sequence, encodeMember(originalKey, bytes, sequence, expiresAtMs, false))
+        redis.call('ZADD', indexKey, 0, originalKey)
+        redis.call('HSET', mapKey, originalKey, rowKey)
+        table.insert(result, originalKey)
+        table.insert(result, sequence)
+    else
+        redis.call('ZADD', rowKey, sequence, encodeMember(originalKey, '', sequence, 0, true))
+        redis.call('ZADD', indexKey, 0, originalKey)
+        redis.call('HSET', mapKey, originalKey, rowKey)
+    end
+    local dueAt = nowMs + 1000
+    local scheduled = redis.call('ZSCORE', cleanupKey, originalKey)
+    if not scheduled or tonumber(scheduled) > dueAt then
+        redis.call('ZADD', cleanupKey, dueAt, originalKey)
+    end
+end
+return result
+`;
+// Shared body for point-in-time paged scanning. KEYS[1]=indexKey,
+// KEYS[2]=mapKey, KEYS[3]=snapshotKey, KEYS[4]=cleanupKey,
+// KEYS[5]=sequenceKey, KEYS[6]=snapshotExpiryKey, KEYS[7]=snapshotBoundaryKey.
+const SCAN_CLEANUP_AND_BOUNDARY = DECODE_HELPERS + `
+local expiredSnapshots = redis.call('ZRANGEBYSCORE', KEYS[6], '-inf', nowMs, 'LIMIT', 0, 128)
+for _, expiredId in ipairs(expiredSnapshots) do
+    redis.call('ZREM', KEYS[6], expiredId)
+    redis.call('ZREM', KEYS[7], expiredId)
+end
+local minimumBoundary = nil
+local boundaryEntry = redis.call('ZRANGE', KEYS[7], 0, 0, 'WITHSCORES')
+if #boundaryEntry == 2 then minimumBoundary = tonumber(boundaryEntry[2]) end
+
+local due = redis.call('ZRANGEBYSCORE', KEYS[4], '-inf', nowMs, 'LIMIT', 0, 32)
+for _, original in ipairs(due) do
+    local rowKey = redis.call('HGET', KEYS[2], original)
+    local members = {}
+    if rowKey then
+        members = redis.call('ZREVRANGE', rowKey, 0, 0, 'WITHSCORES')
+    end
+    if #members == 0 then
+        redis.call('ZREM', KEYS[1], original)
+        redis.call('HDEL', KEYS[2], original)
+        redis.call('ZREM', KEYS[4], original)
+    elseif minimumBoundary then
+        local anchor = redis.call('ZREVRANGEBYSCORE', rowKey, minimumBoundary, '-inf', 'WITHSCORES', 'LIMIT', 0, 1)
+        if #anchor == 2 then
+            redis.call('ZREMRANGEBYSCORE', rowKey, '-inf', '(' .. anchor[2])
+        end
+        redis.call('ZADD', KEYS[4], nowMs + 1000, original)
+    else
+        local record = decodeMember(members[1])
+        local expiresAtMs = tonumber(record[4])
+        if record[5] == true or (expiresAtMs > 0 and expiresAtMs + 60000 <= nowMs) then
+            redis.call('DEL', rowKey)
+            redis.call('ZREM', KEYS[1], original)
+            redis.call('HDEL', KEYS[2], original)
+            redis.call('ZREM', KEYS[4], original)
+        else
+            redis.call('ZREMRANGEBYRANK', rowKey, 0, -2)
+            if expiresAtMs > 0 then
+                redis.call('ZADD', KEYS[4], math.max(nowMs + 1000, expiresAtMs + 60000), original)
+            else
+                redis.call('ZREM', KEYS[4], original)
+            end
+        end
+    end
+end
+`;
+const SCAN_PAGE_READ = `
+local metadata = redis.call('HMGET', KEYS[3], 'now', 'boundary', 'prefix')
+if not metadata[1] or metadata[3] ~= prefix then
+    redis.call('ZREM', KEYS[6], snapshotId)
+    redis.call('ZREM', KEYS[7], snapshotId)
+    return {'expired'}
+end
+local snapshotNow = tonumber(metadata[1])
+local boundary = tonumber(metadata[2])
+local lower = '-'
+if string.len(lastKey) > 0 then lower = '(' .. lastKey end
+local workLimit = math.max(limit * 4, 128)
+local originals = redis.call('ZRANGEBYLEX', KEYS[1], lower, '+', 'LIMIT', 0, workLimit + 1)
+local emitted = 0
+local encodedBytes = 0
+local examined = 0
+local result = {'page', tostring(snapshotNow), ''}
+while examined < #originals and examined < workLimit and emitted < limit do
+    local original = originals[examined + 1]
+    examined = examined + 1
+    if string.sub(original, 1, string.len(prefix)) == prefix then
+        local rowKey = redis.call('HGET', KEYS[2], original)
+        if rowKey then
+            local members = redis.call('ZREVRANGEBYSCORE', rowKey, boundary, '-inf', 'LIMIT', 0, 1)
+            if #members > 0 then
+                local record = decodeMember(members[1])
+                local expiresAtMs = tonumber(record[4])
+                if record[1] == original and record[5] ~= true
+                    and (expiresAtMs == 0 or expiresAtMs > snapshotNow) then
+                    local itemBytes = string.len(original) + string.len(record[2]) + string.len(record[3]) + 128
+                    if emitted > 0 and encodedBytes + itemBytes > 4194304 then
+                        examined = examined - 1
+                        break
+                    end
+                    table.insert(result, original)
+                    table.insert(result, record[2])
+                    table.insert(result, record[3])
+                    table.insert(result, tostring(expiresAtMs))
+                    encodedBytes = encodedBytes + itemBytes
+                    emitted = emitted + 1
+                end
+            end
+        end
+    end
+end
+
+local hasMore = examined < #originals
+if not hasMore and #originals > workLimit then hasMore = true end
+if hasMore then
+    result[3] = originals[examined]
+else
+    redis.call('DEL', KEYS[3])
+    redis.call('ZREM', KEYS[6], snapshotId)
+    redis.call('ZREM', KEYS[7], snapshotId)
+end
+return result
+`;
+// ARGV = [prefix, limit, snapshotId]
+exports.OPAQUE_SCAN_START_SCRIPT = PROLOGUE + SCAN_CLEANUP_AND_BOUNDARY + `
+local prefix = ARGV[1]
+local limit = tonumber(ARGV[2])
+local snapshotId = ARGV[3]
+local lastKey = ''
+
+if redis.call('ZCARD', KEYS[6]) >= 4096 then
+    return {'capacity'}
+end
+redis.call('DEL', KEYS[3])
+local boundary = tonumber(redis.call('GET', KEYS[5]) or '0')
+redis.call('HSET', KEYS[3], 'now', tostring(nowMs), 'boundary', tostring(boundary), 'prefix', prefix)
+redis.call('PEXPIRE', KEYS[3], 60000)
+redis.call('ZADD', KEYS[6], nowMs + 60000, snapshotId)
+redis.call('ZADD', KEYS[7], boundary, snapshotId)
+` + SCAN_PAGE_READ;
+// ARGV = [prefix, lastKeyHex, limit, snapshotId]
+exports.OPAQUE_SCAN_CONTINUE_SCRIPT = PROLOGUE + SCAN_CLEANUP_AND_BOUNDARY + `
+local prefix = ARGV[1]
+local lastKey = ARGV[2]
+local limit = tonumber(ARGV[3])
+local snapshotId = ARGV[4]
+
+if redis.call('EXISTS', KEYS[3]) == 0 then
+    redis.call('ZREM', KEYS[6], snapshotId)
+    redis.call('ZREM', KEYS[7], snapshotId)
+    return {'expired'}
+end
+` + SCAN_PAGE_READ;
+// Relocation Store: raw-bytes STRING payloads at
+// {prefix}:zlink-relocation-v1:blob:{reference}, retention via PSETEX/PX
+// (23-relocation-store-redis.md#8). KEYS[1] is the blob key -- the reference
+// itself is already the key's last segment, so identity on retry is decided
+// by comparing the stored bytes against ARGV[1].
+exports.BLOB_PUT_SCRIPT = PROLOGUE + `
+local existing = redis.call('GET', KEYS[1])
+if existing then
+    if existing ~= ARGV[1] then
+        return {'conflict', nowMs}
+    end
+    local ttl = redis.call('PTTL', KEYS[1])
+    local expiresAtMs = nowMs + math.max(ttl, 0)
+    return {'alreadyStored', nowMs, tostring(expiresAtMs)}
+end
+local retentionMs = tonumber(ARGV[2])
+redis.call('SET', KEYS[1], ARGV[1], 'PX', retentionMs)
+return {'stored', nowMs, tostring(nowMs + retentionMs)}
+`;
+exports.BLOB_READ_SCRIPT = PROLOGUE + `
+local bytes = redis.call('GET', KEYS[1])
+if not bytes then return {0, nowMs} end
+local ttl = redis.call('PTTL', KEYS[1])
+local expiresAtMs = nowMs + math.max(ttl, 0)
+return {1, nowMs, bytes, tostring(expiresAtMs)}
+`;
+exports.BLOB_RENEW_SCRIPT = PROLOGUE + `
+if redis.call('EXISTS', KEYS[1]) == 0 then return {0, nowMs} end
+local retentionMs = tonumber(ARGV[1])
+redis.call('PEXPIRE', KEYS[1], retentionMs)
+return {1, nowMs, tostring(nowMs + retentionMs)}
+`;

package/dist/opaque-store.d.ts

@@ -0,0 +1,22 @@
+import type { ZLinkLocationStore, ZLinkStoreKey, ZLinkStoreReadResult, ZLinkStoreScanRequest, ZLinkStoreScanResult, ZLinkStoreWriteRequest, ZLinkStoreWriteResult } from '@zlink-systems/framework';
+import type { ZLinkRedisLocationOptions } from './redis-options';
+/** Redis implementation of the opaque Location Store provider SPI. */
+export declare class ZLinkRedisLocationStore implements ZLinkLocationStore {
+    private readonly connection;
+    private readonly domain;
+    constructor(options: ZLinkRedisLocationOptions);
+    read(key: ZLinkStoreKey, signal?: AbortSignal): Promise<ZLinkStoreReadResult>;
+    write(request: ZLinkStoreWriteRequest, signal?: AbortSignal): Promise<ZLinkStoreWriteResult>;
+    scan(request: ZLinkStoreScanRequest, signal?: AbortSignal): Promise<ZLinkStoreScanResult>;
+    dispose(): Promise<void>;
+    private readScanPage;
+    private scanKeys;
+    private indexKey;
+    private mapKey;
+    private cleanupKey;
+    private sequenceKey;
+    private snapshotExpiryKey;
+    private snapshotBoundaryKey;
+    private snapshotKey;
+    private rowKey;
+}

package/dist/opaque-store.js

@@ -0,0 +1,295 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ZLinkRedisLocationStore = void 0;
+const node_crypto_1 = require("node:crypto");
+const redis_connection_1 = require("./redis-connection");
+const opaque_redis_scripts_1 = require("./opaque-redis-scripts");
+const redis_values_1 = require("./redis-values");
+const MAX_VALUE_BYTES = 1024 * 1024;
+const MAX_WRITE_KEYS = 2_048;
+const MAX_WRITE_BYTES = 4 * 1024 * 1024;
+// {prefix}:{zlink-location-v3}:opaque:{sha256hex(preimage)} is the public
+// contract (21-location-runtime.md#2.4, 22-location-store-redis.md#7). The
+// braces are a Redis Cluster hash tag: every key this provider's scripts
+// touch in one EVAL (the record row plus the private auxiliary keys below)
+// must land on the same hash slot, matching the dotnet/java reference. Only
+// the six auxiliary keys below (index/map/cleanup/sequence/snapshot*) are a
+// private implementation detail of this provider's point-in-time scan.
+const NAMESPACE = '{zlink-location-v3}:opaque';
+/** Redis implementation of the opaque Location Store provider SPI. */
+class ZLinkRedisLocationStore {
+    connection;
+    domain;
+    constructor(options) {
+        this.connection = new redis_connection_1.RedisConnection(options);
+        this.domain = `${options.keyPrefix}:${NAMESPACE}`;
+    }
+    async read(key, signal) {
+        const logicalKey = requireKey(key);
+        const result = (0, redis_values_1.asArray)(await this.connection.eval(opaque_redis_scripts_1.OPAQUE_READ_SCRIPT, [this.rowKey(logicalKey)], [], signal));
+        const storeNow = fromUnixMs((0, redis_values_1.toNumber)(result[1]));
+        if ((0, redis_values_1.toNumber)(result[0]) !== 1)
+            return { kind: 'missing', storeNow };
+        requireMatchingKey((0, redis_values_1.asString)(result[2]), logicalKey);
+        return {
+            kind: 'found',
+            value: {
+                bytes: rawBytes(result[3]),
+                version: storeVersion((0, redis_values_1.asString)(result[4])),
+                expiresAt: expiresAtOrUndefined((0, redis_values_1.toNumber)(result[5])),
+                storeNow
+            }
+        };
+    }
+    async write(request, signal) {
+        const encoded = encodeWrite(request);
+        const result = (0, redis_values_1.asArray)(await this.connection.eval(opaque_redis_scripts_1.OPAQUE_WRITE_SCRIPT, [
+            this.indexKey(),
+            this.mapKey(),
+            this.cleanupKey(),
+            this.sequenceKey(),
+            this.snapshotExpiryKey(),
+            this.snapshotBoundaryKey(),
+            ...encoded.keys.map(key => this.rowKey(key))
+        ], [
+            JSON.stringify(encoded.conditions),
+            JSON.stringify(encoded.mutations),
+            ...encoded.putBytes
+        ], signal));
+        const storeNow = fromUnixMs((0, redis_values_1.toNumber)(result[1]));
+        const outcome = (0, redis_values_1.asString)(result[0]);
+        if (outcome === 'conflict')
+            return { kind: 'conflict', storeNow };
+        if (outcome === 'backlog') {
+            throw new Error('Redis Location Store version backlog is full.');
+        }
+        if (outcome !== 'applied') {
+            throw new Error('Redis Location Store returned an unrecognized write outcome.');
+        }
+        const putVersions = [];
+        for (let index = 2; index < result.length; index += 2) {
+            putVersions.push({
+                key: storeKey((0, redis_values_1.asString)(result[index])),
+                version: storeVersion((0, redis_values_1.asString)(result[index + 1]))
+            });
+        }
+        return { kind: 'applied', putVersions, storeNow };
+    }
+    async scan(request, signal) {
+        requireScanRequest(request);
+        if (request.cursor === undefined) {
+            const snapshotId = (0, node_crypto_1.randomUUID)();
+            return await this.readScanPage(snapshotId, await this.connection.eval(opaque_redis_scripts_1.OPAQUE_SCAN_START_SCRIPT, this.scanKeys(snapshotId), [request.prefix, String(request.limit), snapshotId], signal));
+        }
+        const cursor = parseCursor(request.cursor);
+        return await this.readScanPage(cursor.snapshotId, await this.connection.eval(opaque_redis_scripts_1.OPAQUE_SCAN_CONTINUE_SCRIPT, this.scanKeys(cursor.snapshotId), [request.prefix, cursor.lastKey, String(request.limit), cursor.snapshotId], signal));
+    }
+    async dispose() {
+        await this.connection.dispose();
+    }
+    async readScanPage(snapshotId, raw) {
+        const result = (0, redis_values_1.asArray)(raw);
+        const outcome = (0, redis_values_1.asString)(result[0]);
+        if (outcome === 'expired')
+            return { kind: 'expired' };
+        if (outcome === 'capacity') {
+            throw new Error('Redis Location Store snapshot capacity is full.');
+        }
+        if (outcome !== 'page') {
+            throw new Error('Redis Location Store returned an unrecognized scan outcome.');
+        }
+        const storeNow = fromUnixMs((0, redis_values_1.toNumber)(result[1]));
+        const nextKey = (0, redis_values_1.asString)(result[2]);
+        const items = [];
+        for (let index = 3; index < result.length; index += 4) {
+            items.push({
+                key: storeKey((0, redis_values_1.asString)(result[index])),
+                value: {
+                    bytes: rawBytes(result[index + 1]),
+                    version: storeVersion((0, redis_values_1.asString)(result[index + 2])),
+                    expiresAt: expiresAtOrUndefined((0, redis_values_1.toNumber)(result[index + 3])),
+                    storeNow
+                }
+            });
+        }
+        return {
+            kind: 'page',
+            value: {
+                items,
+                nextCursor: nextKey.length === 0
+                    ? undefined
+                    : scanCursor(`${snapshotId}:${Buffer.from(nextKey, 'utf8').toString('hex')}`),
+                storeNow
+            }
+        };
+    }
+    scanKeys(snapshotId) {
+        return [
+            this.indexKey(),
+            this.mapKey(),
+            this.snapshotKey(snapshotId),
+            this.cleanupKey(),
+            this.sequenceKey(),
+            this.snapshotExpiryKey(),
+            this.snapshotBoundaryKey()
+        ];
+    }
+    indexKey() {
+        return `${this.domain}:index`;
+    }
+    mapKey() {
+        return `${this.domain}:map`;
+    }
+    cleanupKey() {
+        return `${this.domain}:cleanup`;
+    }
+    sequenceKey() {
+        return `${this.domain}:sequence`;
+    }
+    snapshotExpiryKey() {
+        return `${this.domain}:snapshot-expiry`;
+    }
+    snapshotBoundaryKey() {
+        return `${this.domain}:snapshot-boundary`;
+    }
+    snapshotKey(snapshotId) {
+        return `${this.domain}:scan:${snapshotId}`;
+    }
+    rowKey(logicalKey) {
+        return `${this.domain}:${digest(logicalKey)}`;
+    }
+}
+exports.ZLinkRedisLocationStore = ZLinkRedisLocationStore;
+function encodeWrite(request) {
+    const conditionKeys = request.conditions.map(condition => requireKey(condition.key));
+    const mutationKeys = request.mutations.map(mutation => requireKey(mutation.key));
+    if (new Set(conditionKeys).size !== conditionKeys.length
+        || new Set(mutationKeys).size !== mutationKeys.length) {
+        throw new RangeError('Location Store condition and mutation keys must be unique.');
+    }
+    const keys = [...new Set([...conditionKeys, ...mutationKeys])];
+    if (keys.length > MAX_WRITE_KEYS) {
+        throw new RangeError('Location Store write exceeds 2,048 unique keys.');
+    }
+    // Row keys are appended after the six fixed auxiliary keys; the script
+    // adds 6 to this 1-based index before indexing into KEYS.
+    const keyIndex = new Map(keys.map((key, index) => [key, index + 1]));
+    let encodedBytes = 0;
+    const conditions = request.conditions.map(condition => {
+        const key = requireKey(condition.key);
+        encodedBytes += Buffer.byteLength(key, 'utf8');
+        if (condition.kind === 'missing')
+            return ['missing', keyIndex.get(key), key];
+        const expected = requireVersion(condition.expected);
+        encodedBytes += Buffer.byteLength(expected, 'utf8');
+        return ['version', keyIndex.get(key), key, expected];
+    });
+    const putBytes = [];
+    const mutations = request.mutations.map(mutation => {
+        const key = requireKey(mutation.key);
+        encodedBytes += Buffer.byteLength(key, 'utf8');
+        if (mutation.kind === 'delete')
+            return ['delete', keyIndex.get(key), key];
+        requireValue(mutation.bytes, mutation.retentionMs);
+        encodedBytes += mutation.bytes.byteLength;
+        putBytes.push(Buffer.from(mutation.bytes));
+        return [
+            'put',
+            keyIndex.get(key),
+            key,
+            mutation.retentionMs ?? false
+        ];
+    });
+    if (encodedBytes > MAX_WRITE_BYTES) {
+        throw new RangeError('Location Store write exceeds 4 MiB encoded input.');
+    }
+    return { keys, conditions, mutations, putBytes };
+}
+function requireScanRequest(request) {
+    if (Buffer.byteLength(request.prefix, 'utf8') > 1_024) {
+        throw new RangeError('Location Store scan prefix exceeds 1,024 UTF-8 bytes.');
+    }
+    if (!Number.isSafeInteger(request.limit) || request.limit < 1 || request.limit > 1_000) {
+        throw new RangeError('Location Store scan limit must be in 1..1000.');
+    }
+    if (request.cursor !== undefined)
+        requireCursor(request.cursor);
+}
+function requireKey(key) {
+    const value = key.value;
+    const bytes = Buffer.byteLength(value, 'utf8');
+    if (bytes < 1 || bytes > 1_024) {
+        throw new RangeError('Location Store key must contain 1..1,024 UTF-8 bytes.');
+    }
+    return value;
+}
+function requireMatchingKey(actual, expected) {
+    if (actual !== expected) {
+        throw new Error('Redis opaque record key digest resolved to a different logical key.');
+    }
+}
+function requireVersion(version) {
+    const value = version.value;
+    const bytes = Buffer.byteLength(value, 'utf8');
+    if (bytes < 1 || bytes > 4_096) {
+        throw new RangeError('Location Store version must contain 1..4,096 UTF-8 bytes.');
+    }
+    return value;
+}
+function requireCursor(cursor) {
+    const value = cursor.value;
+    const bytes = Buffer.byteLength(value, 'utf8');
+    if (bytes < 1 || bytes > 4_096) {
+        throw new RangeError('Location Store cursor must contain 1..4,096 UTF-8 bytes.');
+    }
+    return value;
+}
+function requireValue(bytes, retentionMs) {
+    if (bytes.byteLength > MAX_VALUE_BYTES) {
+        throw new RangeError('Location Store value exceeds 1 MiB.');
+    }
+    if (retentionMs !== undefined
+        && (!Number.isSafeInteger(retentionMs) || retentionMs < 1)) {
+        throw new RangeError('Location Store retention must be a positive safe integer.');
+    }
+}
+function parseCursor(cursor) {
+    const value = requireCursor(cursor);
+    const separator = value.lastIndexOf(':');
+    const snapshotId = separator < 0 ? '' : value.slice(0, separator);
+    const lastKeyHex = separator < 0 ? '' : value.slice(separator + 1);
+    if (!/^[0-9a-f-]{36}$/.test(snapshotId)
+        || !/^[0-9a-f]*$/.test(lastKeyHex)
+        || lastKeyHex.length % 2 !== 0) {
+        throw new RangeError('Location Store scan cursor is invalid.');
+    }
+    return { snapshotId, lastKey: Buffer.from(lastKeyHex, 'hex').toString('utf8') };
+}
+function rawBytes(value) {
+    if (Buffer.isBuffer(value))
+        return Uint8Array.from(value);
+    if (value instanceof Uint8Array)
+        return Uint8Array.from(value);
+    return Uint8Array.from(Buffer.from((0, redis_values_1.asString)(value), 'utf8'));
+}
+function digest(value) {
+    return (0, node_crypto_1.createHash)('sha256').update(value, 'utf8').digest('hex');
+}
+function storeKey(value) {
+    return { value };
+}
+function storeVersion(value) {
+    return { value };
+}
+function scanCursor(value) {
+    return { value };
+}
+function expiresAtOrUndefined(expiresAtMs) {
+    return expiresAtMs === 0 ? undefined : fromUnixMs(expiresAtMs);
+}
+function fromUnixMs(value) {
+    if (!Number.isSafeInteger(value) || value < 0) {
+        throw new Error('Redis Store returned an invalid provider timestamp.');
+    }
+    return new Date(value);
+}

package/dist/redis-connection.d.ts

@@ -0,0 +1,16 @@
+import type { RedisClientType } from 'redis';
+import type { ZLinkRedisLocationOptions, ZLinkRedisRelocationOptions } from './redis-options';
+export type RedisCommandValue = string | Buffer;
+export type RedisCommandClient = Pick<RedisClientType, 'isOpen' | 'isReady' | 'connect' | 'disconnect' | 'sendCommand' | 'quit' | 'on'>;
+export declare class RedisConnection {
+    private readonly providedClient?;
+    private client?;
+    private connectionAttempt?;
+    private disposed;
+    private readonly operationTimeoutMs?;
+    constructor(options: ZLinkRedisLocationOptions | ZLinkRedisRelocationOptions);
+    command(args: RedisCommandValue[], signal?: AbortSignal): Promise<unknown>;
+    eval(script: string, keys: readonly string[], args: readonly RedisCommandValue[], signal?: AbortSignal): Promise<unknown>;
+    dispose(): Promise<void>;
+    private connected;
+}