raffel 1.1.73 → 1.1.74

package/dist/cache/redis-layer.js

@@ -1,9 +1,42 @@
-import { isCacheRecord, } from './tiered.js';
+import { cacheNamespacePrefix, isCacheRecord, } from './tiered.js';
 import { DEFAULT_CACHE_CIRCUIT_COOLDOWN_MS, DEFAULT_CACHE_CIRCUIT_FAILURE_THRESHOLD, DEFAULT_CACHE_OPERATION_TIMEOUT_MS, } from './defaults.js';
+function escapeRedisGlob(value) {
+    return value.replace(/[\\*?\[\]]/g, '\\$&');
+}
+const COMMIT_FILL_SCRIPT = `
+local current = redis.call('GET', KEYS[1]) or '0'
+if current ~= ARGV[1] then return 0 end
+redis.call('SET', KEYS[2], ARGV[2], 'PX', ARGV[3])
+return 1
+`;
 /** Redis/Valkey layer that delegates capacity and eviction to the provider. */
 export function createRedisCacheLayer(options) {
-    const prefix = options.prefix ?? 'raffel:cache:';
-    const fullKey = (key) => prefix + key;
+    let prefix = 'raffel:cache:';
+    if (options.prefix !== undefined) {
+        try {
+            encodeURIComponent(options.prefix);
+        }
+        catch {
+            throw new Error('Redis/Valkey prefix must contain valid Unicode');
+        }
+        prefix = `p${Buffer.byteLength(options.prefix)}:${options.prefix}`;
+    }
+    if (options.clusterHashTag?.includes('{') || options.clusterHashTag?.includes('}')) {
+        throw new Error('Redis/Valkey clusterHashTag cannot contain braces');
+    }
+    if (Boolean(options.clusterHashTag) !== Boolean(options.scanClients)) {
+        throw new Error('Redis/Valkey Cluster requires both clusterHashTag and scanClients');
+    }
+    const storagePrefix = options.clusterHashTag
+        ? `${prefix}{${options.clusterHashTag}}:`
+        : prefix;
+    const dataPrefix = `${storagePrefix}d:`;
+    const fullKey = (key) => dataPrefix + key;
+    const generationKey = (namespace) => (`${storagePrefix}m:g:${Buffer.from(namespace).toString('base64url')}`);
+    const supportsDistributedFillFencing = Boolean(options.client.incr && options.client.eval);
+    const supportsInvalidation = Boolean(options.scanClients ||
+        options.client.scan ||
+        (options.allowBlockingClear && options.client.keys));
     let hits = 0;
     let misses = 0;
     async function setWithNativeTtl(key, value, ttlMs) {
@@ -23,8 +56,78 @@ export function createRedisCacheLayer(options) {
         }
         await options.client.set(key, value, 'PX', ttlMs);
     }
+    async function scanBatches(pattern, visit) {
+        const clients = options.scanClients?.() ?? [options.client];
+        if (clients.length === 0) {
+            throw new Error('Redis/Valkey scanClients returned no cluster masters');
+        }
+        for (const client of clients) {
+            if (!client.scan) {
+                if (options.allowBlockingClear && client.keys) {
+                    const keys = await client.keys(pattern);
+                    if (keys.length > 0)
+                        await visit(client, keys);
+                    continue;
+                }
+                throw new Error('Redis/Valkey namespace invalidation requires SCAN support');
+            }
+            let cursor = '0';
+            do {
+                const result = options.clientStyle === 'node-redis' || client.pSetEx
+                    ? await client.scan(cursor, {
+                        MATCH: pattern,
+                        COUNT: options.scanCount ?? 100,
+                    })
+                    : await client.scan(cursor, 'MATCH', pattern, 'COUNT', options.scanCount ?? 100);
+                const next = Array.isArray(result) ? result[0] : result.cursor;
+                const keys = Array.isArray(result) ? result[1] : result.keys;
+                cursor = String(next);
+                if (keys.length > 0)
+                    await visit(client, keys);
+            } while (cursor !== '0');
+        }
+    }
+    async function deleteScannedKeys(client, keys) {
+        if (!options.scanClients)
+            return client.del(keys);
+        const deleted = await Promise.all(keys.map((key) => client.del(key)));
+        return deleted.reduce((total, count) => total + count, 0);
+    }
+    async function deletePattern(pattern) {
+        let deleted = 0;
+        await scanBatches(pattern, async (client, keys) => {
+            deleted += await deleteScannedKeys(client, keys);
+        });
+        return deleted;
+    }
+    function storedRecord(record, ttlMs, staleMs) {
+        const expiresAt = Date.now() + ttlMs;
+        return {
+            ...record,
+            expiresAt,
+            staleUntil: staleMs > 0 ? expiresAt + staleMs : undefined,
+        };
+    }
+    async function commitFillAtomically(key, record, ttlMs, staleMs, token, namespace) {
+        const encoded = JSON.stringify(storedRecord(record, ttlMs, staleMs));
+        const providerKey = fullKey(key);
+        const generation = generationKey(namespace);
+        const duration = String(ttlMs + staleMs);
+        const result = options.clientStyle === 'node-redis' || options.client.pSetEx
+            ? await options.client.eval(COMMIT_FILL_SCRIPT, {
+                keys: [generation, providerKey],
+                arguments: [String(token), encoded, duration],
+            })
+            : await options.client.eval(COMMIT_FILL_SCRIPT, 2, generation, providerKey, String(token), encoded, duration);
+        return Number(result) === 1;
+    }
     return {
         id: options.id,
+        capabilities: {
+            distributedFillFencing: supportsDistributedFillFencing,
+            prefixInvalidation: supportsInvalidation ? 'scan' : false,
+            tagInvalidation: supportsInvalidation ? 'scan' : false,
+        },
         ttlMs: options.ttlMs,
         readTimeoutMs: options.readTimeoutMs ?? 100,
         operationTimeoutMs: options.operationTimeoutMs ?? DEFAULT_CACHE_OPERATION_TIMEOUT_MS,
@@ -59,42 +162,56 @@ export function createRedisCacheLayer(options) {
             return record;
         },
         async set(key, record, ttlMs, staleMs = 0) {
-            const expiresAt = Date.now() + ttlMs;
-            const stored = {
-                ...record,
-                expiresAt,
-                staleUntil: staleMs > 0 ? expiresAt + staleMs : undefined,
-            };
+            const stored = storedRecord(record, ttlMs, staleMs);
             await setWithNativeTtl(fullKey(key), JSON.stringify(stored), ttlMs + staleMs);
         },
+        ...(supportsDistributedFillFencing ? {
+            async beginFill(_key, namespace) {
+                return await options.client.get(generationKey(namespace)) ?? '0';
+            },
+            async isFillCurrent(token, namespace) {
+                const current = await options.client.get(generationKey(namespace)) ?? '0';
+                return current === String(token);
+            },
+            commitFill: commitFillAtomically,
+            async bumpGeneration(namespace) {
+                await options.client.incr(generationKey(namespace));
+            },
+        } : {}),
         async delete(key) {
             await options.client.del(fullKey(key));
         },
         async clearNamespace(namespace) {
-            const pattern = `${prefix}${namespace}:*`;
-            if (!options.client.scan) {
-                if (options.allowBlockingClear && options.client.keys) {
-                    const keys = await options.client.keys(pattern);
-                    if (keys.length > 0)
-                        await options.client.del(keys);
-                    return;
-                }
-                throw new Error('Redis/Valkey namespace invalidation requires SCAN support');
-            }
-            let cursor = '0';
-            do {
-                const result = options.clientStyle === 'node-redis' || options.client.pSetEx
-                    ? await options.client.scan(cursor, {
-                        MATCH: pattern,
-                        COUNT: options.scanCount ?? 100,
-                    })
-                    : await options.client.scan(cursor, 'MATCH', pattern, 'COUNT', options.scanCount ?? 100);
-                const next = Array.isArray(result) ? result[0] : result.cursor;
-                const keys = Array.isArray(result) ? result[1] : result.keys;
-                cursor = String(next);
-                if (keys.length > 0)
-                    await options.client.del(keys);
-            } while (cursor !== '0');
+            const namespacePrefix = dataPrefix + cacheNamespacePrefix(namespace);
+            await deletePattern(`${escapeRedisGlob(namespacePrefix)}*`);
+        },
+        async invalidatePrefix(logicalPrefix, namespace) {
+            const namespacePrefix = dataPrefix + cacheNamespacePrefix(namespace);
+            const pattern = `${escapeRedisGlob(namespacePrefix + logicalPrefix)}*`;
+            return { mode: 'physical', deleted: await deletePattern(pattern) };
+        },
+        async invalidateTag(tag, namespace) {
+            const namespacePrefix = dataPrefix + cacheNamespacePrefix(namespace);
+            const pattern = `${escapeRedisGlob(namespacePrefix)}*`;
+            let deleted = 0;
+            await scanBatches(pattern, async (client, keys) => {
+                const records = await Promise.all(keys.map(async (key) => {
+                    const encoded = await client.get(key);
+                    if (!encoded)
+                        return undefined;
+                    try {
+                        const record = JSON.parse(encoded);
+                        return isCacheRecord(record) ? record : undefined;
+                    }
+                    catch {
+                        return undefined;
+                    }
+                }));
+                const matches = keys.filter((_key, index) => records[index]?.tags?.includes(tag));
+                if (matches.length > 0)
+                    deleted += await deleteScannedKeys(client, matches);
+            });
+            return { mode: 'physical', deleted };
         },
         stats() {
             return { totalItems: 0, hits, misses };

package/dist/cache/redis-layer.js.map

@@ -1 +1 @@
-{"version":3,"file":"redis-layer.js","sourceRoot":"","sources":["../../src/cache/redis-layer.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"redis-layer.js","sourceRoot":"","sources":["../../src/cache/redis-layer.ts"],"names":[],"mappings":"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"}

package/dist/cache/server-runtime.d.ts

@@ -1,11 +1,17 @@
 import type { Context, Interceptor } from '../types/index.js';
-import { type CacheIdentityScope } from './key.js';
-import { type CacheCircuitBreakerOptions, type CacheWriteOptions, type TieredCache, type TieredCacheOptions } from './tiered.js';
+import { type ProcedureCacheKeyOptions } from './key.js';
+import { type CacheCircuitBreakerOptions, type CacheInvalidationResult, type TieredCacheAccess, type CacheWriteOptions, type TieredCache, type TieredCacheOptions } from './tiered.js';
 import type { WriteBehindQueueOptions } from './write-behind-queue.js';
-export interface RouteCacheConfig extends CacheWriteOptions {
+export type CacheTagResolver = readonly string[] | ((input: unknown, ctx: Context, result: unknown) => readonly string[]);
+export interface RouteCacheConfig extends Omit<CacheWriteOptions, 'tags'>, ProcedureCacheKeyOptions {
     enabled?: boolean;
-    scope?: CacheIdentityScope;
-    version?: string;
+    profile?: string;
+    tags?: CacheTagResolver;
+}
+export interface CacheProfileConfig extends Omit<CacheWriteOptions, 'tags'> {
+    layers: string[];
+    /** Coherence guarantee promised by this profile's selected topology. */
+    coherence?: 'ttl' | 'shared-invalidation' | 'backplane';
 }
 export interface CacheRule extends RouteCacheConfig {
     match: string;
@@ -43,29 +49,36 @@ export interface ServerCacheConfig {
     enabled: boolean;
     namespace?: string;
     layers: ServerCacheLayerConfig[];
+    profiles?: Readonly<Record<string, CacheProfileConfig>>;
     rules?: CacheRule[];
     writeBehind?: WriteBehindQueueOptions;
     onLayerError?: TieredCacheOptions['onLayerError'];
 }
 export interface ServerCacheController {
     invalidate(key: string): Promise<void>;
+    invalidateTag(tag: string): Promise<CacheInvalidationResult>;
+    invalidatePrefix(prefix: string): Promise<CacheInvalidationResult>;
     clear(): Promise<void>;
-    keyForProcedure(procedure: string, input: unknown, ctx: Context, options?: Pick<RouteCacheConfig, 'scope' | 'version'>): string | undefined;
-    invalidateProcedure(procedure: string, input: unknown, ctx: Context, options?: Pick<RouteCacheConfig, 'scope' | 'version'>): Promise<boolean>;
+    keyForProcedure(procedure: string, input: unknown, ctx: Context, options?: ProcedureCacheKeyOptions): string | undefined;
+    /** @deprecated Prefer dependency tags or logical-prefix invalidation. */
+    invalidateProcedure(procedure: string, input: unknown, ctx: Context, options?: ProcedureCacheKeyOptions): Promise<boolean>;
     stats(): ReturnType<TieredCache['stats']>;
 }
 export declare class ServerCacheRuntime {
     private readonly config;
     private current;
+    private readonly profileCaches;
+    private readonly layersById;
     private binders;
+    private providersValidated;
     private readonly pending;
     readonly controller: ServerCacheController;
     constructor(config: ServerCacheConfig);
     get cache(): TieredCache;
     interceptorFor(procedure: string, explicit?: RouteCacheConfig | false): Interceptor | undefined;
     bind(services: Readonly<Record<string, unknown>>): void;
-    executeOnce(key: string, next: () => Promise<unknown>, config: RouteCacheConfig): Promise<unknown>;
-    revalidate(key: string, next: () => Promise<unknown>, config: RouteCacheConfig): void;
+    executeOnce(key: string, next: () => Promise<unknown>, writeOptions: CacheWriteOptions | ((value: unknown) => CacheWriteOptions | undefined), cache?: TieredCacheAccess, planId?: string): Promise<unknown>;
+    revalidate(key: string, next: () => Promise<unknown>, writeOptions: CacheWriteOptions | ((value: unknown) => CacheWriteOptions | undefined), cache?: TieredCacheAccess, planId?: string): void;
     start(): void;
     stop(): Promise<void>;
 }

package/dist/cache/server-runtime.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"server-runtime.d.ts","sourceRoot":"","sources":["../../src/cache/server-runtime.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"server-runtime.d.ts","sourceRoot":"","sources":["../../src/cache/server-runtime.ts"],"names":[],"mappings":"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"}

package/dist/cache/server-runtime.js

@@ -1,9 +1,10 @@
 import { matchProcedurePattern } from '../utils/pattern-match.js';
 import { createFileSystemCacheLayer } from './fs-layer.js';
-import { procedureCacheKey, procedureCacheKeyFor } from './key.js';
+import { compileProcedureCacheKey, procedureCacheKeyFor, } from './key.js';
 import { createMemoryCacheLayer, createTieredCache, } from './tiered.js';
 function providerLayer(config, id) {
     let delegate;
+    let capabilities = { distributedFillFencing: false };
     const requireDelegate = () => {
         if (!delegate)
             throw new Error(`Cache provider "${config.provider}" is not available`);
@@ -19,10 +20,26 @@ function providerLayer(config, id) {
                 'delete' in candidate &&
                 'clearNamespace' in candidate) {
                 delegate = candidate;
+                const hasCompleteFencing = Boolean(delegate.capabilities?.distributedFillFencing &&
+                    delegate.beginFill &&
+                    delegate.isFillCurrent &&
+                    delegate.commitFill &&
+                    delegate.bumpGeneration);
+                capabilities = {
+                    ...delegate.capabilities,
+                    distributedFillFencing: hasCompleteFencing,
+                    tagInvalidation: delegate.invalidateTag
+                        ? delegate.capabilities?.tagInvalidation ?? false
+                        : false,
+                    prefixInvalidation: delegate.invalidatePrefix
+                        ? delegate.capabilities?.prefixInvalidation ?? false
+                        : false,
+                };
             }
         },
         layer: {
             id,
+            get capabilities() { return capabilities; },
             ttlMs: config.ttlMs ?? 60 * 60_000,
             writeBehind: config.writeBehind,
             readTimeoutMs: config.timeoutMs ?? 100,
@@ -34,6 +51,47 @@ function providerLayer(config, id) {
             set: (key, record, ttlMs, staleMs) => requireDelegate().set(key, record, ttlMs, staleMs),
             delete: (key) => requireDelegate().delete(key),
             clearNamespace: (namespace) => requireDelegate().clearNamespace(namespace),
+            async beginFill(key, namespace) {
+                const candidate = requireDelegate();
+                if (!candidate.beginFill || !candidate.commitFill)
+                    return { fenced: false };
+                return { fenced: true, token: await candidate.beginFill(key, namespace) };
+            },
+            async isFillCurrent(token, namespace) {
+                const captured = token;
+                if (!captured.fenced)
+                    return true;
+                const candidate = requireDelegate();
+                return candidate.isFillCurrent
+                    ? candidate.isFillCurrent(captured.token, namespace)
+                    : true;
+            },
+            async commitFill(key, record, ttlMs, staleMs, token, namespace) {
+                const captured = token;
+                const candidate = requireDelegate();
+                if (!captured.fenced || !candidate.commitFill) {
+                    await candidate.set(key, record, ttlMs, staleMs);
+                    return true;
+                }
+                return candidate.commitFill(key, record, ttlMs, staleMs, captured.token, namespace);
+            },
+            async bumpGeneration(namespace) {
+                await requireDelegate().bumpGeneration?.(namespace);
+            },
+            invalidateTag: (tag, namespace) => {
+                const candidate = requireDelegate().invalidateTag;
+                if (!candidate) {
+                    throw new Error(`Cache provider "${config.provider}" does not support tag invalidation`);
+                }
+                return candidate.call(requireDelegate(), tag, namespace);
+            },
+            invalidatePrefix: (prefix, namespace) => {
+                const candidate = requireDelegate().invalidatePrefix;
+                if (!candidate) {
+                    throw new Error(`Cache provider "${config.provider}" does not support prefix invalidation`);
+                }
+                return candidate.call(requireDelegate(), prefix, namespace);
+            },
             stats: () => delegate?.stats?.() ?? { totalItems: 0 },
             shutdown: () => delegate?.shutdown?.(),
         },
@@ -48,32 +106,57 @@ function isSuccessful(value) {
 function cloneResponse(value) {
     return value instanceof Response ? value.clone() : value;
 }
-function createProcedureInterceptor(runtime, config) {
+function routeWriteOptions(config, envelope, ctx, result) {
+    const tags = typeof config.tags === 'function'
+        ? config.tags(envelope.payload, ctx, result)
+        : config.tags;
+    return {
+        ttlMs: config.ttlMs,
+        staleMs: config.staleMs,
+        tags,
+    };
+}
+function createProcedureInterceptor(runtime, procedure, config, cache, planId) {
+    const keyFor = compileProcedureCacheKey(procedure, config);
     return async (envelope, ctx, next) => {
         runtime.bind(ctx.services);
-        const key = procedureCacheKey(envelope, ctx, config);
+        const key = keyFor(envelope.payload, ctx);
         if (!key)
             return next();
-        const hit = await runtime.cache.get(key);
+        const hit = await cache.get(key);
         if (hit && !hit.stale)
             return hit.value;
+        const writeOptions = (result) => {
+            try {
+                return routeWriteOptions(config, envelope, ctx, result);
+            }
+            catch (error) {
+                ctx.logger.warn({ error, procedure: envelope.procedure }, 'Cache tag resolver failed; the result was not cached');
+                return undefined;
+            }
+        };
         if (hit?.stale) {
-            runtime.revalidate(key, next, config);
+            runtime.revalidate(key, next, writeOptions, cache, planId);
             return hit.value;
         }
-        return runtime.executeOnce(key, next, config);
+        return runtime.executeOnce(key, next, writeOptions, cache, planId);
     };
 }
 export class ServerCacheRuntime {
     config;
     current;
+    profileCaches = new Map();
+    layersById = new Map();
     binders = [];
+    providersValidated = false;
     pending = new Map();
     controller;
     constructor(config) {
         this.config = config;
         this.controller = {
             invalidate: (key) => this.cache.delete(key),
+            invalidateTag: (tag) => this.cache.invalidateTag(tag),
+            invalidatePrefix: (prefix) => this.cache.invalidatePrefix(prefix),
             clear: () => this.cache.clearNamespace(),
             keyForProcedure: (procedure, input, ctx, options) => procedureCacheKeyFor(procedure, input, ctx, options),
             invalidateProcedure: async (procedure, input, ctx, options) => {
@@ -93,7 +176,7 @@ export class ServerCacheRuntime {
         return this.current;
     }
     interceptorFor(procedure, explicit) {
-        const resolved = { enabled: false };
+        const resolved = {};
         for (const rule of this.config.rules ?? []) {
             if (matchProcedurePattern(rule.match, procedure))
                 Object.assign(resolved, rule);
@@ -102,36 +185,93 @@ export class ServerCacheRuntime {
             resolved.enabled = false;
         else if (explicit)
             Object.assign(resolved, explicit);
-        return resolved.enabled ? createProcedureInterceptor(this, resolved) : undefined;
+        if (resolved.enabled === undefined)
+            resolved.enabled = Boolean(resolved.profile);
+        if (!resolved.enabled)
+            return undefined;
+        const profileName = resolved.profile;
+        if (!profileName) {
+            return createProcedureInterceptor(this, procedure, resolved, this.cache, 'default');
+        }
+        const profile = this.config.profiles?.[profileName];
+        if (!profile)
+            throw new Error(`Cache profile "${profileName}" does not exist`);
+        let cache = this.profileCaches.get(profileName);
+        if (!cache) {
+            cache = this.cache.selectLayers(profile.layers);
+            this.profileCaches.set(profileName, cache);
+        }
+        const { layers: _layers, ...profileDefaults } = profile;
+        const effective = { ...profileDefaults, ...resolved };
+        return createProcedureInterceptor(this, procedure, effective, cache, profileName);
     }
     bind(services) {
+        if (this.providersValidated)
+            return;
         for (const binder of this.binders)
             binder.bind(services);
+        for (const [profileName, profile] of Object.entries(this.config.profiles ?? {})) {
+            if (profile.coherence !== 'shared-invalidation')
+                continue;
+            for (const id of profile.layers) {
+                const layer = this.layersById.get(id);
+                if (!layer.capabilities?.distributedFillFencing) {
+                    throw new Error(`Cache profile "${profileName}" requires distributed fill fencing on layer "${id}"`);
+                }
+                if (!layer.capabilities.tagInvalidation || !layer.capabilities.prefixInvalidation) {
+                    throw new Error(`Cache profile "${profileName}" requires tag and prefix invalidation on layer "${id}"`);
+                }
+            }
+        }
+        this.providersValidated = true;
     }
-    executeOnce(key, next, config) {
-        const existing = this.pending.get(key);
-        if (existing)
-            return existing.then(cloneResponse);
-        const execution = next()
+    executeOnce(key, next, writeOptions, cache = this.cache, planId = 'default') {
+        const pendingKey = `${planId}\0${key}`;
+        const existing = this.pending.get(pendingKey);
+        if (existing) {
+            return existing.cache.isFillCurrent(existing.ticket).then((current) => {
+                if (current)
+                    return existing.execution.then(cloneResponse);
+                if (this.pending.get(pendingKey) === existing)
+                    this.pending.delete(pendingKey);
+                return this.executeOnce(key, next, writeOptions, cache, planId);
+            });
+        }
+        const ticket = cache.beginFill(key);
+        const execution = Promise.resolve()
+            .then(() => ticket.ready)
+            .then(next)
             .then(async (value) => {
-            if (isSuccessful(value))
-                await this.cache.set(key, value, config);
+            if (isSuccessful(value)) {
+                const resolved = typeof writeOptions === 'function'
+                    ? writeOptions(value)
+                    : writeOptions;
+                if (resolved)
+                    await cache.commitFill(ticket, value, resolved);
+            }
             return value;
         })
-            .finally(() => this.pending.delete(key));
-        this.pending.set(key, execution);
+            .finally(() => {
+            cache.cancelFill(ticket);
+            if (this.pending.get(pendingKey)?.execution === execution) {
+                this.pending.delete(pendingKey);
+            }
+        });
+        this.pending.set(pendingKey, { cache, execution, ticket });
         return execution.then(cloneResponse);
     }
-    revalidate(key, next, config) {
-        if (this.pending.has(key))
-            return;
-        void this.executeOnce(key, next, config).catch(() => undefined);
+    revalidate(key, next, writeOptions, cache = this.cache, planId = 'default') {
+        void this.executeOnce(key, next, writeOptions, cache, planId).catch(() => undefined);
     }
     start() {
         if (this.current)
             return;
         this.binders = [];
+        this.providersValidated = false;
+        this.profileCaches.clear();
+        this.layersById.clear();
         const layers = [];
+        const layerConfigsById = new Map();
         const ids = new Set();
         for (const [index, layer] of this.config.layers.entries()) {
             if (layer.enabled === false)
@@ -140,6 +280,7 @@ export class ServerCacheRuntime {
             if (ids.has(id))
                 throw new Error(`Cache layer id "${id}" is duplicated`);
             ids.add(id);
+            layerConfigsById.set(id, layer);
             if (layer.ttlMs !== undefined && layer.ttlMs <= 0) {
                 throw new Error(`Cache layer "${id}" ttlMs must be greater than zero`);
             }
@@ -195,19 +336,46 @@ export class ServerCacheRuntime {
                 this.binders.push(bound);
                 layers.push(bound.layer);
             }
+            this.layersById.set(id, layers.at(-1));
         }
         if (layers.length === 0)
             throw new Error('At least one cache layer must be enabled');
-        this.current = createTieredCache({
+        const cache = createTieredCache({
             namespace: this.config.namespace ?? 'raffel',
             layers,
             writeBehind: this.config.writeBehind,
             onLayerError: this.config.onLayerError,
         });
+        for (const [profileName, profile] of Object.entries(this.config.profiles ?? {})) {
+            try {
+                const selected = cache.selectLayers(profile.layers);
+                if (profile.coherence === 'backplane') {
+                    throw new Error(`Cache profile "${profileName}" requires an invalidation backplane, which is not configured`);
+                }
+                if (profile.coherence === 'shared-invalidation') {
+                    const configuredLayers = profile.layers.map((id) => layerConfigsById.get(id));
+                    if (configuredLayers.some((layer) => layer?.driver !== 'provider')) {
+                        throw new Error(`Cache profile "${profileName}" with shared-invalidation coherence can only use provider layers`);
+                    }
+                    if (configuredLayers.length !== 1) {
+                        throw new Error(`Cache profile "${profileName}" with shared-invalidation coherence requires exactly one provider layer`);
+                    }
+                }
+                this.profileCaches.set(profileName, selected);
+            }
+            catch (error) {
+                void cache.shutdown();
+                throw error;
+            }
+        }
+        this.current = cache;
     }
     async stop() {
         const cache = this.current;
         this.current = undefined;
+        this.profileCaches.clear();
+        this.layersById.clear();
+        this.providersValidated = false;
         if (cache)
             await cache.shutdown();
     }