@sequenceholdings/artifact-studio 0.2.6 → 0.3.1

package/dist/next-cache/components.js

@@ -0,0 +1,113 @@
+import { z } from 'zod';
+import { CacheAdapterRuntime, nextWriteTicket } from './adapter-runtime.js';
+import { createCacheStream, deserializeCacheValue, readCacheStream, serializeCacheValue } from './serialization.js';
+import { normalizeCacheTags } from './store.js';
+const metadataSchema = z.object({
+    tags: z.array(z.string()), stale: z.number().finite().nonnegative(),
+    timestamp: z.number().finite().nonnegative(), expire: z.number().finite(),
+    revalidate: z.number().finite(),
+});
+const recordSchema = metadataSchema.extend({ format: z.literal('component-v1'), bytes: z.instanceof(Uint8Array) });
+function discardStream(value) {
+    void value.cancel().catch(() => { });
+}
+async function awaitEntry({ pending, timeoutMs }) {
+    let timer;
+    try {
+        return await Promise.race([pending, new Promise((_, reject) => {
+                timer = setTimeout(() => reject(new Error('Pending Next cache entry timed out')), timeoutMs);
+            })]);
+    }
+    catch (error) {
+        void pending.then((entry) => discardStream(entry.value), () => { });
+        throw error;
+    }
+    finally {
+        clearTimeout(timer);
+    }
+}
+export function createComponentCacheHandler(options) {
+    const runtime = new CacheAdapterRuntime(options);
+    // Process-wide and bounded to 512 keys, so it holds write tickets only, never cached payloads.
+    const tickets = new Map();
+    const pendingSets = new Map();
+    async function persist({ key, pending, lookup }) {
+        let stream;
+        try {
+            const entry = await awaitEntry({ pending, timeoutMs: runtime.streamTimeoutMs });
+            stream = entry.value;
+            if (!lookup) {
+                discardStream(entry.value);
+                return;
+            }
+            const metadata = metadataSchema.parse(entry);
+            const ttlMs = Math.min(runtime.maxEntryAgeMs, Math.ceil(metadata.timestamp + metadata.expire * 1000 - runtime.now()));
+            // Do not let an older render consume a newer generation's write ticket.
+            if (metadata.timestamp < lookup.observedAt || ttlMs <= 0) {
+                discardStream(entry.value);
+                return;
+            }
+            const tags = normalizeCacheTags(metadata.tags);
+            const bytes = await readCacheStream({ stream: entry.value, maxBytes: runtime.maxEntryBytes, timeoutMs: runtime.streamTimeoutMs });
+            const payload = serializeCacheValue({ value: { ...metadata, format: 'component-v1', bytes }, limits: { maxBytes: runtime.maxEntryBytes } });
+            await runtime.store.commit({ namespace: runtime.namespace, key: `component:${key}`, ticket: lookup.ticket, payload, tags, ttlMs });
+        }
+        catch {
+            if (stream && !stream.locked)
+                discardStream(stream);
+            runtime.report('write');
+        }
+    }
+    return {
+        async get(key, softTags) {
+            try {
+                await pendingSets.get(key);
+                const lookup = await runtime.read({ key: `component:${key}`, tags: normalizeCacheTags(softTags) });
+                if (!lookup)
+                    return undefined;
+                // Payload-free: a hit that is never re-rendered must not pin its serialized entry here. A ticket
+                // left by an earlier hit is replaced once the store has moved past it (invalidation, another
+                // commit, or age), so the first regeneration after an invalidation can actually commit.
+                const retained = tickets.get(key);
+                const next = nextWriteTicket({ retained, lookup, now: runtime.now() });
+                if (next !== retained) {
+                    if (!retained && tickets.size >= 512)
+                        tickets.delete(tickets.keys().next().value ?? '');
+                    tickets.set(key, next);
+                }
+                if (!lookup.entry)
+                    return undefined;
+                const record = recordSchema.parse(deserializeCacheValue({ serialized: lookup.entry.payload, limits: { maxBytes: runtime.maxEntryBytes } }));
+                if (record.expire <= 0 || runtime.now() >= record.timestamp + record.expire * 1000)
+                    return undefined;
+                return { tags: record.tags, stale: record.stale, timestamp: record.timestamp,
+                    expire: record.expire, revalidate: lookup.entry.stale ? -1 : record.revalidate,
+                    value: createCacheStream({ bytes: record.bytes }) };
+            }
+            catch {
+                runtime.report('read');
+                return undefined;
+            }
+        },
+        async set(key, pendingEntry) {
+            const lookup = tickets.get(key);
+            tickets.delete(key);
+            if (pendingSets.has(key) || pendingSets.size >= 128) {
+                await persist({ key, pending: pendingEntry });
+                return;
+            }
+            const pending = persist({ key, pending: pendingEntry, lookup });
+            pendingSets.set(key, pending);
+            try {
+                await pending;
+            }
+            finally {
+                if (pendingSets.get(key) === pending)
+                    pendingSets.delete(key);
+            }
+        },
+        async refreshTags() { },
+        async getExpiration() { return Infinity; }, // Next passes soft tags into get().
+        async updateTags(tags, durations) { await runtime.invalidate({ tags, durations }); },
+    };
+}

package/dist/next-cache/config.d.ts

@@ -0,0 +1,9 @@
+export { artifactNextCacheBindingSchema, verifyArtifactNextCacheReadiness } from './runtime.js';
+type Config = Record<string, unknown>;
+type ConfigInput<T extends object> = T | ((phase: string, context: unknown) => T | Promise<T>);
+/** Always compiled into standalone output; runtime mode is selected only at boot. */
+export declare function withArtifactNextConfig<T extends object>(input: ConfigInput<T>): (phase: string, context: unknown) => Promise<T & Config>;
+/** Runs only inside the isolated compile sandbox, never in the control-plane worker. */
+export declare function installArtifactNextCacheConfig({ projectRoot }: {
+    projectRoot: string;
+}): Promise<void>;

package/dist/next-cache/config.js

@@ -0,0 +1,105 @@
+import { readFile, readdir, rename, writeFile } from 'node:fs/promises';
+import { dirname, join, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { load as parseYaml } from 'js-yaml';
+import { isNextArtifactManifest, parseArtifactStudioManifest } from '../manifest.js';
+import { resolveArtifactNextImages } from '../next-image-config.js';
+export { artifactNextCacheBindingSchema, verifyArtifactNextCacheReadiness } from './runtime.js';
+const MARKER = '// Generated by Atlas Artifact Studio; original configuration is preserved.';
+function configured(config, egress) {
+    const deploymentId = process.env.ARTIFACT_NEXT_BUILD_ID;
+    if (deploymentId !== undefined && (deploymentId.length < 1 || deploymentId.length > 128 || /[^A-Za-z0-9_-]/.test(deploymentId)))
+        throw new Error('Invalid platform build identifier');
+    if (Reflect.get(config, 'deploymentId') !== undefined && Reflect.get(config, 'deploymentId') !== deploymentId)
+        throw new Error('Artifact Studio owns the Next deploymentId configuration');
+    for (const [name, supported] of Object.entries({ basePath: '', assetPrefix: '', distDir: '.next', output: 'standalone' })) {
+        const value = Reflect.get(config, name);
+        if (value !== undefined && value !== supported)
+            throw new Error(`Artifact Studio requires ${name}=${JSON.stringify(supported)} for managed routing and standalone packaging`);
+    }
+    const incremental = fileURLToPath(new URL('./incremental-handler.js', import.meta.url));
+    const components = fileURLToPath(new URL('./component-handler.js', import.meta.url));
+    const existing = Reflect.get(config, 'cacheHandler');
+    const handlers = Reflect.get(config, 'cacheHandlers');
+    if (existing !== undefined && existing !== incremental)
+        throw new Error('Artifact Studio owns the Next cacheHandler configuration');
+    if (handlers !== undefined && (typeof handlers !== 'object' || handlers === null
+        || Object.entries(handlers).some(([key, value]) => !['default', 'remote'].includes(key) || value !== components))) {
+        throw new Error('Artifact Studio owns the Next cacheHandlers configuration');
+    }
+    if (!Array.isArray(egress) || !egress.every((host) => typeof host === 'string'))
+        throw new Error('Invalid Artifact image egress policy');
+    const images = resolveArtifactNextImages({ images: Reflect.get(config, 'images'), egressHosts: egress });
+    return { ...config, output: 'standalone', cacheMaxMemorySize: 0,
+        ...(deploymentId ? { deploymentId } : {}),
+        cacheHandler: incremental, cacheHandlers: { default: components, remote: components },
+        images: { ...images, customCacheHandler: true } };
+}
+/**
+ * seq-studio and the hosted build supply the application's egress policy. A plain local
+ * `next build` or `next dev` reads the same declaration from the application's manifest.
+ */
+async function allowedEgress(config) {
+    const supplied = process.env.ARTIFACT_NEXT_ALLOWED_EGRESS;
+    if (supplied !== undefined)
+        return JSON.parse(supplied);
+    const images = Reflect.get(config, 'images');
+    const patterns = typeof images === 'object' && images !== null ? Reflect.get(images, 'remotePatterns') : undefined;
+    if (process.env.K_SERVICE || !Array.isArray(patterns) || patterns.length === 0)
+        return [];
+    return declaredEgress({ projectRoot: process.cwd() });
+}
+/** The nearest artifact.bundle.yml, when its app_root is this project; the manifest may sit above app_root. */
+async function declaredEgress({ projectRoot }) {
+    for (let directory = projectRoot;; directory = dirname(directory)) {
+        const text = await readFile(join(directory, 'artifact.bundle.yml'), 'utf8').catch(() => undefined);
+        if (text !== undefined) {
+            const manifest = parseArtifactStudioManifest(parseYaml(text));
+            return isNextArtifactManifest(manifest) && resolve(directory, manifest.artifact.app_root) === projectRoot ? manifest.server.egress : [];
+        }
+        if (dirname(directory) === directory)
+            return [];
+    }
+}
+/** Always compiled into standalone output; runtime mode is selected only at boot. */
+export function withArtifactNextConfig(input) {
+    return async (phase, context) => {
+        // Build workers/local dev processes receive disposable storage; hosted runtime
+        // must explicitly provide disabled/hosted and cannot fall back to local memory.
+        if (!process.env.K_SERVICE && !process.env.ARTIFACT_NEXT_CACHE_MODE) {
+            if (phase === 'phase-development-server' || phase === 'phase-production-server')
+                process.env.ARTIFACT_NEXT_CACHE_MODE = 'local';
+            else if (phase === 'phase-production-build')
+                process.env.ARTIFACT_NEXT_CACHE_MODE = 'build';
+        }
+        const config = typeof input === 'function' ? await input(phase, context) : input;
+        if (!config || typeof config !== 'object' || Array.isArray(config))
+            throw new Error('Next configuration must return an object');
+        return configured(config, await allowedEgress(config));
+    };
+}
+/** Runs only inside the isolated compile sandbox, never in the control-plane worker. */
+export async function installArtifactNextCacheConfig({ projectRoot }) {
+    const names = await readdir(projectRoot);
+    const configs = names.filter((name) => /^next\.config\.(?:mjs|js|ts)$/.test(name));
+    if (configs.length > 1)
+        throw new Error('An Artifact Next application must have exactly one Next configuration file');
+    const original = configs[0];
+    const reserved = names.filter((name) => name.startsWith('.sequence-next-'));
+    if (original && (await readFile(join(projectRoot, original), 'utf8')).startsWith(MARKER)) {
+        const saved = reserved.length === 1 && /^\.sequence-next-user\.config\.(?:mjs|js|ts)$/.test(reserved[0]) ? reserved[0] : undefined;
+        if ((reserved.length === 0 || saved) && await readFile(join(projectRoot, original), 'utf8') === wrapperSource(saved))
+            return;
+    }
+    if (reserved.length)
+        throw new Error('Source contains reserved Artifact Next configuration files');
+    const extension = original?.split('.').at(-1) ?? 'mjs';
+    const saved = `.sequence-next-user.config.${extension}`;
+    if (original)
+        await rename(join(projectRoot, original), join(projectRoot, saved));
+    const wrapper = extension === 'ts' ? 'next.config.ts' : 'next.config.mjs';
+    await writeFile(join(projectRoot, wrapper), wrapperSource(original ? saved : undefined), { flag: 'wx' });
+}
+function wrapperSource(saved) {
+    return `${MARKER}\nimport { withArtifactNextConfig } from '@sequenceholdings/artifact-studio/next-cache/config';\n${saved ? `import userConfig from './${saved}';\n` : 'const userConfig = {};\n'}export default withArtifactNextConfig(userConfig);\n`;
+}

package/dist/next-cache/incremental-handler.d.ts

@@ -0,0 +1,18 @@
+import type { IncrementalCacheContext, NextIncrementalCacheHandler } from './incremental.js';
+export { verifyArtifactNextCacheReadiness } from './config.js';
+declare class ArtifactRuntimeIncrementalHandler implements NextIncrementalCacheHandler {
+    private readonly handler;
+    constructor(context?: {
+        revalidatedTags?: string[];
+    });
+    get(key: string, context?: IncrementalCacheContext): Promise<{
+        value: unknown;
+        lastModified: number;
+    } | null>;
+    set(key: string, value: unknown, context?: IncrementalCacheContext): Promise<void>;
+    revalidateTag(tags: string | string[], durations?: {
+        expire?: number;
+    }): Promise<void>;
+    resetRequestCache(): void;
+}
+export { ArtifactRuntimeIncrementalHandler as default };

package/dist/next-cache/incremental-handler.js

@@ -0,0 +1,17 @@
+import { getArtifactNextRuntimeCache } from './runtime.js';
+// The trusted container launcher imports this public subpath for readiness.
+// Keep it in the handler dependency graph so Next traces it into standalone.
+export { verifyArtifactNextCacheReadiness } from './config.js';
+class ArtifactRuntimeIncrementalHandler {
+    handler;
+    constructor(context = {}) {
+        const Handler = getArtifactNextRuntimeCache().IncrementalCacheHandler;
+        this.handler = new Handler(context);
+    }
+    get(key, context) { return this.handler.get(key, context); }
+    set(key, value, context) { return this.handler.set(key, value, context); }
+    revalidateTag(tags, durations) { return this.handler.revalidateTag(tags, durations); }
+    resetRequestCache() { this.handler.resetRequestCache(); }
+}
+// Next's configuration loader requires a default export from handler modules.
+export { ArtifactRuntimeIncrementalHandler as default };

package/dist/next-cache/incremental.d.ts

@@ -0,0 +1,27 @@
+import { type NextCacheOptions } from './adapter-runtime.js';
+export interface IncrementalCacheContext {
+    tags?: string[];
+    softTags?: string[];
+    kind?: string;
+    /** Supplied by Next for pages and routes on set(). */
+    cacheControl?: {
+        revalidate?: number | false;
+        expire?: number;
+    };
+}
+export interface NextIncrementalCacheHandler {
+    get(key: string, context?: IncrementalCacheContext): Promise<{
+        value: unknown;
+        lastModified: number;
+    } | null>;
+    set(key: string, value: unknown, context?: IncrementalCacheContext): Promise<void>;
+    revalidateTag(tags: string | string[], durations?: {
+        expire?: number;
+    }): Promise<void>;
+    resetRequestCache(): void;
+}
+export type NextIncrementalCacheHandlerConstructor = new (context?: {
+    revalidatedTags?: string[];
+}) => NextIncrementalCacheHandler;
+/** The constructor is returned for a platform-generated Next cacheHandler shim. */
+export declare function createIncrementalCacheHandler(options: NextCacheOptions): NextIncrementalCacheHandlerConstructor;

package/dist/next-cache/incremental.js

@@ -0,0 +1,99 @@
+import { z } from 'zod';
+import { CacheAdapterRuntime, nextWriteTicket } from './adapter-runtime.js';
+import { deserializeCacheValue, serializeCacheValue } from './serialization.js';
+import { normalizeCacheTags } from './store.js';
+/** Next's per-route CacheControl, recorded with a page or route so a soft invalidation can stay SWR. */
+const cacheControlSchema = z.object({
+    revalidate: z.union([z.number().finite().positive(), z.literal(false)]),
+    expire: z.number().finite().positive().optional(),
+});
+const storedEntrySchema = z.object({
+    format: z.literal('incremental-v1'), value: z.unknown(), lastModified: z.number().finite(),
+    cacheControl: cacheControlSchema.optional(),
+});
+const taggedValueSchema = z.object({
+    kind: z.string().optional(),
+    tags: z.array(z.string()).optional(),
+    headers: z.record(z.string(), z.unknown()).optional(),
+}).passthrough();
+// Keeps a synthesized SWR timestamp clear of the revalidate and expire boundaries.
+const STALE_WINDOW_MARGIN_MS = 1_000;
+/**
+ * lastModified for an entry the store reports as soft-invalidated (stale but not expired).
+ * Next 16.3 reads -1 as "stale" for FETCH entries, but as "expired: block on regeneration" for
+ * APP_PAGE and APP_ROUTE. For those, report a time just past the route's revalidate window and
+ * still inside expire, which Next serves stale while regenerating in the background. Pages with
+ * no revalidate window (revalidate: false) or no room before expire can only regenerate blocking.
+ */
+function softStaleLastModified({ record, now }) {
+    const kind = taggedValueSchema.safeParse(record.value).data?.kind;
+    const control = record.cacheControl;
+    if ((kind !== 'APP_PAGE' && kind !== 'APP_ROUTE') || !control || control.revalidate === false)
+        return -1;
+    const revalidateMs = control.revalidate * 1000;
+    if (control.expire !== undefined && control.expire * 1000 - revalidateMs <= 2 * STALE_WINDOW_MARGIN_MS)
+        return -1;
+    const lastModified = now - revalidateMs - STALE_WINDOW_MARGIN_MS;
+    return lastModified > 0 ? lastModified : -1;
+}
+/** The constructor is returned for a platform-generated Next cacheHandler shim. */
+export function createIncrementalCacheHandler(options) {
+    const runtime = new CacheAdapterRuntime(options);
+    return class ArtifactIncrementalCacheHandler {
+        // Next creates an IncrementalCache/handler for each request. Tickets are never
+        // shared across requests, and no user/cache payload is kept process-globally.
+        tickets = new Map();
+        revalidatedTags;
+        constructor(context = {}) {
+            this.revalidatedTags = new Set(context.revalidatedTags ?? []);
+        }
+        async get(key, context = {}) {
+            try {
+                const tags = normalizeCacheTags([...(context.tags ?? []), ...(context.softTags ?? [])]);
+                const lookup = await runtime.read({ key: `isr:${key}`, tags });
+                if (!lookup)
+                    return null;
+                // Payload-free, like the component handler: set() only needs the ticket and lookup time. A ticket
+                // the store has moved past (e.g. revalidateTag earlier in this request) is replaced, not kept.
+                const retained = this.tickets.get(key);
+                const next = nextWriteTicket({ retained, lookup, now: runtime.now() });
+                if (next !== retained && (retained || this.tickets.size < 512))
+                    this.tickets.set(key, next);
+                if (!lookup.entry || tags.some((tag) => this.revalidatedTags.has(tag)))
+                    return null;
+                const record = storedEntrySchema.parse(deserializeCacheValue({ serialized: lookup.entry.payload, limits: { maxBytes: runtime.maxEntryBytes } }));
+                // Soft staleness is not hard expiration: pages and routes must stay stale-while-revalidate.
+                return { value: record.value, lastModified: lookup.entry.stale ? softStaleLastModified({ record, now: runtime.now() }) : record.lastModified };
+            }
+            catch {
+                runtime.report('read');
+                return null;
+            }
+        }
+        async set(key, value, context = {}) {
+            const lookup = this.tickets.get(key);
+            this.tickets.delete(key);
+            // No get means no proof the render preceded invalidation. Skip caching
+            // rather than assigning a fresh epoch to possibly stale computed output.
+            if (!lookup)
+                return;
+            try {
+                const parsed = taggedValueSchema.safeParse(value);
+                const valueTags = parsed.success ? parsed.data.tags ?? [] : [];
+                const header = parsed.success ? parsed.data.headers?.['x-next-cache-tags'] : undefined;
+                const tags = normalizeCacheTags([...(context.tags ?? []), ...valueTags, ...(typeof header === 'string' ? header.split(',') : [])]);
+                const cacheControl = cacheControlSchema.safeParse(context.cacheControl).data;
+                const payload = serializeCacheValue({ value: { format: 'incremental-v1', value, lastModified: runtime.now(), ...(cacheControl ? { cacheControl } : {}) }, limits: { maxBytes: runtime.maxEntryBytes } });
+                await runtime.store.commit({ namespace: runtime.namespace, key: `isr:${key}`, ticket: lookup.ticket,
+                    payload, tags, ttlMs: runtime.maxEntryAgeMs });
+            }
+            catch {
+                runtime.report('write');
+            }
+        }
+        async revalidateTag(tags, durations) {
+            await runtime.invalidate({ tags: typeof tags === 'string' ? [tags] : tags, durations });
+        }
+        resetRequestCache() { this.tickets.clear(); }
+    };
+}

package/dist/next-cache/index.d.ts

@@ -0,0 +1,18 @@
+import type { NextCacheOptions } from './adapter-runtime.js';
+export { createComponentCacheHandler, type NextComponentCacheEntry, type NextComponentCacheHandler } from './components.js';
+export { createIncrementalCacheHandler, type IncrementalCacheContext, type NextIncrementalCacheHandler, type NextIncrementalCacheHandlerConstructor } from './incremental.js';
+export { LocalNextCacheStore } from './memory-store.js';
+export { RedisNextCacheStore } from './redis-store.js';
+export { ValkeyScriptExecutor, ValkeyUnavailableError, type ValkeyConnection, type RedisScriptExecutor } from './valkey-transport.js';
+export type { NextCacheOptions } from './adapter-runtime.js';
+export type { NextCacheNamespace, NextCacheStore, CacheWriteTicket, CacheLookup, CacheCommit, CacheLocation } from './store.js';
+/**
+ * Platform wiring for both Next cache APIs. Generated shims default-export the
+ * constructor/object, and next.config must set cacheMaxMemorySize: 0.
+ * This caches explicit application-wide Next entries, never SDK user requests.
+ * User-bound SDK fetches must use no-store and remain outside use-cache scopes.
+ */
+export declare function createNextCacheHandlers(options: NextCacheOptions): {
+    IncrementalCacheHandler: import("./incremental.js").NextIncrementalCacheHandlerConstructor;
+    cacheComponents: import("./components.js").NextComponentCacheHandler;
+};

package/dist/next-cache/index.js

@@ -0,0 +1,16 @@
+import { createComponentCacheHandler } from './components.js';
+import { createIncrementalCacheHandler } from './incremental.js';
+export { createComponentCacheHandler } from './components.js';
+export { createIncrementalCacheHandler } from './incremental.js';
+export { LocalNextCacheStore } from './memory-store.js';
+export { RedisNextCacheStore } from './redis-store.js';
+export { ValkeyScriptExecutor, ValkeyUnavailableError } from './valkey-transport.js';
+/**
+ * Platform wiring for both Next cache APIs. Generated shims default-export the
+ * constructor/object, and next.config must set cacheMaxMemorySize: 0.
+ * This caches explicit application-wide Next entries, never SDK user requests.
+ * User-bound SDK fetches must use no-store and remain outside use-cache scopes.
+ */
+export function createNextCacheHandlers(options) {
+    return { IncrementalCacheHandler: createIncrementalCacheHandler(options), cacheComponents: createComponentCacheHandler(options) };
+}

package/dist/next-cache/memory-store.d.ts

@@ -0,0 +1,27 @@
+import { type CacheCommit, type CacheLocation, type CacheLookup, type NextCacheNamespace, type NextCacheStore } from './store.js';
+/** Explicitly disposable, isolated local cache. Never a distributed-store fallback. */
+export declare class LocalNextCacheStore implements NextCacheStore {
+    private readonly metadata;
+    private readonly entries;
+    private readonly now;
+    private readonly maxEntries;
+    private readonly maxBytes;
+    private bytes;
+    constructor({ purpose, now, maxEntries, maxBytes }: {
+        purpose: 'test' | 'local-development';
+        now?: () => number;
+        maxEntries?: number;
+        maxBytes?: number;
+    });
+    private getMetadata;
+    private remove;
+    read(input: CacheLocation & {
+        tags: string[];
+    }): Promise<CacheLookup>;
+    commit(input: CacheCommit): Promise<boolean>;
+    invalidate(input: {
+        namespace: NextCacheNamespace;
+        tags: string[];
+        expireAfterMs?: number;
+    }): Promise<void>;
+}

package/dist/next-cache/memory-store.js

@@ -0,0 +1,118 @@
+import { randomUUID } from 'node:crypto';
+import { cacheEntryKey, cacheNamespacePrefix, MAX_CACHE_WRITE_AGE_MS, MAX_NAMESPACE_TAGS, normalizeCacheTags, validateCacheCommit, validateExpiration, } from './store.js';
+/** Explicitly disposable, isolated local cache. Never a distributed-store fallback. */
+export class LocalNextCacheStore {
+    metadata = new Map();
+    entries = new Map();
+    now;
+    maxEntries;
+    maxBytes;
+    bytes = 0;
+    constructor({ purpose, now = Date.now, maxEntries = 1024, maxBytes = 64 * 1024 * 1024 }) {
+        if (purpose !== 'test' && purpose !== 'local-development')
+            throw new Error('Local cache cannot serve a hosted deployment');
+        if (![maxEntries, maxBytes].every((value) => Number.isSafeInteger(value) && value > 0))
+            throw new Error('Invalid local cache capacity');
+        this.now = now;
+        this.maxEntries = maxEntries;
+        this.maxBytes = maxBytes;
+    }
+    getMetadata(namespace) {
+        const key = cacheNamespacePrefix(namespace);
+        let metadata = this.metadata.get(key);
+        if (!metadata) {
+            if (this.metadata.size >= 256)
+                this.metadata.delete(this.metadata.keys().next().value ?? '');
+            metadata = { incarnation: randomUUID(), epoch: 0, tags: new Map() };
+            this.metadata.set(key, metadata);
+        }
+        return metadata;
+    }
+    remove(key) {
+        const entry = this.entries.get(key);
+        if (entry)
+            this.bytes -= Buffer.byteLength(entry.payload);
+        this.entries.delete(key);
+    }
+    async read(input) {
+        const tags = normalizeCacheTags(input.tags);
+        const key = cacheEntryKey(input);
+        const metadata = this.getMetadata(input.namespace);
+        let entry = this.entries.get(key);
+        if (entry && entry.expiresAt <= this.now()) {
+            this.remove(key);
+            entry = undefined;
+        }
+        const result = { ticket: {
+                incarnation: metadata.incarnation, epoch: metadata.epoch,
+                version: entry?.version ?? '', startedAt: this.now(),
+            } };
+        if (!entry || entry.incarnation !== metadata.incarnation)
+            return result;
+        let stale = false;
+        for (const tag of [...tags, ...entry.tags]) {
+            const history = metadata.tags.get(tag);
+            if (!history)
+                continue;
+            if (entry.epoch < history.floor)
+                return result;
+            for (const event of history.events) {
+                if (event.epoch <= entry.epoch)
+                    continue;
+                if (event.expireAt <= this.now())
+                    return result;
+                stale = true;
+            }
+        }
+        // Refresh LRU position only for usable records.
+        this.entries.delete(key);
+        this.entries.set(key, entry);
+        result.entry = { payload: entry.payload, stale };
+        return result;
+    }
+    async commit(input) {
+        validateCacheCommit(input);
+        const key = cacheEntryKey(input);
+        const metadata = this.metadata.get(cacheNamespacePrefix(input.namespace));
+        let previous = this.entries.get(key);
+        if (previous && previous.expiresAt <= this.now()) {
+            this.remove(key);
+            previous = undefined;
+        }
+        if (!metadata || metadata.incarnation !== input.ticket.incarnation || metadata.epoch !== input.ticket.epoch
+            || (previous?.version ?? '') !== input.ticket.version || this.now() < input.ticket.startedAt
+            || this.now() - input.ticket.startedAt > MAX_CACHE_WRITE_AGE_MS)
+            return false;
+        const bytes = Buffer.byteLength(input.payload);
+        if (bytes > this.maxBytes)
+            return false;
+        this.remove(key);
+        this.entries.set(key, { ...input.ticket, version: randomUUID(), tags: [...input.tags],
+            payload: input.payload, expiresAt: this.now() + input.ttlMs });
+        this.bytes += bytes;
+        while (this.entries.size > this.maxEntries || this.bytes > this.maxBytes) {
+            this.remove(this.entries.keys().next().value ?? '');
+        }
+        return true;
+    }
+    async invalidate(input) {
+        validateExpiration(input.expireAfterMs);
+        const tags = normalizeCacheTags(input.tags);
+        if (!tags.length)
+            return;
+        const metadata = this.getMetadata(input.namespace);
+        if (metadata.tags.size + tags.length > MAX_NAMESPACE_TAGS) {
+            metadata.incarnation = randomUUID();
+            metadata.epoch = 0;
+            metadata.tags.clear();
+        }
+        const epoch = ++metadata.epoch;
+        for (const tag of tags) {
+            const history = metadata.tags.get(tag) ?? { floor: 0, events: [] };
+            history.events.push({ epoch, expireAt: this.now() + (input.expireAfterMs ?? 0) });
+            if (history.events.length > 16)
+                history.floor = history.events.shift()?.epoch ?? history.floor;
+            metadata.tags.set(tag, history);
+        }
+    }
+}

package/dist/next-cache/redis-scripts.d.ts

@@ -0,0 +1,3 @@
+export declare const NEXT_CACHE_READ_SCRIPT = "\nlocal clock = redis.call('TIME')\nlocal now = tonumber(clock[1]) * 1000 + math.floor(tonumber(clock[2]) / 1000)\nlocal function decode(value)\n  if not value then return nil end\n  local ok, parsed = pcall(cjson.decode, value)\n  if ok and type(parsed) == 'table' then return parsed end\n  return nil\nend\nlocal function initialize(nonce, retention)\n  local incarnation = redis.call('HGET', KEYS[1], 'incarnation')\n  if not incarnation then\n    redis.call('DEL', KEYS[1])\n    redis.call('HSET', KEYS[1], 'incarnation', nonce, 'epoch', '0')\n    incarnation = nonce\n  end\n  redis.call('PEXPIRE', KEYS[1], retention)\n  return incarnation\nend\n\nlocal incarnation = initialize(ARGV[1], ARGV[2])\nlocal epoch = tonumber(redis.call('HGET', KEYS[1], 'epoch'))\nlocal entry = decode(redis.call('GET', KEYS[2]))\nlocal ticket = {incarnation=incarnation, epoch=epoch, version=entry and entry.version or '', startedAt=now}\nlocal result = {ticket=ticket}\nif not entry or entry.incarnation ~= incarnation or entry.expiresAt <= now then\n  return cjson.encode(result)\nend\nlocal tags = decode(ARGV[3])\nfor _, tag in ipairs(entry.tags) do table.insert(tags, tag) end\nlocal stale = false\nfor _, tag in ipairs(tags) do\n  local raw = redis.call('HGET', KEYS[1], 'tag:' .. tag)\n  local state = decode(raw)\n  if raw and not state then return cjson.encode(result) end\n  if state then\n    if entry.epoch < state.floor then return cjson.encode(result) end\n    for _, event in ipairs(state.events) do\n      if event.epoch > entry.epoch then\n        if event.expireAt >= 0 and event.expireAt <= now then return cjson.encode(result) end\n        stale = true\n      end\n    end\n  end\nend\nresult.entry = {payload=entry.payload, stale=stale}\nreturn cjson.encode(result)\n";
+export declare const NEXT_CACHE_COMMIT_SCRIPT = "\nlocal clock = redis.call('TIME')\nlocal now = tonumber(clock[1]) * 1000 + math.floor(tonumber(clock[2]) / 1000)\nlocal function decode(value)\n  if not value then return nil end\n  local ok, parsed = pcall(cjson.decode, value)\n  if ok and type(parsed) == 'table' then return parsed end\n  return nil\nend\nlocal function initialize(nonce, retention)\n  local incarnation = redis.call('HGET', KEYS[1], 'incarnation')\n  if not incarnation then\n    redis.call('DEL', KEYS[1])\n    redis.call('HSET', KEYS[1], 'incarnation', nonce, 'epoch', '0')\n    incarnation = nonce\n  end\n  redis.call('PEXPIRE', KEYS[1], retention)\n  return incarnation\nend\n\nlocal ticket = decode(ARGV[1])\nif redis.call('HGET', KEYS[1], 'incarnation') ~= ticket.incarnation then return 0 end\nif tonumber(redis.call('HGET', KEYS[1], 'epoch')) ~= ticket.epoch then return 0 end\nif now - ticket.startedAt > tonumber(ARGV[7]) or now < ticket.startedAt then return 0 end\nlocal existing = decode(redis.call('GET', KEYS[2]))\nif (existing and existing.version or '') ~= ticket.version then return 0 end\nlocal entry = {\n  incarnation=ticket.incarnation, epoch=ticket.epoch, version=ARGV[2],\n  tags=decode(ARGV[3]), payload=ARGV[4], expiresAt=now+tonumber(ARGV[5])\n}\nredis.call('SET', KEYS[2], cjson.encode(entry), 'PX', ARGV[5])\nredis.call('PEXPIRE', KEYS[1], ARGV[6])\nreturn 1\n";
+export declare const NEXT_CACHE_INVALIDATE_SCRIPT = "\nlocal clock = redis.call('TIME')\nlocal now = tonumber(clock[1]) * 1000 + math.floor(tonumber(clock[2]) / 1000)\nlocal function decode(value)\n  if not value then return nil end\n  local ok, parsed = pcall(cjson.decode, value)\n  if ok and type(parsed) == 'table' then return parsed end\n  return nil\nend\nlocal function initialize(nonce, retention)\n  local incarnation = redis.call('HGET', KEYS[1], 'incarnation')\n  if not incarnation then\n    redis.call('DEL', KEYS[1])\n    redis.call('HSET', KEYS[1], 'incarnation', nonce, 'epoch', '0')\n    incarnation = nonce\n  end\n  redis.call('PEXPIRE', KEYS[1], retention)\n  return incarnation\nend\n\nlocal tags = decode(ARGV[3])\nif #tags == 0 then return 1 end\n-- Bound metadata growth. Rotating its incarnation safely invalidates all entries.\nif redis.call('HLEN', KEYS[1]) + #tags > tonumber(ARGV[5]) + 2 then redis.call('DEL', KEYS[1]) end\ninitialize(ARGV[1], ARGV[2])\nlocal epoch = redis.call('HINCRBY', KEYS[1], 'epoch', 1)\nlocal expireAt = tonumber(ARGV[4]) < 0 and -1 or now + tonumber(ARGV[4])\nfor _, tag in ipairs(tags) do\n  local state = decode(redis.call('HGET', KEYS[1], 'tag:' .. tag)) or {floor=0, events={}}\n  table.insert(state.events, {epoch=epoch, expireAt=expireAt})\n  if #state.events > 16 then\n    local removed = table.remove(state.events, 1)\n    state.floor = removed.epoch\n  end\n  redis.call('HSET', KEYS[1], 'tag:' .. tag, cjson.encode(state))\nend\nreturn 1\n";