egaki 0.6.0 → 0.7.1

package/dist/cli/cached-generate.js

@@ -0,0 +1,208 @@
+// General-purpose persisted memoization for expensive async functions.
+//
+// cachedGenerate() wraps any async function with:
+//   - Deterministic filesystem caching (params → stable hash → file)
+//   - Concurrent call deduplication (same key → same promise)
+//   - Stale fallback management (old results moved to stale/ subfolder)
+//   - Progress tracking (namespace-based, drives the player toolbar UI)
+//
+// Binary params (Uint8Array) are auto-hashed in the cache key. The caller
+// only provides a generate function, a serializer, and a namespace.
+//
+// Usage:
+//   const generateImage = cachedGenerate({
+//     namespace: 'image',
+//     prefixFrom: (p) => p.prompt,
+//     generate: (p) => generateImageUncached(p).then(r => r.images[0]!),
+//     serialize: (file) => ({ bytes: file.uint8Array, extension: '.png' }),
+//   })
+import fs from 'node:fs';
+import path from 'node:path';
+import { stableJsonKey, hashKey, promptPrefix, generatedDir, findCachedFile, findFallbackFile, moveFileToStale, generationQueue, formatKeyParams, } from './cache-utils.js';
+const generationRegistry = globalThis.__egakiGenerationRegistry ??= new Map();
+const progressListeners = globalThis.__egakiProgressListeners ??= new Set();
+function notifyProgressListeners() {
+    for (const listener of progressListeners) {
+        try {
+            listener();
+        }
+        catch { /* listener errors are non-fatal */ }
+    }
+}
+/** Subscribe to generation progress changes. Returns an unsubscribe function. */
+export function onProgressChange(listener) {
+    progressListeners.add(listener);
+    return () => { progressListeners.delete(listener); };
+}
+/** Recent generation errors, drained on each getGenerationProgress() call
+ *  so each SSE event includes errors that happened since the last yield. */
+const recentErrors = globalThis.__egakiRecentErrors ??= [];
+/** Get a snapshot of all active generations with elapsed time computed.
+ *  Drains the error queue so each call returns only new errors since last read. */
+export function getGenerationProgress() {
+    const now = Date.now();
+    const generations = [];
+    const counts = {};
+    for (const [key, entry] of generationRegistry) {
+        generations.push({ ...entry, key, elapsedMs: now - entry.startedAt });
+        counts[entry.namespace] = (counts[entry.namespace] ?? 0) + 1;
+    }
+    const total = generations.length;
+    const errors = recentErrors.splice(0);
+    return {
+        generations,
+        errors,
+        summary: { counts, total },
+        done: total === 0 && errors.length === 0,
+    };
+}
+function registerGeneration(key, entry) {
+    generationRegistry.set(key, entry);
+    notifyProgressListeners();
+}
+function unregisterGeneration(key, error) {
+    const entry = generationRegistry.get(key);
+    if (entry && error) {
+        recentErrors.push({
+            key,
+            namespace: entry.namespace,
+            label: entry.label,
+            model: entry.model,
+            error,
+            durationMs: Date.now() - entry.startedAt,
+        });
+    }
+    generationRegistry.delete(key);
+    notifyProgressListeners();
+}
+// ---------------------------------------------------------------------------
+// Auto cache key — recursively walks params, hashes Uint8Array values,
+// strips undefined. Handles nested objects and arrays of any depth.
+// ---------------------------------------------------------------------------
+function normalizeCacheValue(value) {
+    if (value === undefined)
+        return undefined;
+    if (value instanceof Uint8Array)
+        return hashKey(value);
+    if (Array.isArray(value))
+        return value.map(normalizeCacheValue);
+    if (value && typeof value === 'object') {
+        return Object.fromEntries(Object.entries(value)
+            .filter(([, v]) => v !== undefined)
+            .map(([k, v]) => [k, normalizeCacheValue(v)]));
+    }
+    return value;
+}
+function autoCacheKey(params) {
+    return normalizeCacheValue(params);
+}
+/** Compute cache info for a given namespace and params without starting generation.
+ *  Used by server components to check cache and find fallback synchronously. */
+export function getCacheInfo(namespace, params, prefixText) {
+    const keyParams = autoCacheKey(params);
+    // Note: getCacheInfo uses the raw params. If a cachedGenerate wrapper uses
+    // cacheKey to exclude fields, the caller should pass the same subset here.
+    const key = stableJsonKey(keyParams);
+    const hash = hashKey(key);
+    const dir = generatedDir(namespace);
+    const prefix = promptPrefix(prefixText);
+    const cached = findCachedFile(dir, hash);
+    const fallback = cached ? undefined : findFallbackFile(dir, prefix, hash);
+    const fallbackSrc = fallback
+        ? `/generated/${namespace}/${fallback.inStale ? 'stale/' : ''}${fallback.filename}`
+        : undefined;
+    return { hash, prefix, dir, key, cached, fallback, fallbackSrc };
+}
+export function cachedGenerate(config) {
+    const { namespace, prefixFrom, cacheKey, generate, serialize, deserialize, modelFrom, postWrite } = config;
+    function cachedFn(params) {
+        const rawKeyParams = cacheKey ? cacheKey(params) : params;
+        const keyParams = autoCacheKey(rawKeyParams);
+        const key = stableJsonKey(keyParams);
+        const hash = hashKey(key);
+        const dir = generatedDir(namespace);
+        const prefix = promptPrefix(prefixFrom(params));
+        // Queue key includes namespace to prevent cross-namespace collisions.
+        // Two wrappers with different namespaces but identical params must not
+        // share the same in-flight promise.
+        const queueKey = `${namespace}:${key}`;
+        // 1. Cache hit — return immediately
+        const cached = findCachedFile(dir, hash);
+        if (cached) {
+            const urlPath = `/generated/${namespace}/${cached}`;
+            const filePath = path.join(dir, cached);
+            if (deserialize) {
+                return Promise.resolve(deserialize({ urlPath, filePath }));
+            }
+            return Promise.resolve({ src: urlPath });
+        }
+        // 2. Dedup — return pending promise if same key is in-flight
+        const pending = generationQueue.get(queueKey);
+        if (pending)
+            return pending;
+        // 3. Find stale fallback for cleanup after generation
+        const fallback = findFallbackFile(dir, prefix, hash);
+        // 4. Register progress
+        const regKey = `${namespace}:${hash}`;
+        const label = prefixFrom(params);
+        registerGeneration(regKey, {
+            namespace,
+            label,
+            model: modelFrom?.(params),
+            startedAt: Date.now(),
+            params: keyParams,
+        });
+        // 5. Generate, serialize, write to disk
+        // The entire body is wrapped in try/catch so that failures in serialize(),
+        // fs.writeFileSync(), or deserialize() also unregister progress and return
+        // Error instead of throwing through the promise.
+        const promise = (async () => {
+            try {
+                console.log(`[egaki] generating ${namespace}: ${prefix}-${hash} (${formatKeyParams(keyParams)})`);
+                const result = await generate(params);
+                const serialized = serialize(result, params);
+                const finalPrefix = serialized.prefix ? promptPrefix(serialized.prefix) : prefix;
+                const filename = `${finalPrefix}-${hash}${serialized.extension}`;
+                const filePath = path.join(dir, filename);
+                if ('bytes' in serialized) {
+                    fs.writeFileSync(filePath, serialized.bytes);
+                }
+                else {
+                    fs.writeFileSync(filePath, JSON.stringify(serialized.json, null, 2));
+                }
+                if (postWrite) {
+                    try {
+                        postWrite(filePath, result, params);
+                    }
+                    catch (e) {
+                        console.error(`[egaki] postWrite error for ${namespace}:`, e);
+                    }
+                }
+                console.log(`[egaki] generated ${namespace}: ${filename}`);
+                if (fallback)
+                    moveFileToStale(dir, fallback);
+                unregisterGeneration(regKey);
+                const urlPath = `/generated/${namespace}/${filename}`;
+                if (deserialize) {
+                    return deserialize({ urlPath, filePath });
+                }
+                return { src: urlPath };
+            }
+            catch (err) {
+                const error = err instanceof Error ? err : new Error(String(err));
+                unregisterGeneration(regKey, error.message);
+                return error;
+            }
+            finally {
+                generationQueue.delete(queueKey);
+            }
+        })();
+        generationQueue.set(queueKey, promise);
+        return promise;
+    }
+    cachedFn.getCacheInfo = function (params) {
+        const rawKeyParams = cacheKey ? cacheKey(params) : params;
+        return getCacheInfo(namespace, rawKeyParams, prefixFrom(params));
+    };
+    return cachedFn;
+}

package/dist/cli/cached-generate.test.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Tests for cachedGenerate — the general-purpose persisted memoization HOF.
+ *
+ * Uses a temp directory as the project root so tests are isolated and don't
+ * touch the real public/generated/ folder. Tests verify: cache hit/miss,
+ * dedup of concurrent calls, stale fallback management, auto-hashing of
+ * Uint8Array params, JSON serialization, progress tracking, error handling,
+ * and the getCacheInfo helper.
+ */
+export {};
+//# sourceMappingURL=cached-generate.test.d.ts.map

package/dist/cli/cached-generate.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cached-generate.test.d.ts","sourceRoot":"","sources":["../../src/cli/cached-generate.test.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG"}

package/dist/cli/cached-generate.test.js

@@ -0,0 +1,431 @@
+/**
+ * Tests for cachedGenerate — the general-purpose persisted memoization HOF.
+ *
+ * Uses a temp directory as the project root so tests are isolated and don't
+ * touch the real public/generated/ folder. Tests verify: cache hit/miss,
+ * dedup of concurrent calls, stale fallback management, auto-hashing of
+ * Uint8Array params, JSON serialization, progress tracking, error handling,
+ * and the getCacheInfo helper.
+ */
+import { describe, test, expect, beforeEach, afterEach } from 'vitest';
+import fs from 'node:fs';
+import path from 'node:path';
+import os from 'node:os';
+import { cachedGenerate, getCacheInfo, getGenerationProgress, } from "./cached-generate.js";
+import { setProjectRoot } from "./cache-utils.js";
+let tmpDir;
+beforeEach(() => {
+    tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'egaki-cached-generate-test-'));
+    setProjectRoot(tmpDir);
+});
+afterEach(() => {
+    fs.rmSync(tmpDir, { recursive: true, force: true });
+});
+function makeTestConfig(overrides) {
+    let callCount = 0;
+    const config = {
+        namespace: 'test',
+        prefixFrom: (p) => p.prompt,
+        generate: async (params) => {
+            callCount++;
+            return { data: `generated-${params.prompt}` };
+        },
+        serialize: (result) => ({
+            bytes: new Uint8Array(Buffer.from(result.data)),
+            extension: '.txt',
+        }),
+        ...overrides,
+    };
+    return { config, getCallCount: () => callCount };
+}
+// ---------------------------------------------------------------------------
+// Cache hit / miss
+// ---------------------------------------------------------------------------
+describe('cache hit and miss', () => {
+    test('first call generates and writes file', async () => {
+        const { config, getCallCount } = makeTestConfig();
+        const fn = cachedGenerate(config);
+        const result = await fn({ prompt: 'hello world' });
+        expect(result).not.toBeInstanceOf(Error);
+        const r = result;
+        expect(r.src).toMatch(/^\/generated\/test\/hello-world-[a-f0-9]{8}\.txt$/);
+        expect(getCallCount()).toBe(1);
+        // File exists on disk
+        const filePath = path.join(tmpDir, 'public', r.src);
+        expect(fs.existsSync(filePath)).toBe(true);
+        expect(fs.readFileSync(filePath, 'utf-8')).toBe('generated-hello world');
+    });
+    test('second call with same params returns cached (no generation)', async () => {
+        const { config, getCallCount } = makeTestConfig();
+        const fn = cachedGenerate(config);
+        const r1 = await fn({ prompt: 'hello world' });
+        const r2 = await fn({ prompt: 'hello world' });
+        expect(r1).not.toBeInstanceOf(Error);
+        expect(r2).not.toBeInstanceOf(Error);
+        expect(r1.src).toBe(r2.src);
+        expect(getCallCount()).toBe(1); // only called once
+    });
+    test('different params generate different files', async () => {
+        const { config, getCallCount } = makeTestConfig();
+        const fn = cachedGenerate(config);
+        const r1 = await fn({ prompt: 'alpha' });
+        const r2 = await fn({ prompt: 'beta' });
+        expect(r1).not.toBeInstanceOf(Error);
+        expect(r2).not.toBeInstanceOf(Error);
+        expect(r1.src).not.toBe(r2.src);
+        expect(getCallCount()).toBe(2);
+    });
+});
+// ---------------------------------------------------------------------------
+// Concurrent dedup
+// ---------------------------------------------------------------------------
+describe('deduplication', () => {
+    test('concurrent calls with same params return same promise', async () => {
+        let resolveGenerate;
+        const { config } = makeTestConfig({
+            generate: () => new Promise((resolve) => { resolveGenerate = resolve; }),
+        });
+        const fn = cachedGenerate(config);
+        const p1 = fn({ prompt: 'dedup test' });
+        const p2 = fn({ prompt: 'dedup test' });
+        // Resolve the single generation
+        resolveGenerate({ data: 'result' });
+        const [r1, r2] = await Promise.all([p1, p2]);
+        expect(r1).not.toBeInstanceOf(Error);
+        expect(r2).not.toBeInstanceOf(Error);
+        expect(r1.src).toBe(r2.src);
+    });
+});
+// ---------------------------------------------------------------------------
+// Stale fallback management
+// ---------------------------------------------------------------------------
+describe('stale management', () => {
+    test('changing params moves old file to stale/', async () => {
+        const { config } = makeTestConfig();
+        const fn = cachedGenerate(config);
+        // Generate first version
+        const r1 = await fn({ prompt: 'hello world', seed: 1 });
+        expect(r1).not.toBeInstanceOf(Error);
+        const firstFile = path.basename(r1.src);
+        // Generate with different seed but same prompt prefix
+        const r2 = await fn({ prompt: 'hello world', seed: 2 });
+        expect(r2).not.toBeInstanceOf(Error);
+        // Old file should be in stale/
+        const staleDir = path.join(tmpDir, 'public', 'generated', 'test', 'stale');
+        const staleFiles = fs.existsSync(staleDir) ? fs.readdirSync(staleDir) : [];
+        expect(staleFiles).toContain(firstFile);
+    });
+});
+// ---------------------------------------------------------------------------
+// Auto-hashing Uint8Array params
+// ---------------------------------------------------------------------------
+describe('Uint8Array auto-hashing', () => {
+    test('same bytes produce same cache key', async () => {
+        const { config, getCallCount } = makeTestConfig();
+        const fn = cachedGenerate(config);
+        const data = new Uint8Array([1, 2, 3]);
+        const r1 = await fn({ prompt: 'with data', inputData: data });
+        const r2 = await fn({ prompt: 'with data', inputData: new Uint8Array([1, 2, 3]) });
+        expect(getCallCount()).toBe(1); // same key → cached
+        expect(r1.src).toBe(r2.src);
+    });
+    test('different bytes produce different cache keys', async () => {
+        const { config, getCallCount } = makeTestConfig();
+        const fn = cachedGenerate(config);
+        await fn({ prompt: 'with data', inputData: new Uint8Array([1, 2, 3]) });
+        await fn({ prompt: 'with data', inputData: new Uint8Array([4, 5, 6]) });
+        expect(getCallCount()).toBe(2);
+    });
+});
+// ---------------------------------------------------------------------------
+// JSON serialization
+// ---------------------------------------------------------------------------
+describe('JSON serialization', () => {
+    test('json serialize writes .json and deserialize reads it back', async () => {
+        const fn = cachedGenerate({
+            namespace: 'json-test',
+            prefixFrom: (p) => p.query,
+            generate: async (params) => ({ items: [params.query, 'b', 'c'] }),
+            serialize: (result) => ({
+                json: result,
+                extension: '.json',
+            }),
+            deserialize: ({ filePath }) => JSON.parse(fs.readFileSync(filePath, 'utf-8')),
+        });
+        const r1 = await fn({ query: 'search term' });
+        expect(r1).not.toBeInstanceOf(Error);
+        expect(r1.items).toEqual(['search term', 'b', 'c']);
+        // Second call reads from cache
+        const r2 = await fn({ query: 'search term' });
+        expect(r2).not.toBeInstanceOf(Error);
+        expect(r2.items).toEqual(['search term', 'b', 'c']);
+    });
+});
+// ---------------------------------------------------------------------------
+// Prefix override from serialize
+// ---------------------------------------------------------------------------
+describe('prefix override', () => {
+    test('serialize can return a prefix to override the filename', async () => {
+        const fn = cachedGenerate({
+            namespace: 'prefix-test',
+            prefixFrom: () => 'initial',
+            generate: async () => ({ text: 'the actual content is here' }),
+            serialize: (result) => ({
+                bytes: new Uint8Array(Buffer.from(result.text)),
+                extension: '.txt',
+                prefix: 'the actual content is here',
+            }),
+        });
+        const r = await fn({ id: '123' });
+        expect(r).not.toBeInstanceOf(Error);
+        // The filename should use the override prefix, not 'initial'
+        expect(r.src).toMatch(/the-actual-content-is-here/);
+        expect(r.src).not.toMatch(/initial/);
+    });
+});
+// ---------------------------------------------------------------------------
+// Progress tracking
+// ---------------------------------------------------------------------------
+describe('progress tracking', () => {
+    test('generation is registered and unregistered', async () => {
+        let resolveGenerate;
+        const fn = cachedGenerate({
+            namespace: 'progress-test',
+            prefixFrom: (p) => p.prompt,
+            modelFrom: (p) => `model-${p.seed}`,
+            generate: () => new Promise((resolve) => { resolveGenerate = resolve; }),
+            serialize: (result) => ({
+                bytes: new Uint8Array(Buffer.from(result.data)),
+                extension: '.txt',
+            }),
+        });
+        const promise = fn({ prompt: 'tracking test', seed: 42 });
+        // While generating, progress should show the entry
+        const progress = getGenerationProgress();
+        expect(progress.summary.total).toBe(1);
+        expect(progress.summary.counts['progress-test']).toBe(1);
+        expect(progress.generations[0]?.namespace).toBe('progress-test');
+        expect(progress.generations[0]?.label).toBe('tracking test');
+        expect(progress.generations[0]?.model).toBe('model-42');
+        // Resolve the generation
+        resolveGenerate({ data: 'done' });
+        await promise;
+        // After completion, progress should be empty
+        const after = getGenerationProgress();
+        expect(after.summary.total).toBe(0);
+    });
+    test('failed generation reports error in progress', async () => {
+        const fn = cachedGenerate({
+            namespace: 'error-progress',
+            prefixFrom: (p) => p.prompt,
+            generate: async () => { throw new Error('API failed'); },
+            serialize: (result) => ({
+                bytes: new Uint8Array(Buffer.from(result.data)),
+                extension: '.txt',
+            }),
+        });
+        const result = await fn({ prompt: 'fail test' });
+        expect(result).toBeInstanceOf(Error);
+        expect(result.message).toBe('API failed');
+        // Error should be in the progress drain
+        const progress = getGenerationProgress();
+        expect(progress.errors.length).toBe(1);
+        expect(progress.errors[0]?.error).toBe('API failed');
+        expect(progress.errors[0]?.namespace).toBe('error-progress');
+        // Errors drain on read — second call should have none
+        const progress2 = getGenerationProgress();
+        expect(progress2.errors.length).toBe(0);
+    });
+});
+// ---------------------------------------------------------------------------
+// Error handling
+// ---------------------------------------------------------------------------
+describe('error handling', () => {
+    test('generate throwing returns Error', async () => {
+        const fn = cachedGenerate({
+            namespace: 'error-test',
+            prefixFrom: (p) => p.prompt,
+            generate: async () => { throw new Error('boom'); },
+            serialize: (result) => ({
+                bytes: new Uint8Array(Buffer.from(result.data)),
+                extension: '.txt',
+            }),
+        });
+        const result = await fn({ prompt: 'error test' });
+        expect(result).toBeInstanceOf(Error);
+        expect(result.message).toBe('boom');
+    });
+    test('non-Error throw is wrapped in Error', async () => {
+        const fn = cachedGenerate({
+            namespace: 'error-test-2',
+            prefixFrom: (p) => p.prompt,
+            generate: async () => { throw 'string error'; },
+            serialize: (result) => ({
+                bytes: new Uint8Array(Buffer.from(result.data)),
+                extension: '.txt',
+            }),
+        });
+        const result = await fn({ prompt: 'string error test' });
+        expect(result).toBeInstanceOf(Error);
+        expect(result.message).toBe('string error');
+    });
+    test('failed call does not cache — retry regenerates', async () => {
+        let shouldFail = true;
+        const fn = cachedGenerate({
+            namespace: 'retry-test',
+            prefixFrom: (p) => p.prompt,
+            generate: async (params) => {
+                if (shouldFail)
+                    throw new Error('temporary failure');
+                return { data: `ok-${params.prompt}` };
+            },
+            serialize: (result) => ({
+                bytes: new Uint8Array(Buffer.from(result.data)),
+                extension: '.txt',
+            }),
+        });
+        const r1 = await fn({ prompt: 'retry' });
+        expect(r1).toBeInstanceOf(Error);
+        shouldFail = false;
+        const r2 = await fn({ prompt: 'retry' });
+        expect(r2).not.toBeInstanceOf(Error);
+        expect(r2.src).toMatch(/\/generated\/retry-test\//);
+    });
+});
+// ---------------------------------------------------------------------------
+// Namespace isolation in dedup queue
+// ---------------------------------------------------------------------------
+describe('namespace isolation', () => {
+    test('same params in different namespaces generate independently', async () => {
+        let imageCallCount = 0;
+        let videoCallCount = 0;
+        const imageFn = cachedGenerate({
+            namespace: 'ns-image',
+            prefixFrom: (p) => p.prompt,
+            generate: async (params) => {
+                imageCallCount++;
+                return { data: `image-${params.prompt}` };
+            },
+            serialize: (result) => ({
+                bytes: new Uint8Array(Buffer.from(result.data)),
+                extension: '.png',
+            }),
+        });
+        const videoFn = cachedGenerate({
+            namespace: 'ns-video',
+            prefixFrom: (p) => p.prompt,
+            generate: async (params) => {
+                videoCallCount++;
+                return { data: `video-${params.prompt}` };
+            },
+            serialize: (result) => ({
+                bytes: new Uint8Array(Buffer.from(result.data)),
+                extension: '.mp4',
+            }),
+        });
+        const [imgResult, vidResult] = await Promise.all([
+            imageFn({ prompt: 'same params' }),
+            videoFn({ prompt: 'same params' }),
+        ]);
+        expect(imgResult).not.toBeInstanceOf(Error);
+        expect(vidResult).not.toBeInstanceOf(Error);
+        expect(imageCallCount).toBe(1);
+        expect(videoCallCount).toBe(1);
+        // Different src paths
+        expect(imgResult.src).toMatch(/ns-image/);
+        expect(vidResult.src).toMatch(/ns-video/);
+    });
+});
+// ---------------------------------------------------------------------------
+// Recursive Uint8Array hashing
+// ---------------------------------------------------------------------------
+describe('recursive binary hashing', () => {
+    test('nested Uint8Array values produce stable cache keys', async () => {
+        const { config, getCallCount } = makeTestConfig();
+        const fn = cachedGenerate(config);
+        // Pass nested binary data inside an object
+        const r1 = await fn({ prompt: 'nested', inputData: new Uint8Array([10, 20, 30]) });
+        const r2 = await fn({ prompt: 'nested', inputData: new Uint8Array([10, 20, 30]) });
+        expect(getCallCount()).toBe(1); // same nested bytes → cached
+    });
+});
+// ---------------------------------------------------------------------------
+// Serialize failure handling
+// ---------------------------------------------------------------------------
+describe('serialize failure', () => {
+    test('serialize throwing unregisters progress and returns Error', async () => {
+        // Drain any leftover errors from previous tests
+        getGenerationProgress();
+        const fn = cachedGenerate({
+            namespace: 'serialize-fail',
+            prefixFrom: (p) => p.prompt,
+            generate: async () => ({ data: 'ok' }),
+            serialize: () => { throw new Error('serialize exploded'); },
+        });
+        const result = await fn({ prompt: 'serialize test' });
+        expect(result).toBeInstanceOf(Error);
+        expect(result.message).toBe('serialize exploded');
+        // Progress should be clean — no stuck entries
+        const progress = getGenerationProgress();
+        expect(progress.summary.total).toBe(0);
+        // Error should be in the drain
+        expect(progress.errors.length).toBe(1);
+        expect(progress.errors[0]?.error).toBe('serialize exploded');
+    });
+});
+// ---------------------------------------------------------------------------
+// cacheKey config excludes non-identity fields
+// ---------------------------------------------------------------------------
+describe('cacheKey config', () => {
+    test('excluded fields do not affect cache identity', async () => {
+        let callCount = 0;
+        const fn = cachedGenerate({
+            namespace: 'cachekey-test',
+            prefixFrom: (p) => p.label ?? p.query,
+            cacheKey: ({ label, ...rest }) => rest,
+            generate: async (params) => {
+                callCount++;
+                return { data: `result-${params.query}` };
+            },
+            serialize: (result) => ({
+                bytes: new Uint8Array(Buffer.from(result.data)),
+                extension: '.txt',
+            }),
+        });
+        await fn({ query: 'search', label: 'label-a' });
+        await fn({ query: 'search', label: 'label-b' });
+        // Same query, different labels → should be same cache entry
+        expect(callCount).toBe(1);
+    });
+});
+// ---------------------------------------------------------------------------
+// getCacheInfo helper
+// ---------------------------------------------------------------------------
+describe('getCacheInfo', () => {
+    test('returns cache miss before any generation', () => {
+        const info = getCacheInfo('test-ns', { prompt: 'hello' }, 'hello');
+        expect(info.cached).toBeUndefined();
+        expect(info.hash).toMatch(/^[a-f0-9]{8}$/);
+        expect(info.prefix).toBe('hello');
+    });
+    test('returns cache hit after generation', async () => {
+        const { config } = makeTestConfig();
+        const fn = cachedGenerate(config);
+        await fn({ prompt: 'cached info test' });
+        const info = getCacheInfo('test', { prompt: 'cached info test' }, 'cached info test');
+        expect(info.cached).toBeDefined();
+        expect(info.cached).toMatch(/cached-info-test-[a-f0-9]{8}\.txt/);
+    });
+    test('returns fallbackSrc when a previous generation exists', async () => {
+        const { config } = makeTestConfig();
+        const fn = cachedGenerate(config);
+        // Generate first version
+        await fn({ prompt: 'fallback test', seed: 1 });
+        // Query for a different version that doesn't exist yet
+        // Version 1 is in the main dir and should be found as fallback
+        const info = getCacheInfo('test', { prompt: 'fallback test', seed: 2 }, 'fallback test');
+        expect(info.cached).toBeUndefined();
+        expect(info.fallbackSrc).toBeDefined();
+        expect(info.fallbackSrc).toMatch(/\/generated\/test\/fallback-test-/);
+    });
+});

package/dist/cli/cartesia-provider.d.ts

@@ -0,0 +1,16 @@
+import type { SpeechProvider } from './speech-generate.js';
+import type { WordTimestamp } from './transcription-generate.js';
+/**
+ * Parse a Cartesia SSE stream into audio chunks and word timestamps.
+ * Uses eventsource-parser for robust SSE frame parsing.
+ */
+export declare function parseCartesiaSseStream(body: ReadableStream<Uint8Array>): Promise<{
+    audioChunks: Uint8Array[];
+    timestamps: WordTimestamp[];
+}>;
+/**
+ * Create a Cartesia speech provider using the SSE endpoint with word timestamps.
+ * Returns raw PCM audio (pcm_s16le) since the SSE endpoint only supports raw container.
+ */
+export declare function createCartesiaSpeechProvider(): SpeechProvider;
+//# sourceMappingURL=cartesia-provider.d.ts.map

package/dist/cli/cartesia-provider.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cartesia-provider.d.ts","sourceRoot":"","sources":["../../src/cli/cartesia-provider.ts"],"names":[],"mappings":"AAkBA,OAAO,KAAK,EAAE,cAAc,EAA+C,MAAM,sBAAsB,CAAA;AACvG,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,6BAA6B,CAAA;AA8DhE;;;GAGG;AACH,wBAAsB,sBAAsB,CAC1C,IAAI,EAAE,cAAc,CAAC,UAAU,CAAC,GAC/B,OAAO,CAAC;IAAE,WAAW,EAAE,UAAU,EAAE,CAAC;IAAC,UAAU,EAAE,aAAa,EAAE,CAAA;CAAE,CAAC,CAsCrE;AAqDD;;;GAGG;AACH,wBAAgB,4BAA4B,IAAI,cAAc,CA6D7D"}