raffel 1.1.73 → 1.1.74

package/dist/cache/tiered.js

@@ -10,8 +10,20 @@ export function isCacheRecord(value) {
         && Number.isFinite(record.version)
         && (record.staleUntil === undefined || Number.isFinite(record.staleUntil))
         && (record.sizeBytes === undefined || Number.isFinite(record.sizeBytes))
+        && (record.tags === undefined || (Array.isArray(record.tags) && record.tags.every((tag) => typeof tag === 'string')))
         && 'value' in record;
 }
+/** Encode and frame a logical namespace for collision-free physical key prefixes. */
+export function cacheNamespacePrefix(namespace) {
+    if (!namespace)
+        throw new Error('Cache namespace cannot be empty');
+    try {
+        return `${encodeURIComponent(namespace)}:`;
+    }
+    catch {
+        throw new Error('Cache namespace must contain valid Unicode');
+    }
+}
 function layerDuration(configured, layer, fallback) {
     if (typeof configured === 'number')
         return configured;
@@ -71,6 +83,8 @@ export function createMemoryCacheLayer(options) {
         throw new Error('Memory cache expirationResolutionMs must be greater than zero');
     }
     const entries = new Map();
+    const entrySizes = new Map();
+    const tagIndex = new Map();
     const maxEntries = options.maxEntries ?? DEFAULT_L1_MAX_ENTRIES;
     const maxMemoryBytes = options.maxMemoryBytes ?? DEFAULT_L1_MAX_MEMORY_BYTES;
     let currentMemoryBytes = 0;
@@ -82,9 +96,17 @@ export function createMemoryCacheLayer(options) {
     });
     function remove(key) {
         const record = entries.get(key);
-        if (record)
-            currentMemoryBytes -= record.sizeBytes ?? 0;
+        if (record) {
+            currentMemoryBytes -= entrySizes.get(key) ?? 0;
+            for (const tag of record.tags ?? []) {
+                const keys = tagIndex.get(tag);
+                keys?.delete(key);
+                if (keys?.size === 0)
+                    tagIndex.delete(tag);
+            }
+        }
         entries.delete(key);
+        entrySizes.delete(key);
         wheel.cancel(key);
     }
     function evictUntilFits(incomingBytes) {
@@ -101,6 +123,10 @@ export function createMemoryCacheLayer(options) {
     }
     return {
         id: options.id,
+        capabilities: {
+            prefixInvalidation: 'scan',
+            tagInvalidation: 'indexed',
+        },
         synchronous: true,
         ttlMs: options.ttlMs,
         get(key) {
@@ -122,20 +148,32 @@ export function createMemoryCacheLayer(options) {
             return record;
         },
         set(key, record, ttlMs, staleMs = 0) {
-            const sizeBytes = record.sizeBytes ?? logicalSize(record.value);
-            if (sizeBytes === undefined)
+            const valueSizeBytes = record.sizeBytes ?? logicalSize(record.value);
+            if (valueSizeBytes === undefined)
                 return;
+            const tags = [...new Set((record.tags ?? []).map((tag) => tag.trim()).filter(Boolean))];
+            const sizeBytes = valueSizeBytes + tags.reduce((total, tag) => total + Buffer.byteLength(tag) + 16, 0);
             remove(key);
             if (!evictUntilFits(sizeBytes))
                 return;
             const expiresAt = Date.now() + ttlMs;
             const stored = {
                 ...record,
-                sizeBytes,
+                sizeBytes: valueSizeBytes,
+                tags: tags.length > 0 ? tags : undefined,
                 expiresAt,
                 staleUntil: staleMs > 0 ? expiresAt + staleMs : undefined,
             };
             entries.set(key, stored);
+            entrySizes.set(key, sizeBytes);
+            for (const tag of stored.tags ?? []) {
+                let keys = tagIndex.get(tag);
+                if (!keys) {
+                    keys = new Set();
+                    tagIndex.set(tag, keys);
+                }
+                keys.add(key);
+            }
             currentMemoryBytes += sizeBytes;
             wheel.schedule(key, stored.staleUntil ?? stored.expiresAt, stored.version);
         },
@@ -143,11 +181,27 @@ export function createMemoryCacheLayer(options) {
             remove(key);
         },
         clearNamespace(namespace) {
+            const prefix = cacheNamespacePrefix(namespace);
             for (const key of entries.keys()) {
-                if (key.startsWith(`${namespace}:`))
+                if (key.startsWith(prefix))
                     remove(key);
             }
         },
+        invalidateTag(tag, namespace) {
+            const prefix = cacheNamespacePrefix(namespace);
+            const keys = [...(tagIndex.get(tag) ?? [])]
+                .filter((key) => key.startsWith(prefix));
+            for (const key of keys)
+                remove(key);
+            return { mode: 'physical', deleted: keys.length };
+        },
+        invalidatePrefix(logicalPrefix, namespace) {
+            const prefix = cacheNamespacePrefix(namespace) + logicalPrefix;
+            const keys = [...entries.keys()].filter((key) => key.startsWith(prefix));
+            for (const key of keys)
+                remove(key);
+            return { mode: 'physical', deleted: keys.length };
+        },
         stats() {
             return { totalItems: entries.size, memoryUsageBytes: currentMemoryBytes, hits, misses };
         },
@@ -165,20 +219,32 @@ export function createTieredCache(options) {
     if (options.operationTimeoutMs !== undefined && options.operationTimeoutMs <= 0) {
         throw new Error('Tiered cache operationTimeoutMs must be greater than zero');
     }
+    const configuredLayerIds = new Set();
     for (const layer of options.layers) {
+        if (configuredLayerIds.has(layer.id)) {
+            throw new Error(`Cache layer id "${layer.id}" is duplicated`);
+        }
+        configuredLayerIds.add(layer.id);
         if (layer.readTimeoutMs !== undefined && layer.readTimeoutMs <= 0) {
             throw new Error(`Cache layer "${layer.id}" readTimeoutMs must be greater than zero`);
         }
         if (layer.operationTimeoutMs !== undefined && layer.operationTimeoutMs <= 0) {
             throw new Error(`Cache layer "${layer.id}" operationTimeoutMs must be greater than zero`);
         }
+        if (layer.capabilities?.distributedFillFencing &&
+            !(layer.beginFill && layer.isFillCurrent && layer.commitFill && layer.bumpGeneration)) {
+            throw new Error(`Cache layer "${layer.id}" distributed fill fencing contract is incomplete`);
+        }
     }
-    const prefix = `${options.namespace}:`;
+    const prefix = cacheNamespacePrefix(options.namespace);
     const layers = [...options.layers];
-    const writeQueues = layers.slice(1).map((layer) => new WriteBehindQueue({
+    const writeQueues = layers.map((layer) => new WriteBehindQueue({
         ...options.writeBehind,
         ...layer.writeBehind,
     }));
+    const allLayerIndexes = layers.map((_layer, index) => index);
+    const layerIndexes = new Map(layers.map((layer, index) => [layer.id, index]));
+    const ticketOwner = {};
     let version = 0;
     let namespaceEpoch = 0;
     let clearInProgress;
@@ -307,6 +373,11 @@ export function createTieredCache(options) {
             releaseKey();
         });
     }
+    function runOrderedWrite(index, key, task) {
+        return layers[index].synchronous
+            ? trackForegroundWrite(key, task)
+            : writeQueues[index].enqueueBarrier(key, task);
+    }
     async function writeLayer(index, key, record, ttlMs, staleMs, capturedNamespaceEpoch, capturedKeyEpoch, capturedWriteVersion) {
         if (isLayerFenced(index, key))
             return;
@@ -338,6 +409,34 @@ export function createTieredCache(options) {
         };
         await withDeadline(layer.set(key, record, ttlMs, staleMs), layer.operationTimeoutMs ?? options.operationTimeoutMs ?? DEFAULT_CACHE_OPERATION_TIMEOUT_MS, `Cache layer "${layer.id}" set timed out`, () => { releaseFence = addLayerFence(index, key); }, cleanupLateWrite);
     }
+    async function commitLayerFill(index, key, record, ttlMs, staleMs, token) {
+        const layer = layers[index];
+        if (isLayerFenced(index, key))
+            return false;
+        return withDeadline(layer.commitFill(key, record, ttlMs, staleMs, token, options.namespace), layer.operationTimeoutMs ?? options.operationTimeoutMs ?? DEFAULT_CACHE_OPERATION_TIMEOUT_MS, `Cache layer "${layer.id}" fill commit timed out`);
+    }
+    function usesDistributedFillFencing(layer) {
+        return Boolean(layer.capabilities?.distributedFillFencing &&
+            layer.beginFill &&
+            layer.isFillCurrent &&
+            layer.commitFill &&
+            layer.bumpGeneration);
+    }
+    async function bumpLayerGenerations(operation) {
+        await Promise.all(layers.map(async (layer, index) => {
+            if (!usesDistributedFillFencing(layer))
+                return;
+            try {
+                await withDeadline(layer.bumpGeneration(options.namespace), layer.operationTimeoutMs ?? options.operationTimeoutMs ??
+                    DEFAULT_CACHE_OPERATION_TIMEOUT_MS, `Cache layer "${layer.id}" generation update timed out`);
+            }
+            catch (error) {
+                markLayerFailure(index);
+                options.onLayerError?.(layer.id, operation, error);
+                throw error;
+            }
+        }));
+    }
     async function deleteLayer(index, key) {
         const layer = layers[index];
         let releaseFence;
@@ -380,6 +479,22 @@ export function createTieredCache(options) {
             throw error;
         }
     }
+    async function invalidateLayerTag(index, tag) {
+        const layer = layers[index];
+        if (!layer.invalidateTag) {
+            throw new Error(`Cache layer "${layer.id}" does not support tag invalidation`);
+        }
+        return withDeadline(layer.invalidateTag(tag, options.namespace), layer.operationTimeoutMs ?? options.operationTimeoutMs ??
+            DEFAULT_CACHE_OPERATION_TIMEOUT_MS, `Cache layer "${layer.id}" tag invalidation timed out`);
+    }
+    async function invalidateLayerPrefix(index, logicalPrefix) {
+        const layer = layers[index];
+        if (!layer.invalidatePrefix) {
+            throw new Error(`Cache layer "${layer.id}" does not support prefix invalidation`);
+        }
+        return withDeadline(layer.invalidatePrefix(logicalPrefix, options.namespace), layer.operationTimeoutMs ?? options.operationTimeoutMs ??
+            DEFAULT_CACHE_OPERATION_TIMEOUT_MS, `Cache layer "${layer.id}" prefix invalidation timed out`);
+    }
     function guardedRead(layer, key) {
         const health = readHealth.get(layer) ?? { failures: 0, openUntil: 0 };
         readHealth.set(layer, health);
@@ -411,143 +526,322 @@ export function createTieredCache(options) {
             return markFailure(error);
         }
     }
-    return {
-        async get(key) {
-            const namespacedKey = prefix + key;
-            let releaseKey;
-            const ensureRetained = () => {
-                releaseKey ??= retainKey(namespacedKey);
-            };
-            try {
-                if (clearInProgress)
-                    await clearInProgress.catch(() => undefined);
-                const deletion = deletions.get(namespacedKey);
-                if (deletion)
-                    await deletion.catch(() => undefined);
-                const capturedNamespaceEpoch = namespaceEpoch;
-                const capturedKeyEpoch = keyEpochs.get(namespacedKey) ?? 0;
-                const capturedWriteVersion = keyWriteVersions.get(namespacedKey);
-                const readIsCurrent = () => namespaceEpoch === capturedNamespaceEpoch &&
-                    (keyEpochs.get(namespacedKey) ?? 0) === capturedKeyEpoch &&
-                    keyWriteVersions.get(namespacedKey) === capturedWriteVersion;
-                let staleHit;
-                for (let index = 0; index < layers.length; index++) {
-                    const layer = layers[index];
-                    if (isLayerFenced(index, namespacedKey))
-                        continue;
-                    let record;
+    async function getFrom(key, selectedIndexes) {
+        const namespacedKey = prefix + key;
+        let releaseKey;
+        const ensureRetained = () => {
+            releaseKey ??= retainKey(namespacedKey);
+        };
+        try {
+            if (clearInProgress)
+                await clearInProgress.catch(() => undefined);
+            const deletion = deletions.get(namespacedKey);
+            if (deletion)
+                await deletion.catch(() => undefined);
+            const capturedNamespaceEpoch = namespaceEpoch;
+            const capturedKeyEpoch = keyEpochs.get(namespacedKey) ?? 0;
+            const capturedWriteVersion = keyWriteVersions.get(namespacedKey);
+            const readIsCurrent = () => namespaceEpoch === capturedNamespaceEpoch &&
+                (keyEpochs.get(namespacedKey) ?? 0) === capturedKeyEpoch &&
+                keyWriteVersions.get(namespacedKey) === capturedWriteVersion;
+            let staleHit;
+            for (let position = 0; position < selectedIndexes.length; position++) {
+                const index = selectedIndexes[position];
+                const layer = layers[index];
+                if (isLayerFenced(index, namespacedKey))
+                    continue;
+                let record;
+                try {
+                    if (layer.synchronous) {
+                        record = layer.get(namespacedKey);
+                    }
+                    else {
+                        ensureRetained();
+                        const candidate = guardedRead(layer, namespacedKey);
+                        record = isThenable(candidate) ? await candidate : candidate;
+                    }
+                }
+                catch (error) {
+                    options.onLayerError?.(layer.id, 'get', error);
+                    continue;
+                }
+                if (!readIsCurrent())
+                    return undefined;
+                if (!record)
+                    continue;
+                const now = Date.now();
+                if (now >= (record.staleUntil ?? record.expiresAt)) {
+                    ensureRetained();
                     try {
-                        if (layer.synchronous) {
-                            record = layer.get(namespacedKey);
-                        }
-                        else {
-                            ensureRetained();
-                            const candidate = guardedRead(layer, namespacedKey);
-                            record = isThenable(candidate) ? await candidate : candidate;
-                        }
+                        await deleteLayer(index, namespacedKey);
                     }
                     catch (error) {
-                        options.onLayerError?.(layer.id, 'get', error);
-                        continue;
+                        options.onLayerError?.(layer.id, 'delete', error);
                     }
-                    if (!readIsCurrent())
-                        return undefined;
-                    if (!record)
-                        continue;
-                    const now = Date.now();
-                    if (now >= (record.staleUntil ?? record.expiresAt)) {
-                        ensureRetained();
-                        try {
-                            await deleteLayer(index, namespacedKey);
-                        }
-                        catch (error) {
-                            options.onLayerError?.(layer.id, 'delete', error);
+                    continue;
+                }
+                const stale = now >= record.expiresAt && now < (record.staleUntil ?? record.expiresAt);
+                if (stale) {
+                    staleHit ??= { value: record.value, layer: layer.id, stale: true };
+                    continue;
+                }
+                if (position > 0) {
+                    await Promise.all(selectedIndexes.slice(0, position).map(async (upperIndex) => {
+                        const upper = layers[upperIndex];
+                        await runOrderedWrite(upperIndex, namespacedKey, async () => {
+                            if (!readIsCurrent())
+                                return;
+                            try {
+                                await writeLayer(upperIndex, namespacedKey, record, upper.ttlMs ?? 60_000, 0, capturedNamespaceEpoch, capturedKeyEpoch, capturedWriteVersion);
+                            }
+                            catch (error) {
+                                options.onLayerError?.(upper.id, 'set', error);
+                            }
+                        });
+                    }));
+                }
+                if (!readIsCurrent())
+                    return undefined;
+                return { value: record.value, layer: layer.id, stale: false };
+            }
+            return readIsCurrent() ? staleHit : undefined;
+        }
+        finally {
+            releaseKey?.();
+        }
+    }
+    async function setTo(key, value, writeOptions, selectedIndexes, fillTicket) {
+        if (clearInProgress)
+            await clearInProgress.catch(() => undefined);
+        const namespacedKey = prefix + key;
+        const deletion = deletions.get(namespacedKey);
+        if (deletion)
+            await deletion.catch(() => undefined);
+        const releaseKey = retainKey(namespacedKey);
+        try {
+            const capturedNamespaceEpoch = namespaceEpoch;
+            const capturedKeyEpoch = keyEpochs.get(namespacedKey) ?? 0;
+            const now = Date.now();
+            const sizeBytes = logicalSize(value);
+            if (sizeBytes === undefined)
+                return false;
+            const tags = [...new Set((writeOptions.tags ?? []).map((tag) => tag.trim()).filter(Boolean))];
+            const record = {
+                value,
+                tags: tags.length > 0 ? tags : undefined,
+                sizeBytes,
+                createdAt: now,
+                expiresAt: now,
+                version: ++version,
+            };
+            let allAccepted = true;
+            keyWriteVersions.set(namespacedKey, record.version);
+            const fencedIndexes = fillTicket
+                ? selectedIndexes.filter((index) => usesDistributedFillFencing(layers[index]))
+                : [];
+            for (const index of fencedIndexes) {
+                const layer = layers[index];
+                const releaseQueuedKey = retainKey(namespacedKey);
+                const write = async () => {
+                    try {
+                        const ttlMs = layerDuration(writeOptions.ttlMs, layer, layer.ttlMs ?? 60_000);
+                        const staleMs = layerDuration(writeOptions.staleMs, layer, 0);
+                        if (!fillTicket.layerTokens.has(index)) {
+                            allAccepted = false;
+                            return;
                         }
-                        continue;
-                    }
-                    const stale = now >= record.expiresAt && now < (record.staleUntil ?? record.expiresAt);
-                    if (stale) {
-                        staleHit ??= { value: record.value, layer: layer.id, stale: true };
-                        continue;
+                        allAccepted = await commitLayerFill(index, namespacedKey, record, ttlMs, staleMs, fillTicket.layerTokens.get(index));
                     }
-                    if (index > 0) {
-                        await Promise.all(layers.slice(0, index).map(async (upper, upperIndex) => {
-                            await trackForegroundWrite(namespacedKey, async () => {
-                                if (!readIsCurrent())
-                                    return;
-                                try {
-                                    await writeLayer(upperIndex, namespacedKey, record, upper.ttlMs ?? 60_000, 0, capturedNamespaceEpoch, capturedKeyEpoch, capturedWriteVersion);
-                                }
-                                catch (error) {
-                                    options.onLayerError?.(upper.id, 'set', error);
-                                }
-                            });
-                        }));
+                    catch (error) {
+                        options.onLayerError?.(layer.id, 'commitFill', error);
+                        allAccepted = false;
                     }
-                    if (!readIsCurrent())
-                        return undefined;
-                    return { value: record.value, layer: layer.id, stale: false };
+                };
+                try {
+                    await writeQueues[index].enqueueBarrier(namespacedKey, write);
                 }
-                return readIsCurrent() ? staleHit : undefined;
-            }
-            finally {
-                releaseKey?.();
+                finally {
+                    releaseQueuedKey();
+                }
+                if (!allAccepted)
+                    return false;
             }
-        },
-        async set(key, value, writeOptions = {}) {
-            if (clearInProgress)
-                await clearInProgress.catch(() => undefined);
-            const namespacedKey = prefix + key;
-            const deletion = deletions.get(namespacedKey);
-            if (deletion)
-                await deletion.catch(() => undefined);
-            const releaseKey = retainKey(namespacedKey);
-            try {
-                const capturedNamespaceEpoch = namespaceEpoch;
-                const capturedKeyEpoch = keyEpochs.get(namespacedKey) ?? 0;
-                const now = Date.now();
-                const sizeBytes = logicalSize(value);
-                if (sizeBytes === undefined)
-                    return;
-                const record = {
-                    value,
-                    sizeBytes,
-                    createdAt: now,
-                    expiresAt: now,
-                    version: ++version,
+            if (namespaceEpoch !== capturedNamespaceEpoch ||
+                (keyEpochs.get(namespacedKey) ?? 0) !== capturedKeyEpoch ||
+                keyWriteVersions.get(namespacedKey) !== record.version)
+                return false;
+            for (const [position, index] of selectedIndexes.entries()) {
+                const layer = layers[index];
+                if (fencedIndexes.includes(index))
+                    continue;
+                const write = async () => {
+                    if (namespaceEpoch !== capturedNamespaceEpoch ||
+                        (keyEpochs.get(namespacedKey) ?? 0) !== capturedKeyEpoch ||
+                        keyWriteVersions.get(namespacedKey) !== record.version)
+                        return;
+                    try {
+                        const ttlMs = layerDuration(writeOptions.ttlMs, layer, layer.ttlMs ?? 60_000);
+                        const staleMs = layerDuration(writeOptions.staleMs, layer, 0);
+                        await writeLayer(index, namespacedKey, record, ttlMs, staleMs, capturedNamespaceEpoch, capturedKeyEpoch, record.version);
+                    }
+                    catch (error) {
+                        options.onLayerError?.(layer.id, 'set', error);
+                    }
                 };
-                keyWriteVersions.set(namespacedKey, record.version);
-                const first = layers[0];
-                if (first) {
-                    await trackForegroundWrite(namespacedKey, async () => {
-                        try {
-                            await writeLayer(0, namespacedKey, record, layerDuration(writeOptions.ttlMs, first, first.ttlMs ?? 60_000), layerDuration(writeOptions.staleMs, first, 0), capturedNamespaceEpoch, capturedKeyEpoch, record.version);
-                        }
-                        catch (error) {
-                            options.onLayerError?.(first.id, 'set', error);
-                        }
-                    });
+                if (position === 0) {
+                    await runOrderedWrite(index, namespacedKey, write);
                 }
-                for (let index = 1; index < layers.length; index++) {
-                    const layer = layers[index];
+                else {
                     const releaseQueuedKey = retainKey(namespacedKey);
-                    writeQueues[index - 1].enqueue(namespacedKey, async () => {
-                        if (namespaceEpoch !== capturedNamespaceEpoch ||
-                            (keyEpochs.get(namespacedKey) ?? 0) !== capturedKeyEpoch ||
-                            keyWriteVersions.get(namespacedKey) !== record.version)
-                            return;
-                        try {
-                            await writeLayer(index, namespacedKey, record, layerDuration(writeOptions.ttlMs, layer, layer.ttlMs ?? 60_000), layerDuration(writeOptions.staleMs, layer, 0), capturedNamespaceEpoch, capturedKeyEpoch, record.version);
-                        }
-                        catch (error) {
-                            options.onLayerError?.(layer.id, 'set', error);
-                        }
-                    }, releaseQueuedKey);
+                    writeQueues[index].enqueue(namespacedKey, write, releaseQueuedKey);
                 }
             }
-            finally {
-                releaseKey();
+            return allAccepted;
+        }
+        finally {
+            releaseKey();
+        }
+    }
+    function beginFillFor(key, selectedIndexes) {
+        const namespacedKey = prefix + key;
+        const ticket = {
+            owner: ticketOwner,
+            key,
+            namespacedKey,
+            namespaceEpoch,
+            keyEpoch: keyEpochs.get(namespacedKey) ?? 0,
+            selectedIndexes,
+            layerTokens: new Map(),
+            captureFailed: false,
+            release: retainKey(namespacedKey),
+            finished: false,
+            ready: Promise.resolve(),
+        };
+        ticket.ready = Promise.all(selectedIndexes.map(async (index) => {
+            const layer = layers[index];
+            if (!usesDistributedFillFencing(layer))
+                return;
+            try {
+                const token = await withDeadline(layer.beginFill(namespacedKey, options.namespace), layer.operationTimeoutMs ?? options.operationTimeoutMs ??
+                    DEFAULT_CACHE_OPERATION_TIMEOUT_MS, `Cache layer "${layer.id}" fill capture timed out`);
+                ticket.layerTokens.set(index, token);
             }
+            catch (error) {
+                ticket.captureFailed = true;
+                options.onLayerError?.(layer.id, 'beginFill', error);
+            }
+        })).then(() => undefined);
+        return ticket;
+    }
+    function finishFill(ticket) {
+        const internal = ticket;
+        if (internal.owner !== ticketOwner) {
+            throw new Error('Cache fill ticket belongs to a different cache');
+        }
+        if (!internal.finished) {
+            internal.finished = true;
+            internal.release();
+        }
+        return internal;
+    }
+    function isLocallyCurrent(internal) {
+        return !internal.finished && !internal.captureFailed &&
+            namespaceEpoch === internal.namespaceEpoch &&
+            (keyEpochs.get(internal.namespacedKey) ?? 0) === internal.keyEpoch;
+    }
+    async function isFillCurrent(ticket) {
+        const internal = ticket;
+        if (internal.owner !== ticketOwner) {
+            throw new Error('Cache fill ticket belongs to a different cache');
+        }
+        await internal.ready;
+        if (!isLocallyCurrent(internal))
+            return false;
+        for (const [index, token] of internal.layerTokens) {
+            const layer = layers[index];
+            if (!layer.isFillCurrent)
+                continue;
+            try {
+                const current = await withDeadline(layer.isFillCurrent(token, options.namespace), layer.readTimeoutMs ?? options.readTimeoutMs ?? DEFAULT_CACHE_READ_TIMEOUT_MS, `Cache layer "${layer.id}" fill validation timed out`);
+                if (!current)
+                    return false;
+            }
+            catch (error) {
+                options.onLayerError?.(layer.id, 'beginFill', error);
+                return false;
+            }
+        }
+        return true;
+    }
+    async function commitFill(ticket, value, writeOptions) {
+        const internal = ticket;
+        try {
+            if (internal.owner !== ticketOwner) {
+                throw new Error('Cache fill ticket belongs to a different cache');
+            }
+            await internal.ready;
+            if (!isLocallyCurrent(internal))
+                return false;
+            return setTo(internal.key, value, writeOptions, internal.selectedIndexes, internal);
+        }
+        finally {
+            finishFill(ticket);
+        }
+    }
+    async function invalidateAcrossLayers(operation, invalidate) {
+        namespaceEpoch++;
+        await bumpLayerGenerations(operation);
+        await Promise.all(foregroundWrites.values());
+        await Promise.all(writeQueues.map((queue) => queue.drain()));
+        const results = await Promise.all(layers.map(async (layer, index) => {
+            try {
+                return [layer.id, await invalidate(index)];
+            }
+            catch (error) {
+                options.onLayerError?.(layer.id, operation, error);
+                throw error;
+            }
+        }));
+        const modes = new Set(results.map(([, result]) => result.mode));
+        return {
+            mode: modes.size === 1 ? results[0][1].mode : 'mixed',
+            deleted: results.reduce((total, [, result]) => total + (result.deleted ?? 0), 0),
+            layers: Object.fromEntries(results),
+        };
+    }
+    return {
+        get: (key) => getFrom(key, allLayerIndexes),
+        set: async (key, value, writeOptions = {}) => {
+            await setTo(key, value, writeOptions, allLayerIndexes);
+        },
+        beginFill: (key) => beginFillFor(key, allLayerIndexes),
+        isFillCurrent,
+        commitFill: (ticket, value, writeOptions = {}) => commitFill(ticket, value, writeOptions),
+        cancelFill: (ticket) => { finishFill(ticket); },
+        selectLayers(layerIds) {
+            if (layerIds.length === 0)
+                throw new Error('A cache layer selection cannot be empty');
+            const selectedIndexes = layerIds.map((id) => {
+                const index = layerIndexes.get(id);
+                if (index === undefined)
+                    throw new Error(`Cache layer "${id}" does not exist`);
+                return index;
+            });
+            for (let index = 1; index < selectedIndexes.length; index++) {
+                if (selectedIndexes[index] <= selectedIndexes[index - 1]) {
+                    throw new Error('Cache profile layers must preserve their configured order');
+                }
+            }
+            return {
+                get: (key) => getFrom(key, selectedIndexes),
+                set: async (key, value, writeOptions = {}) => {
+                    await setTo(key, value, writeOptions, selectedIndexes);
+                },
+                beginFill: (key) => beginFillFor(key, selectedIndexes),
+                isFillCurrent,
+                commitFill: (ticket, value, writeOptions = {}) => commitFill(ticket, value, writeOptions),
+                cancelFill: (ticket) => { finishFill(ticket); },
+            };
         },
         async delete(key) {
             if (clearInProgress)
@@ -561,15 +855,23 @@ export function createTieredCache(options) {
             keyWriteVersions.delete(namespacedKey);
             const operation = (async () => {
                 const errors = [];
-                await foregroundWrites.get(namespacedKey);
                 try {
-                    await deleteLayer(0, namespacedKey);
+                    await bumpLayerGenerations('delete');
                 }
                 catch (error) {
-                    options.onLayerError?.(layers[0].id, 'delete', error);
                     errors.push(error);
                 }
-                await Promise.all(layers.slice(1).map((layer, index) => writeQueues[index].enqueueBarrier(namespacedKey, async () => {
+                await foregroundWrites.get(namespacedKey);
+                await writeQueues[0].enqueueBarrier(namespacedKey, async () => {
+                    try {
+                        await deleteLayer(0, namespacedKey);
+                    }
+                    catch (error) {
+                        options.onLayerError?.(layers[0].id, 'delete', error);
+                        errors.push(error);
+                    }
+                });
+                await Promise.all(layers.slice(1).map((layer, index) => writeQueues[index + 1].enqueueBarrier(namespacedKey, async () => {
                     try {
                         await deleteLayer(index + 1, namespacedKey);
                     }
@@ -593,6 +895,18 @@ export function createTieredCache(options) {
                 releaseKey();
             }
         },
+        async invalidateTag(rawTag) {
+            const tag = rawTag.trim();
+            if (!tag)
+                throw new Error('Cache tag cannot be empty');
+            return invalidateAcrossLayers('invalidateTag', (index) => invalidateLayerTag(index, tag));
+        },
+        async invalidatePrefix(rawPrefix) {
+            const logicalPrefix = rawPrefix.trim();
+            if (!logicalPrefix)
+                throw new Error('Cache prefix cannot be empty; use clearNamespace instead');
+            return invalidateAcrossLayers('invalidatePrefix', (index) => invalidateLayerPrefix(index, logicalPrefix));
+        },
         async clearNamespace() {
             if (clearInProgress)
                 return clearInProgress;
@@ -601,11 +915,18 @@ export function createTieredCache(options) {
             keyWriteVersions.clear();
             const operation = (async () => {
                 const errors = [];
+                try {
+                    await bumpLayerGenerations('clear');
+                }
+                catch (error) {
+                    errors.push(error);
+                }
                 for (const result of await Promise.allSettled(deletions.values())) {
                     if (result.status === 'rejected')
                         errors.push(result.reason);
                 }
                 await Promise.all(foregroundWrites.values());
+                await writeQueues[0].drain();
                 try {
                     await clearLayer(0);
                 }
@@ -614,7 +935,7 @@ export function createTieredCache(options) {
                     errors.push(error);
                 }
                 await Promise.all(layers.slice(1).map(async (layer, index) => {
-                    await writeQueues[index].drain();
+                    await writeQueues[index + 1].drain();
                     try {
                         await clearLayer(index + 1);
                     }
@@ -655,7 +976,7 @@ export function createTieredCache(options) {
                         ]).size,
                     } : {}),
                     fencedKeys: layerFences[index].keys.size + layerFences[index].failedKeys.size,
-                    ...(index > 0 ? { writeQueue: writeQueues[index - 1].stats() } : {}),
+                    ...(index > 0 ? { writeQueue: writeQueues[index].stats() } : {}),
                 };
             });
         },