@zlink-systems/framework-locations-redis 0.10.0

package/dist/redis-connection.js

@@ -0,0 +1,136 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.RedisConnection = void 0;
+const redis_1 = require("redis");
+class RedisConnection {
+    providedClient;
+    client;
+    connectionAttempt;
+    disposed = false;
+    operationTimeoutMs;
+    constructor(options) {
+        requireOptions(options);
+        this.providedClient = options.client;
+        this.operationTimeoutMs = options.operationTimeoutMs;
+        if (options.client === undefined) {
+            this.client = (0, redis_1.createClient)({
+                disableOfflineQueue: true,
+                ...(options.clientOptions ?? {}),
+                socket: {
+                    reconnectStrategy: false,
+                    ...(options.clientOptions?.socket ?? {})
+                },
+                url: options.url ?? options.clientOptions?.url
+            });
+            this.client.on('error', () => { });
+        }
+    }
+    async command(args, signal) {
+        signal?.throwIfAborted();
+        const client = await this.connected(signal);
+        // Store values are opaque bytes. Returning RESP bulk strings as UTF-8
+        // strings would replace invalid byte sequences before the provider can
+        // copy them into Uint8Array.
+        const operation = client.sendCommand(args, {
+            typeMapping: {
+                [redis_1.RESP_TYPES.BLOB_STRING]: Buffer
+            }
+        });
+        return await waitForOperation(operation, signal, this.operationTimeoutMs);
+    }
+    async eval(script, keys, args, signal) {
+        return await this.command(['EVAL', script, String(keys.length), ...keys, ...args], signal);
+    }
+    async dispose() {
+        if (this.disposed)
+            return;
+        this.disposed = true;
+        const client = this.client;
+        this.client = undefined;
+        if (client !== undefined && client.isOpen === true) {
+            await client.quit();
+        }
+    }
+    async connected(signal) {
+        signal?.throwIfAborted();
+        if (this.disposed)
+            throw new Error('Redis Store is disposed.');
+        const client = this.providedClient ?? this.client;
+        if (client === undefined)
+            throw new Error('Redis Store is disposed.');
+        if (isClientReady(client))
+            return client;
+        if (this.connectionAttempt === undefined) {
+            // Publish the attempt before any await. A failed connection can leave
+            // node-redis open but not ready; the close and reconnect sequence must
+            // still be owned by this single promise when callers arrive together.
+            const attempt = (async () => {
+                if (client.isOpen === true && !isClientReady(client)) {
+                    await client.disconnect();
+                }
+                await client.connect();
+            })();
+            this.connectionAttempt = attempt;
+            attempt.then(() => {
+                if (this.connectionAttempt === attempt)
+                    this.connectionAttempt = undefined;
+            }, () => {
+                if (this.connectionAttempt === attempt)
+                    this.connectionAttempt = undefined;
+            });
+        }
+        await waitForOperation(this.connectionAttempt, signal, this.operationTimeoutMs);
+        if (!isClientReady(client)) {
+            throw new Error('Redis client connection completed before it became ready.');
+        }
+        return client;
+    }
+}
+exports.RedisConnection = RedisConnection;
+function isClientReady(client) {
+    return client.isReady === true;
+}
+function requireOptions(options) {
+    if (options.keyPrefix.length === 0) {
+        throw new Error('Redis Store keyPrefix is required.');
+    }
+    if (options.keyPrefix.includes('{') || options.keyPrefix.includes('}')) {
+        throw new Error('Redis Store keyPrefix must not contain hash-tag braces.');
+    }
+    if (options.client === undefined
+        && options.url === undefined
+        && options.clientOptions === undefined) {
+        throw new Error('Redis Store requires url, clientOptions, or client.');
+    }
+    if (options.operationTimeoutMs !== undefined
+        && (!Number.isSafeInteger(options.operationTimeoutMs)
+            || options.operationTimeoutMs < 1)) {
+        throw new RangeError('Redis Store operationTimeoutMs must be a positive safe integer.');
+    }
+}
+async function waitForOperation(operation, signal, timeoutMs) {
+    if (signal === undefined && timeoutMs === undefined)
+        return await operation;
+    return await new Promise((resolve, reject) => {
+        let timeout;
+        let settled = false;
+        const cleanup = () => {
+            signal?.removeEventListener('abort', onAbort);
+            if (timeout !== undefined)
+                clearTimeout(timeout);
+        };
+        const settle = (action) => {
+            if (settled)
+                return;
+            settled = true;
+            cleanup();
+            action();
+        };
+        const onAbort = () => settle(() => reject(signal?.reason ?? new Error('Redis Store operation aborted.')));
+        signal?.addEventListener('abort', onAbort, { once: true });
+        if (timeoutMs !== undefined) {
+            timeout = setTimeout(() => settle(() => reject(new Error(`Redis Store operation timed out after ${timeoutMs} ms.`))), timeoutMs);
+        }
+        operation.then(value => settle(() => resolve(value)), error => settle(() => reject(error)));
+    });
+}

package/dist/redis-options.d.ts

@@ -0,0 +1,15 @@
+import type { RedisClientOptions, RedisClientType } from 'redis';
+export interface ZLinkRedisLocationOptions {
+    readonly url?: string;
+    readonly client?: RedisClientType;
+    readonly clientOptions?: RedisClientOptions;
+    readonly keyPrefix: string;
+    readonly operationTimeoutMs?: number;
+}
+export interface ZLinkRedisRelocationOptions {
+    readonly url?: string;
+    readonly client?: RedisClientType;
+    readonly clientOptions?: RedisClientOptions;
+    readonly keyPrefix: string;
+    readonly operationTimeoutMs?: number;
+}

package/dist/redis-options.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/redis-values.d.ts

@@ -0,0 +1,3 @@
+export declare function asArray(value: unknown): readonly unknown[];
+export declare function asString(value: unknown): string;
+export declare function toNumber(value: unknown): number;

package/dist/redis-values.js

@@ -0,0 +1,26 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.asArray = asArray;
+exports.asString = asString;
+exports.toNumber = toNumber;
+function asArray(value) {
+    if (!Array.isArray(value)) {
+        throw new TypeError('Redis command returned a non-array value.');
+    }
+    return value;
+}
+function asString(value) {
+    if (typeof value === 'string') {
+        return value;
+    }
+    if (Buffer.isBuffer(value)) {
+        return value.toString();
+    }
+    if (typeof value === 'number' || typeof value === 'bigint') {
+        return String(value);
+    }
+    throw new TypeError('Redis command returned a non-string value.');
+}
+function toNumber(value) {
+    return Number(asString(value));
+}

package/dist/relocation-store.d.ts

@@ -0,0 +1,14 @@
+import type { ZLinkBlobPutResult, ZLinkBlobReadResult, ZLinkBlobReference, ZLinkBlobRenewResult, ZLinkRelocationStore } from '@zlink-systems/framework';
+import type { ZLinkRedisRelocationOptions } from './redis-options';
+/** Redis implementation of immutable relocation blob storage. */
+export declare class ZLinkRedisRelocationStore implements ZLinkRelocationStore {
+    private readonly connection;
+    private readonly domain;
+    constructor(options: ZLinkRedisRelocationOptions);
+    put(reference: ZLinkBlobReference, payload: Uint8Array, retentionMs: number, signal?: AbortSignal): Promise<ZLinkBlobPutResult>;
+    read(reference: ZLinkBlobReference, signal?: AbortSignal): Promise<ZLinkBlobReadResult>;
+    renew(reference: ZLinkBlobReference, retentionMs: number, signal?: AbortSignal): Promise<ZLinkBlobRenewResult>;
+    delete(reference: ZLinkBlobReference, signal?: AbortSignal): Promise<void>;
+    dispose(): Promise<void>;
+    private blobKey;
+}

package/dist/relocation-store.js

@@ -0,0 +1,103 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ZLinkRedisRelocationStore = void 0;
+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_ENCODED_BLOB_BYTES = 64 * 1024 * 1024 + 23;
+/** Redis implementation of immutable relocation blob storage. */
+class ZLinkRedisRelocationStore {
+    connection;
+    domain;
+    constructor(options) {
+        this.connection = new redis_connection_1.RedisConnection(options);
+        // {prefix}:{zlink-relocation-v1}:blob:{reference}
+        // (23-relocation-store-redis.md#8). Braced for Redis Cluster hash-tag
+        // co-location, matching the dotnet/java reference.
+        this.domain = `${options.keyPrefix}:{zlink-relocation-v1}`;
+    }
+    async put(reference, payload, retentionMs, signal) {
+        const referenceValue = requireReference(reference);
+        requirePayload(payload);
+        const retention = requireRetention(retentionMs);
+        const result = (0, redis_values_1.asArray)(await this.connection.eval(opaque_redis_scripts_1.BLOB_PUT_SCRIPT, [this.blobKey(referenceValue)], [Buffer.from(payload), String(retention)], signal));
+        const kind = (0, redis_values_1.asString)(result[0]);
+        const storeNow = fromUnixMs((0, redis_values_1.toNumber)(result[1]));
+        if (kind === 'conflict')
+            return { kind, storeNow };
+        return {
+            kind: kind === 'alreadyStored' ? 'alreadyStored' : 'stored',
+            storeNow,
+            expiresAt: fromUnixMs((0, redis_values_1.toNumber)(result[2]))
+        };
+    }
+    async read(reference, signal) {
+        const referenceValue = requireReference(reference);
+        const result = (0, redis_values_1.asArray)(await this.connection.eval(opaque_redis_scripts_1.BLOB_READ_SCRIPT, [this.blobKey(referenceValue)], [], signal));
+        const storeNow = fromUnixMs((0, redis_values_1.toNumber)(result[1]));
+        if ((0, redis_values_1.toNumber)(result[0]) !== 1)
+            return { kind: 'missing', storeNow };
+        return {
+            kind: 'found',
+            bytes: Uint8Array.from(asBuffer(result[2])),
+            expiresAt: fromUnixMs((0, redis_values_1.toNumber)(result[3])),
+            storeNow
+        };
+    }
+    async renew(reference, retentionMs, signal) {
+        const referenceValue = requireReference(reference);
+        const retention = requireRetention(retentionMs);
+        const result = (0, redis_values_1.asArray)(await this.connection.eval(opaque_redis_scripts_1.BLOB_RENEW_SCRIPT, [this.blobKey(referenceValue)], [String(retention)], signal));
+        const storeNow = fromUnixMs((0, redis_values_1.toNumber)(result[1]));
+        if ((0, redis_values_1.toNumber)(result[0]) !== 1)
+            return { kind: 'missing', storeNow };
+        return {
+            kind: 'renewed',
+            expiresAt: fromUnixMs((0, redis_values_1.toNumber)(result[2])),
+            storeNow
+        };
+    }
+    async delete(reference, signal) {
+        const referenceValue = requireReference(reference);
+        await this.connection.command(['DEL', this.blobKey(referenceValue)], signal);
+    }
+    async dispose() {
+        await this.connection.dispose();
+    }
+    blobKey(reference) {
+        return `${this.domain}:blob:${reference}`;
+    }
+}
+exports.ZLinkRedisRelocationStore = ZLinkRedisRelocationStore;
+function requireReference(reference) {
+    const value = reference.value;
+    const bytes = Buffer.byteLength(value, 'utf8');
+    if (bytes < 1 || bytes > 4_096) {
+        throw new RangeError('Relocation Store reference must contain 1..4,096 UTF-8 bytes.');
+    }
+    return value;
+}
+function requirePayload(payload) {
+    if (payload.byteLength > MAX_ENCODED_BLOB_BYTES) {
+        throw new RangeError('Relocation Store encoded blob exceeds 64 MiB + 23 bytes.');
+    }
+}
+function requireRetention(retentionMs) {
+    if (!Number.isSafeInteger(retentionMs) || retentionMs < 1) {
+        throw new RangeError('Relocation Store retention must be a positive safe integer.');
+    }
+    return retentionMs;
+}
+function asBuffer(value) {
+    if (Buffer.isBuffer(value))
+        return Buffer.from(value);
+    if (value instanceof Uint8Array)
+        return Buffer.from(value);
+    return Buffer.from((0, redis_values_1.asString)(value), 'utf8');
+}
+function fromUnixMs(value) {
+    if (!Number.isSafeInteger(value) || value < 0) {
+        throw new Error('Redis Store returned an invalid provider timestamp.');
+    }
+    return new Date(value);
+}

package/package.json

@@ -0,0 +1,18 @@
+{
+  "name": "@zlink-systems/framework-locations-redis",
+  "version": "0.10.0",
+  "license": "SEE LICENSE IN LICENSE",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "dependencies": {
+    "@zlink-systems/framework": "0.10.0",
+    "@zlink-systems/zlink": "0.17.3",
+    "redis": "^6.1.0"
+  }
+}

package/src/index.ts

@@ -0,0 +1,3 @@
+export * from './redis-options';
+export * from './opaque-store';
+export * from './relocation-store';

package/src/opaque-redis-scripts.ts

@@ -0,0 +1,337 @@
+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
+`;
+
+export const 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.
+export const 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]
+export const 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]
+export const 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].
+export const 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)}
+`;
+
+export const 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)}
+`;
+
+export const 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)}
+`;