@sequenceholdings/artifact-studio 0.2.6 → 0.3.1

package/dist/next-cache/redis-scripts.js

@@ -0,0 +1,85 @@
+// One metadata hash holds the incarnation, epoch and complete tag history. Redis
+// eviction is key-atomic: tags cannot disappear independently and revive an entry.
+const common = `
+local clock = redis.call('TIME')
+local now = tonumber(clock[1]) * 1000 + math.floor(tonumber(clock[2]) / 1000)
+local function decode(value)
+  if not value then return nil end
+  local ok, parsed = pcall(cjson.decode, value)
+  if ok and type(parsed) == 'table' then return parsed end
+  return nil
+end
+local function initialize(nonce, retention)
+  local incarnation = redis.call('HGET', KEYS[1], 'incarnation')
+  if not incarnation then
+    redis.call('DEL', KEYS[1])
+    redis.call('HSET', KEYS[1], 'incarnation', nonce, 'epoch', '0')
+    incarnation = nonce
+  end
+  redis.call('PEXPIRE', KEYS[1], retention)
+  return incarnation
+end
+`;
+export const NEXT_CACHE_READ_SCRIPT = `${common}
+local incarnation = initialize(ARGV[1], ARGV[2])
+local epoch = tonumber(redis.call('HGET', KEYS[1], 'epoch'))
+local entry = decode(redis.call('GET', KEYS[2]))
+local ticket = {incarnation=incarnation, epoch=epoch, version=entry and entry.version or '', startedAt=now}
+local result = {ticket=ticket}
+if not entry or entry.incarnation ~= incarnation or entry.expiresAt <= now then
+  return cjson.encode(result)
+end
+local tags = decode(ARGV[3])
+for _, tag in ipairs(entry.tags) do table.insert(tags, tag) end
+local stale = false
+for _, tag in ipairs(tags) do
+  local raw = redis.call('HGET', KEYS[1], 'tag:' .. tag)
+  local state = decode(raw)
+  if raw and not state then return cjson.encode(result) end
+  if state then
+    if entry.epoch < state.floor then return cjson.encode(result) end
+    for _, event in ipairs(state.events) do
+      if event.epoch > entry.epoch then
+        if event.expireAt >= 0 and event.expireAt <= now then return cjson.encode(result) end
+        stale = true
+      end
+    end
+  end
+end
+result.entry = {payload=entry.payload, stale=stale}
+return cjson.encode(result)
+`;
+export const NEXT_CACHE_COMMIT_SCRIPT = `${common}
+local ticket = decode(ARGV[1])
+if redis.call('HGET', KEYS[1], 'incarnation') ~= ticket.incarnation then return 0 end
+if tonumber(redis.call('HGET', KEYS[1], 'epoch')) ~= ticket.epoch then return 0 end
+if now - ticket.startedAt > tonumber(ARGV[7]) or now < ticket.startedAt then return 0 end
+local existing = decode(redis.call('GET', KEYS[2]))
+if (existing and existing.version or '') ~= ticket.version then return 0 end
+local entry = {
+  incarnation=ticket.incarnation, epoch=ticket.epoch, version=ARGV[2],
+  tags=decode(ARGV[3]), payload=ARGV[4], expiresAt=now+tonumber(ARGV[5])
+}
+redis.call('SET', KEYS[2], cjson.encode(entry), 'PX', ARGV[5])
+redis.call('PEXPIRE', KEYS[1], ARGV[6])
+return 1
+`;
+export const NEXT_CACHE_INVALIDATE_SCRIPT = `${common}
+local tags = decode(ARGV[3])
+if #tags == 0 then return 1 end
+-- Bound metadata growth. Rotating its incarnation safely invalidates all entries.
+if redis.call('HLEN', KEYS[1]) + #tags > tonumber(ARGV[5]) + 2 then redis.call('DEL', KEYS[1]) end
+initialize(ARGV[1], ARGV[2])
+local epoch = redis.call('HINCRBY', KEYS[1], 'epoch', 1)
+local expireAt = tonumber(ARGV[4]) < 0 and -1 or now + tonumber(ARGV[4])
+for _, tag in ipairs(tags) do
+  local state = decode(redis.call('HGET', KEYS[1], 'tag:' .. tag)) or {floor=0, events={}}
+  table.insert(state.events, {epoch=epoch, expireAt=expireAt})
+  if #state.events > 16 then
+    local removed = table.remove(state.events, 1)
+    state.floor = removed.epoch
+  end
+  redis.call('HSET', KEYS[1], 'tag:' .. tag, cjson.encode(state))
+end
+return 1
+`;

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

@@ -0,0 +1,18 @@
+import { type CacheCommit, type CacheLocation, type CacheLookup, type NextCacheNamespace, type NextCacheStore } from './store.js';
+import type { RedisScriptExecutor } from './valkey-transport.js';
+/** Shared Redis/Valkey store. No process-local invalidation state or fallback. */
+export declare class RedisNextCacheStore implements NextCacheStore {
+    private readonly executor;
+    constructor({ executor }: {
+        executor: RedisScriptExecutor;
+    });
+    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/redis-store.js

@@ -0,0 +1,56 @@
+import { randomUUID } from 'node:crypto';
+import { z } from 'zod';
+import { cacheDigest, cacheEntryKey, cacheNamespacePrefix, MAX_CACHE_ENTRY_AGE_MS, MAX_CACHE_WRITE_AGE_MS, MAX_NAMESPACE_TAGS, normalizeCacheTags, validateCacheCommit, validateExpiration, } from './store.js';
+import { NEXT_CACHE_COMMIT_SCRIPT, NEXT_CACHE_INVALIDATE_SCRIPT, NEXT_CACHE_READ_SCRIPT } from './redis-scripts.js';
+const lookupSchema = z.object({
+    ticket: z.object({
+        incarnation: z.string().uuid(), epoch: z.number().int().nonnegative(),
+        version: z.string().max(36), startedAt: z.number().int().nonnegative(),
+    }),
+    entry: z.object({ payload: z.string(), stale: z.boolean() }).optional(),
+});
+const METADATA_RETENTION_MS = MAX_CACHE_ENTRY_AGE_MS + MAX_CACHE_WRITE_AGE_MS;
+/** Shared Redis/Valkey store. No process-local invalidation state or fallback. */
+export class RedisNextCacheStore {
+    executor;
+    constructor({ executor }) {
+        this.executor = executor;
+    }
+    async read(input) {
+        const tags = normalizeCacheTags(input.tags).map(cacheDigest);
+        const result = await this.executor.eval({
+            script: NEXT_CACHE_READ_SCRIPT,
+            keys: [`${cacheNamespacePrefix(input.namespace)}:meta`, cacheEntryKey(input)],
+            arguments: [randomUUID(), String(METADATA_RETENTION_MS), JSON.stringify(tags)],
+        });
+        if (typeof result !== 'string')
+            throw new Error('Invalid Next cache response');
+        return lookupSchema.parse(JSON.parse(result));
+    }
+    async commit(input) {
+        validateCacheCommit(input);
+        const result = await this.executor.eval({
+            script: NEXT_CACHE_COMMIT_SCRIPT,
+            keys: [`${cacheNamespacePrefix(input.namespace)}:meta`, cacheEntryKey(input)],
+            arguments: [JSON.stringify(input.ticket), randomUUID(), JSON.stringify(input.tags.map(cacheDigest)),
+                input.payload, String(input.ttlMs), String(METADATA_RETENTION_MS), String(MAX_CACHE_WRITE_AGE_MS)],
+        });
+        if (result !== 0 && result !== 1)
+            throw new Error('Invalid Next cache commit response');
+        return result === 1;
+    }
+    async invalidate(input) {
+        validateExpiration(input.expireAfterMs);
+        const tags = normalizeCacheTags(input.tags).map(cacheDigest);
+        if (!tags.length)
+            return;
+        const result = await this.executor.eval({
+            script: NEXT_CACHE_INVALIDATE_SCRIPT,
+            keys: [`${cacheNamespacePrefix(input.namespace)}:meta`],
+            arguments: [randomUUID(), String(METADATA_RETENTION_MS), JSON.stringify(tags),
+                String(input.expireAfterMs ?? 0), String(MAX_NAMESPACE_TAGS)],
+        });
+        if (result !== 1)
+            throw new Error('Next cache invalidation failed');
+    }
+}

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

@@ -0,0 +1,29 @@
+import { z } from 'zod';
+export declare const artifactNextCacheBindingSchema: z.ZodObject<{
+    namespace: z.ZodObject<{
+        applicationId: z.ZodString;
+        environment: z.ZodString;
+        releaseId: z.ZodString;
+        generation: z.ZodString;
+    }, z.core.$strict>;
+    connection: z.ZodObject<{
+        host: z.ZodString;
+        port: z.ZodNumber;
+        serverIdentity: z.ZodString;
+        caCertificates: z.ZodArray<z.ZodString>;
+    }, z.core.$strict>;
+}, z.core.$strict>;
+export declare function createArtifactNextRuntimeCache({ env }?: {
+    env?: NodeJS.ProcessEnv;
+}): {
+    IncrementalCacheHandler: import("./incremental.js").NextIncrementalCacheHandlerConstructor;
+    cacheComponents: import("./components.js").NextComponentCacheHandler;
+    verifyReadiness(): Promise<void>;
+};
+export declare function getArtifactNextRuntimeCache(): {
+    IncrementalCacheHandler: import("./incremental.js").NextIncrementalCacheHandlerConstructor;
+    cacheComponents: import("./components.js").NextComponentCacheHandler;
+    verifyReadiness(): Promise<void>;
+};
+/** Trusted startup calls this before serving; unlike cache reads, failures propagate. */
+export declare function verifyArtifactNextCacheReadiness(): Promise<void>;

package/dist/next-cache/runtime.js

@@ -0,0 +1,63 @@
+import { randomUUID } from 'node:crypto';
+import { z } from 'zod';
+import { createComponentCacheHandler } from './components.js';
+import { createIncrementalCacheHandler } from './incremental.js';
+import { LocalNextCacheStore } from './memory-store.js';
+import { RedisNextCacheStore } from './redis-store.js';
+import { ValkeyScriptExecutor } from './valkey-transport.js';
+const namespaceSchema = z.strictObject({
+    applicationId: z.string().min(1).max(256), environment: z.string().min(1).max(256),
+    releaseId: z.string().min(1).max(256), generation: z.string().min(1).max(256),
+});
+export const artifactNextCacheBindingSchema = z.strictObject({
+    namespace: namespaceSchema,
+    connection: z.strictObject({
+        host: z.string().min(1).max(253), port: z.number().int().min(1).max(65535),
+        serverIdentity: z.string().min(1).max(253), caCertificates: z.array(z.string().min(1).max(16384)).min(1).max(16),
+    }),
+});
+function disabledStore() {
+    return {
+        async read() { return { ticket: { incarnation: randomUUID(), epoch: 0, version: '', startedAt: Date.now() } }; },
+        async commit() { return false; },
+        async invalidate() { },
+    };
+}
+export function createArtifactNextRuntimeCache({ env = process.env } = {}) {
+    let store;
+    let namespace;
+    const mode = env.ARTIFACT_NEXT_CACHE_MODE;
+    if (mode === 'hosted') {
+        const binding = artifactNextCacheBindingSchema.parse(JSON.parse(env.ARTIFACT_NEXT_CACHE_BINDING ?? 'null'));
+        store = new RedisNextCacheStore({ executor: new ValkeyScriptExecutor({ connection: binding.connection }) });
+        namespace = binding.namespace;
+    }
+    else if (mode === 'local' || mode === 'build' || mode === 'disabled') {
+        if (env.ARTIFACT_NEXT_CACHE_BINDING)
+            throw new Error('Only hosted cache mode may receive a private binding');
+        if (env.K_SERVICE && mode !== 'disabled')
+            throw new Error('Hosted Next runtimes cannot use a process-local cache');
+        store = mode === 'disabled' ? disabledStore() : new LocalNextCacheStore({ purpose: 'local-development' });
+        namespace = { applicationId: 'disposable', environment: mode, releaseId: 'local', generation: randomUUID() };
+    }
+    else {
+        throw new Error('Artifact Next cache mode must be explicitly configured before starting the server');
+    }
+    const options = { store, namespace };
+    return {
+        IncrementalCacheHandler: createIncrementalCacheHandler(options), cacheComponents: createComponentCacheHandler(options),
+        async verifyReadiness() {
+            if (mode === 'hosted')
+                await store.read({ namespace, key: '__platform_readiness', tags: [] });
+        },
+    };
+}
+let handlers;
+export function getArtifactNextRuntimeCache() {
+    handlers ??= createArtifactNextRuntimeCache();
+    return handlers;
+}
+/** Trusted startup calls this before serving; unlike cache reads, failures propagate. */
+export async function verifyArtifactNextCacheReadiness() {
+    await getArtifactNextRuntimeCache().verifyReadiness();
+}

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

@@ -0,0 +1,39 @@
+import { Buffer } from 'node:buffer';
+export interface CacheSerializationLimits {
+    /** Maximum UTF-8 bytes in the complete serialized record, including tags. */
+    maxBytes: number;
+    /** Maximum nesting depth; the root value has depth zero. */
+    maxDepth: number;
+    /** Maximum cumulative value count, including map keys and values. */
+    maxMembers: number;
+}
+export declare const DEFAULT_CACHE_SERIALIZATION_LIMITS: Readonly<CacheSerializationLimits>;
+type SerializationErrorCode = 'invalid_value' | 'limit_exceeded' | 'invalid_payload' | 'stream_timeout' | 'stream_aborted';
+export declare class CacheSerializationError extends Error {
+    readonly code: SerializationErrorCode;
+    constructor({ code, message }: {
+        code: SerializationErrorCode;
+        message: string;
+    });
+}
+/** Encodes only inert values, without invoking toJSON, getters or object constructors. */
+export declare function serializeCacheValue({ value, limits }: {
+    value: unknown;
+    limits?: Partial<CacheSerializationLimits>;
+}): string;
+export declare function deserializeCacheValue({ serialized, limits }: {
+    serialized: string;
+    limits?: Partial<CacheSerializationLimits>;
+}): unknown;
+/** Consumes an owned stream. Callers must pass a cache branch, not a response's live body. */
+export declare function readCacheStream({ stream, maxBytes, timeoutMs, maxChunks, signal, }: {
+    stream: ReadableStream<Uint8Array>;
+    maxBytes?: number;
+    timeoutMs?: number;
+    maxChunks?: number;
+    signal?: AbortSignal;
+}): Promise<Buffer>;
+export declare function createCacheStream({ bytes }: {
+    bytes: Uint8Array;
+}): ReadableStream<Uint8Array>;
+export {};

package/dist/next-cache/serialization.js

@@ -0,0 +1,333 @@
+import { Buffer } from 'node:buffer';
+import { performance } from 'node:perf_hooks';
+export const DEFAULT_CACHE_SERIALIZATION_LIMITS = Object.freeze({
+    maxBytes: 16 * 1024 * 1024,
+    maxDepth: 64,
+    maxMembers: 100_000,
+});
+export class CacheSerializationError extends Error {
+    code;
+    constructor({ code, message }) {
+        super(message);
+        this.name = 'CacheSerializationError';
+        this.code = code;
+    }
+}
+function fail({ code, message }) {
+    throw new CacheSerializationError({ code, message });
+}
+function positiveInteger({ value, name }) {
+    if (!Number.isSafeInteger(value) || value <= 0) {
+        fail({ code: 'invalid_value', message: `${name} must be a positive safe integer` });
+    }
+    return value;
+}
+function resolveLimits({ limits }) {
+    const resolved = { ...DEFAULT_CACHE_SERIALIZATION_LIMITS, ...limits };
+    for (const [name, value] of Object.entries(resolved))
+        positiveInteger({ value, name });
+    // Even a caller-supplied limit must not allow unbounded JavaScript recursion.
+    if (resolved.maxDepth > 128)
+        fail({ code: 'invalid_value', message: 'maxDepth cannot exceed 128' });
+    return resolved;
+}
+class ValueBudget {
+    limits;
+    members = 0;
+    constructor(limits) {
+        this.limits = limits;
+    }
+    visit({ depth }) {
+        if (depth > this.limits.maxDepth)
+            fail({ code: 'limit_exceeded', message: 'Cache value depth limit exceeded' });
+        this.members += 1;
+        this.checkMembers({ additional: 0 });
+    }
+    checkMembers({ additional }) {
+        if (additional > this.limits.maxMembers - this.members) {
+            fail({ code: 'limit_exceeded', message: 'Cache value member limit exceeded' });
+        }
+    }
+}
+const UNSAFE_KEYS = new Set(['__proto__', 'prototype', 'constructor']);
+function checkKey({ key, code }) {
+    if (UNSAFE_KEYS.has(key))
+        fail({ code, message: 'Unsafe cache record key' });
+}
+function numberPayload({ value }) {
+    if (Object.is(value, -0))
+        return '-0';
+    return Number.isFinite(value) ? value : String(value);
+}
+class ValueWriter extends ValueBudget {
+    bytes = 0;
+    parts = [];
+    ancestors = new Set();
+    write({ text }) {
+        this.bytes += Buffer.byteLength(text);
+        if (this.bytes > this.limits.maxBytes)
+            fail({ code: 'limit_exceeded', message: 'Cache value byte limit exceeded' });
+        this.parts.push(text);
+    }
+    writeString({ value }) {
+        if (Buffer.byteLength(value) > this.limits.maxBytes - this.bytes) {
+            fail({ code: 'limit_exceeded', message: 'Cache value byte limit exceeded' });
+        }
+        this.write({ text: JSON.stringify(value) });
+    }
+    encode({ value, depth }) {
+        this.visit({ depth });
+        if (value === null || value === undefined) {
+            this.write({ text: value === null ? '["null"]' : '["undefined"]' });
+        }
+        else if (typeof value === 'string') {
+            this.write({ text: '["string",' });
+            this.writeString({ value });
+            this.write({ text: ']' });
+        }
+        else if (typeof value === 'boolean' || typeof value === 'number') {
+            const payload = typeof value === 'number' ? numberPayload({ value }) : value;
+            this.write({ text: `["${typeof value}",${JSON.stringify(payload)}]` });
+        }
+        else if (typeof value === 'object') {
+            this.encodeObject({ value, depth });
+        }
+        else {
+            fail({ code: 'invalid_value', message: 'Unsupported cache value type' });
+        }
+    }
+    encodeObject({ value, depth }) {
+        if (this.ancestors.has(value))
+            fail({ code: 'invalid_value', message: 'Cyclic cache value' });
+        this.ancestors.add(value);
+        try {
+            const prototype = Object.getPrototypeOf(value);
+            if (Buffer.isBuffer(value) && prototype === Buffer.prototype)
+                this.encodeBytes({ value, tag: 'buffer' });
+            else if (value instanceof Uint8Array && prototype === Uint8Array.prototype)
+                this.encodeBytes({ value, tag: 'bytes' });
+            else if (value instanceof Map && prototype === Map.prototype)
+                this.encodeMap({ value, depth });
+            else if (Array.isArray(value) && prototype === Array.prototype)
+                this.encodeArray({ value, depth });
+            else if (prototype === Object.prototype || prototype === null)
+                this.encodeRecord({ value, depth, nullPrototype: prototype === null });
+            else
+                fail({ code: 'invalid_value', message: 'Unsupported cache value prototype' });
+        }
+        finally {
+            this.ancestors.delete(value);
+        }
+    }
+    encodeBytes({ value, tag }) {
+        if (Math.ceil(value.byteLength / 3) * 4 > this.limits.maxBytes - this.bytes) {
+            fail({ code: 'limit_exceeded', message: 'Cache value byte limit exceeded' });
+        }
+        const encoded = Buffer.from(value.buffer, value.byteOffset, value.byteLength).toString('base64');
+        this.write({ text: `["${tag}","${encoded}"]` });
+    }
+    encodeMap({ value, depth }) {
+        this.checkMembers({ additional: value.size * 2 });
+        if (Reflect.ownKeys(value).length)
+            fail({ code: 'invalid_value', message: 'Cache maps cannot have custom properties' });
+        this.write({ text: '["map",[' });
+        let separator = '';
+        for (const [key, member] of value) {
+            this.write({ text: `${separator}[` });
+            this.encode({ value: key, depth: depth + 1 });
+            this.write({ text: ',' });
+            this.encode({ value: member, depth: depth + 1 });
+            this.write({ text: ']' });
+            separator = ',';
+        }
+        this.write({ text: ']]' });
+    }
+    encodeArray({ value, depth }) {
+        this.checkMembers({ additional: value.length });
+        if (Reflect.ownKeys(value).length !== value.length + 1) {
+            fail({ code: 'invalid_value', message: 'Cache arrays must be dense and cannot have custom properties' });
+        }
+        this.write({ text: '["array",[' });
+        for (let index = 0; index < value.length; index += 1) {
+            const descriptor = Object.getOwnPropertyDescriptor(value, String(index));
+            if (!descriptor || !('value' in descriptor))
+                fail({ code: 'invalid_value', message: 'Cache arrays cannot have accessors or holes' });
+            if (index)
+                this.write({ text: ',' });
+            this.encode({ value: descriptor.value, depth: depth + 1 });
+        }
+        this.write({ text: ']]' });
+    }
+    encodeRecord({ value, depth, nullPrototype }) {
+        const keys = Reflect.ownKeys(value);
+        this.checkMembers({ additional: keys.length });
+        this.write({ text: nullPrototype ? '["null-record",[' : '["record",[' });
+        let separator = '';
+        for (const key of keys) {
+            if (typeof key !== 'string')
+                fail({ code: 'invalid_value', message: 'Cache records cannot have symbol keys' });
+            checkKey({ key, code: 'invalid_value' });
+            const descriptor = Object.getOwnPropertyDescriptor(value, key);
+            if (!descriptor || !('value' in descriptor) || !descriptor.enumerable) {
+                fail({ code: 'invalid_value', message: 'Cache records must contain enumerable data properties' });
+            }
+            this.write({ text: `${separator}[` });
+            this.writeString({ value: key });
+            this.write({ text: ',' });
+            this.encode({ value: descriptor.value, depth: depth + 1 });
+            this.write({ text: ']' });
+            separator = ',';
+        }
+        this.write({ text: ']]' });
+    }
+    finish() { return this.parts.join(''); }
+}
+/** Encodes only inert values, without invoking toJSON, getters or object constructors. */
+export function serializeCacheValue({ value, limits }) {
+    const writer = new ValueWriter(resolveLimits({ limits }));
+    writer.write({ text: '["artifact-next-cache",1,' });
+    writer.encode({ value, depth: 0 });
+    writer.write({ text: ']' });
+    return writer.finish();
+}
+function invalidPayload() {
+    return fail({ code: 'invalid_payload', message: 'Invalid serialized cache value' });
+}
+function decodeNumber({ value }) {
+    if (typeof value === 'number' && Number.isFinite(value) && !Object.is(value, -0))
+        return value;
+    switch (value) {
+        case '-0': return -0;
+        case 'NaN': return Number.NaN;
+        case 'Infinity': return Infinity;
+        case '-Infinity': return -Infinity;
+        default: return invalidPayload();
+    }
+}
+function decodeBytes({ value }) {
+    if (typeof value !== 'string' || value.length % 4 !== 0 || !/^[A-Za-z0-9+/]*={0,2}$/.test(value)) {
+        return invalidPayload();
+    }
+    const decoded = Buffer.from(value, 'base64');
+    if (decoded.toString('base64') !== value)
+        return invalidPayload();
+    return decoded;
+}
+function decodeEntries({ value, depth, budget, tag }) {
+    budget.checkMembers({ additional: value.length * (tag === 'map' ? 2 : 1) });
+    if (tag === 'array')
+        return value.map((member) => decodeValue({ value: member, depth: depth + 1, budget }));
+    const map = new Map();
+    const record = tag === 'null-record' ? Object.create(null) : {};
+    for (const entry of value) {
+        if (!Array.isArray(entry) || entry.length !== 2)
+            return invalidPayload();
+        if (tag === 'map') {
+            const key = decodeValue({ value: entry[0], depth: depth + 1, budget });
+            if (map.has(key))
+                return invalidPayload();
+            map.set(key, decodeValue({ value: entry[1], depth: depth + 1, budget }));
+        }
+        else {
+            const key = entry[0];
+            if (typeof key !== 'string' || Object.hasOwn(record, key))
+                return invalidPayload();
+            checkKey({ key, code: 'invalid_payload' });
+            record[key] = decodeValue({ value: entry[1], depth: depth + 1, budget });
+        }
+    }
+    return tag === 'map' ? map : record;
+}
+function decodeValue({ value, depth, budget }) {
+    budget.visit({ depth });
+    if (!Array.isArray(value))
+        return invalidPayload();
+    const tag = value[0];
+    if (tag === 'undefined' || tag === 'null') {
+        if (value.length !== 1)
+            return invalidPayload();
+        return tag === 'null' ? null : undefined;
+    }
+    if (value.length !== 2)
+        return invalidPayload();
+    const payload = value[1];
+    if (tag === 'string' && typeof payload === 'string')
+        return payload;
+    if (tag === 'boolean' && typeof payload === 'boolean')
+        return payload;
+    if (tag === 'number')
+        return decodeNumber({ value: payload });
+    if (tag === 'buffer' || tag === 'bytes') {
+        const bytes = decodeBytes({ value: payload });
+        return tag === 'buffer' ? bytes : new Uint8Array(bytes);
+    }
+    if ((tag === 'array' || tag === 'record' || tag === 'null-record' || tag === 'map') && Array.isArray(payload)) {
+        return decodeEntries({ value: payload, depth, budget, tag });
+    }
+    return invalidPayload();
+}
+export function deserializeCacheValue({ serialized, limits }) {
+    const budget = new ValueBudget(resolveLimits({ limits }));
+    if (Buffer.byteLength(serialized) > budget.limits.maxBytes)
+        fail({ code: 'limit_exceeded', message: 'Cache value byte limit exceeded' });
+    let envelope;
+    try {
+        envelope = JSON.parse(serialized);
+    }
+    catch {
+        return invalidPayload();
+    }
+    if (!Array.isArray(envelope) || envelope.length !== 3 || envelope[0] !== 'artifact-next-cache' || envelope[1] !== 1) {
+        return invalidPayload();
+    }
+    return decodeValue({ value: envelope[2], depth: 0, budget });
+}
+/** Consumes an owned stream. Callers must pass a cache branch, not a response's live body. */
+export async function readCacheStream({ stream, maxBytes = DEFAULT_CACHE_SERIALIZATION_LIMITS.maxBytes, timeoutMs = 10_000, maxChunks = 65_536, signal, }) {
+    for (const [name, value] of Object.entries({ maxBytes, timeoutMs, maxChunks }))
+        positiveInteger({ value, name });
+    if (timeoutMs > 2_147_483_647)
+        fail({ code: 'invalid_value', message: 'Stream timeout exceeds timer range' });
+    const reader = stream.getReader();
+    let interrupt = () => { };
+    const interrupted = new Promise((_resolve, reject) => { interrupt = reject; });
+    const timedOut = () => new CacheSerializationError({ code: 'stream_timeout', message: 'Cache stream read timed out' });
+    const aborted = () => new CacheSerializationError({ code: 'stream_aborted', message: 'Cache stream read aborted' });
+    const onAbort = () => interrupt(aborted());
+    const timer = setTimeout(() => interrupt(timedOut()), timeoutMs);
+    const deadline = performance.now() + timeoutMs;
+    signal?.addEventListener('abort', onAbort, { once: true });
+    const chunks = [];
+    let bytes = 0;
+    try {
+        while (true) {
+            if (signal?.aborted)
+                throw aborted();
+            if (performance.now() >= deadline)
+                throw timedOut();
+            const result = await Promise.race([reader.read(), interrupted]);
+            if (result.done)
+                return Buffer.concat(chunks, bytes);
+            if (!(result.value instanceof Uint8Array))
+                fail({ code: 'invalid_value', message: 'Cache stream must contain bytes' });
+            bytes += result.value.byteLength;
+            if (bytes > maxBytes || chunks.length >= maxChunks)
+                fail({ code: 'limit_exceeded', message: 'Cache stream byte or chunk limit exceeded' });
+            chunks.push(Buffer.from(result.value));
+        }
+    }
+    catch (error) {
+        // Cancellation hooks belong to the producer and may never settle; do not let them defeat the deadline.
+        void reader.cancel(error).catch(() => { });
+        throw error;
+    }
+    finally {
+        clearTimeout(timer);
+        signal?.removeEventListener('abort', onAbort);
+        reader.releaseLock();
+    }
+}
+export function createCacheStream({ bytes }) {
+    const copy = Buffer.from(bytes);
+    return new ReadableStream({ start(controller) { controller.enqueue(copy); controller.close(); } });
+}

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

@@ -0,0 +1,54 @@
+/** A fresh generation is mandatory for every activation, including rollback. */
+export interface NextCacheNamespace {
+    applicationId: string;
+    environment: string;
+    releaseId: string;
+    generation: string;
+}
+export interface CacheWriteTicket {
+    incarnation: string;
+    epoch: number;
+    version: string;
+    startedAt: number;
+}
+export interface CacheLookup {
+    ticket: CacheWriteTicket;
+    entry?: {
+        payload: string;
+        stale: boolean;
+    };
+}
+export interface CacheLocation {
+    namespace: NextCacheNamespace;
+    key: string;
+}
+export interface CacheCommit extends CacheLocation {
+    ticket: CacheWriteTicket;
+    payload: string;
+    tags: string[];
+    ttlMs: number;
+}
+/** Each method is atomic. Cache writes must use the ticket from before rendering. */
+export interface NextCacheStore {
+    read(input: CacheLocation & {
+        tags: string[];
+    }): Promise<CacheLookup>;
+    commit(input: CacheCommit): Promise<boolean>;
+    invalidate(input: {
+        namespace: NextCacheNamespace;
+        tags: string[];
+        expireAfterMs?: number;
+    }): Promise<void>;
+}
+export declare const MAX_CACHE_TAGS = 128;
+export declare const MAX_CACHE_TAG_BYTES = 256;
+export declare const MAX_CACHE_ENTRY_BYTES: number;
+export declare const MAX_CACHE_ENTRY_AGE_MS: number;
+export declare const MAX_CACHE_WRITE_AGE_MS: number;
+export declare const MAX_NAMESPACE_TAGS = 10000;
+export declare function cacheDigest(value: string): string;
+export declare function cacheNamespacePrefix(namespace: NextCacheNamespace): string;
+export declare function cacheEntryKey({ namespace, key }: CacheLocation): string;
+export declare function normalizeCacheTags(tags: string[]): string[];
+export declare function validateCacheCommit(input: CacheCommit): void;
+export declare function validateExpiration(expireAfterMs?: number): void;