@lumenkey/cli 0.3.1 → 0.4.0-rc.1

package/dist/studio/output-save-worker.d.ts

@@ -0,0 +1,40 @@
+import { assetFetch } from '../core/client.js';
+import type { LumenKeyConfig } from '../core/types.js';
+import type { StudioAssetStore } from './asset-store.js';
+import type { SaveOperation } from './output-save-contract.js';
+export interface SaveWorkerHooks {
+    afterAcceptedCommit?(): void | Promise<void>;
+    duringDownload?(bytes: number): void | Promise<void>;
+    afterLinkBeforeUnlink?(): void | Promise<void>;
+    afterFilePublishBeforeCheckpoint?(): void | Promise<void>;
+    beforeCatalogCommit?(): void | Promise<void>;
+    afterCatalogBeforeRelation?(): void | Promise<void>;
+    afterRelationBeforeResponse?(): void | Promise<void>;
+}
+export interface OutputSaveWorker {
+    enqueue(id: string): void;
+    idle(): Promise<void>;
+    close(): Promise<void>;
+    recover(): Promise<void>;
+    retry(id: string, connectionId: string, revision: number): Promise<SaveOperation>;
+    suspend(connectionId: string): void;
+    activate(connectionId: string): void;
+    progress(id: string, revision: number, attempt: number): {
+        receivedBytes: number;
+        totalBytes: number | null;
+    } | null;
+}
+/** Serial executor per root writer. Transport and file IO never hold its journal queue.
+ * Construction is internal DI; HTTP cannot choose a transport, path or fault hook. */
+export declare function createOutputSaveWorker(options: {
+    store: StudioAssetStore;
+    outputDir: string;
+    maxBytes?: number;
+    fetchAsset?: typeof assetFetch;
+    hooks?: SaveWorkerHooks;
+    loadConfig?(): LumenKeyConfig | Promise<LumenKeyConfig>;
+    refreshJob?(operation: SaveOperation, signal: AbortSignal): Promise<unknown>;
+    /** Internal clock DI only; production deadline is always 120000ms. */
+    armDeadline?(milliseconds: number, expire: () => void): () => void;
+}): OutputSaveWorker;
+//# sourceMappingURL=output-save-worker.d.ts.map

package/dist/studio/output-save-worker.js

@@ -0,0 +1,360 @@
+import { open } from 'node:fs/promises';
+import path from 'node:path';
+import { assetFetch, LumenKeyError, LumenKeyClient } from '../core/client.js';
+import { studioBindingDigest } from './cloud-service.js';
+import { streamAssetBodyToFile } from '../core/asset-stream.js';
+import { cloudDiagnostic, projectOutputViews, projectJob } from './cloud-contract.js';
+import { detectStudioMediaType, mediaExtensions } from './media.js';
+import { assertStudioRoot, prepareStudioRoot } from './paths.js';
+import { hasFsCode, StudioError } from './errors.js';
+import { reconcilePublishedSaveFile, reconcilePartialSaveFile } from './output-save-recovery.js';
+import { SaveIntegrityPending } from './output-save-journal.js';
+const workers = new WeakMap();
+const workerCodes = ['SAVE_REGISTRATION_PENDING', 'SAVE_RELATION_PENDING', 'SAVE_AUTHORITY_INVALID', 'SAVE_AUTHORITY_UNAVAILABLE', 'SAVE_BINDING_REQUIRED', 'SAVE_BINDING_MISMATCH', 'SAVE_PATH_UNSAFE', 'SAVE_TARGET_CONFLICT', 'SAVE_WRITE_FAILED', 'SAVE_NETWORK_ERROR', 'SAVE_DOWNLOAD_TIMEOUT', 'SAVE_MEDIA_TOO_LARGE', 'SAVE_MEDIA_UNSUPPORTED', 'SAVE_LENGTH_MISMATCH', 'SAVE_SOURCE_UNAVAILABLE', 'SAVE_OUTPUT_IDENTITY_CONFLICT', 'SAVE_CLOUD_CONFIG_REQUIRED', 'SAVE_REVISION_CONFLICT'];
+function workerCode(code) { return workerCodes.find(value => value === code) ?? 'SAVE_WRITE_FAILED'; }
+function pendingCode(op) { return !op.transfer?.completed ? null : op.receipt.facts.registration === 'ABSENT' ? 'SAVE_REGISTRATION_PENDING' : op.receipt.facts.registration === 'PRESENT' && op.receipt.facts.relation === 'ABSENT' ? 'SAVE_RELATION_PENDING' : null; }
+function diagnostic(code, retryable, mayAlreadyBeSaved) { return { ...cloudDiagnostic(new StudioError(code, 409)), retryable, mayAlreadyBeSaved }; }
+/** Serial executor per root writer. Transport and file IO never hold its journal queue.
+ * Construction is internal DI; HTTP cannot choose a transport, path or fault hook. */
+export function createOutputSaveWorker(options) {
+    const existing = workers.get(options.store);
+    if (existing)
+        return existing;
+    const limit = Math.min(128 * 1024 * 1024, options.store.maxBytes, options.maxBytes ?? 128 * 1024 * 1024);
+    if (!Number.isSafeInteger(limit) || limit < 1)
+        throw new StudioError('STUDIO_INPUT_INVALID');
+    let queue = Promise.resolve();
+    let closed = false;
+    let controller;
+    let closePromise;
+    let activeConnection;
+    const suspended = new Set();
+    const scheduled = new Set();
+    const progress = new Map();
+    const failures = [];
+    async function recoveryFailure(op, code, published = false) {
+        if (code !== 'SAVE_WRITE_FAILED' || !op.transfer?.completed || (!published && !['FILE_READY', 'REGISTERED'].includes(op.receipt.stage)))
+            return { code, safeRetry: false };
+        // Classifying a fault must not publish or unlink: recovery owns those writes.
+        try {
+            await reconcilePublishedSaveFile(options.outputDir, op, limit, undefined, true);
+            const pending = pendingCode(op);
+            return pending ? { code: pending, safeRetry: true } : { code, safeRetry: false };
+        }
+        catch (error) {
+            return { code: workerCode(error instanceof StudioError ? error.code : 'SAVE_WRITE_FAILED'), safeRetry: false };
+        }
+    }
+    async function localRecovery(original) {
+        // Observation is read-only diagnostics but temporarily disables safeRetry.
+        // Do not reconcile through a live check or reinterpret it as a save fault.
+        if (original.receipt.integrityCheck === 'PENDING')
+            return original;
+        let op = original;
+        const update = async (patch) => op = await options.store.saveAuthority.advanceWorker(op, patch);
+        if (['ACCEPTED', 'SAVING'].includes(op.receipt.state) || (op.receipt.state === 'FAILED' && op.receipt.retryable && pendingCode(op))) {
+            const code = pendingCode(op);
+            await update({ state: 'RECOVERY_REQUIRED', stage: 'RECONCILING', safeRetry: false, retryable: true, error: code ? diagnostic(code, true, true) : null, ...(code ? { mayAlreadyBeSaved: true } : {}) });
+        }
+        if (op.receipt.state === 'SAVED' || op.receipt.state === 'BLOCKED')
+            return op;
+        try {
+            const authority = await options.store.saveAuthority.read();
+            const run = (await options.store.runs.read()).runs.find(r => r.runId === op.receipt.runId);
+            const digest = authority.connections.find(c => c.connectionId === op.connectionId)?.bindingDigestRef;
+            if (!run || run.binding !== digest || run.job?.jobId !== op.receipt.jobId)
+                throw new StudioError('SAVE_BINDING_MISMATCH', 403);
+            if (!op.transfer?.completed) {
+                await reconcilePartialSaveFile(options.outputDir, op);
+                return update({ safeRetry: true, retryable: true, mayAlreadyBeSaved: false, error: op.receipt.state === 'FAILED' && op.receipt.error ? { ...op.receipt.error, mayAlreadyBeSaved: false } : null, facts: { file: 'ABSENT', registration: 'ABSENT', relation: 'ABSENT' } });
+            }
+            const evidence = await reconcilePublishedSaveFile(options.outputDir, op, limit);
+            // Ownership revalidation permits this SAME operation's local reconciliation,
+            // not a fresh download or an integrity VERIFIED claim.
+            const pending = pendingCode(op);
+            await update({ safeRetry: true, retryable: true, mayAlreadyBeSaved: true, error: pending ? diagnostic(pending, true, true) : null });
+            if (op.receipt.integrityCheck === 'PENDING')
+                return op;
+            await update({ state: 'SAVING', stage: 'RECONCILING', attempt: op.receipt.attempt + 1, safeRetry: false, error: null });
+            const asset = { assetId: op.assetId, displayName: path.basename(evidence.completed.relativePath), ...evidence.completed, savedAt: op.receipt.createdAt };
+            await update({ stage: 'FILE_READY', facts: { file: 'NOT_CHECKED', registration: op.receipt.facts.registration, relation: op.receipt.facts.relation }, mayAlreadyBeSaved: true });
+            await options.hooks?.beforeCatalogCommit?.();
+            await options.store.registerExistingManagedFile(asset);
+            await update({ stage: 'REGISTERED', asset: { ...assetReceipt(asset), absolutePath: evidence.absolutePath }, facts: { file: 'NOT_CHECKED', registration: 'PRESENT', relation: 'ABSENT' } });
+            await options.hooks?.afterCatalogBeforeRelation?.();
+            await update({ state: 'SAVED', stage: 'LINKED', facts: { file: 'NOT_CHECKED', registration: 'PRESENT', relation: 'PRESENT' }, checkedAt: null, error: null, safeRetry: false, retryable: false, mayAlreadyBeSaved: true });
+            await options.hooks?.afterRelationBeforeResponse?.();
+            return op;
+        }
+        catch (error) {
+            if (error instanceof SaveIntegrityPending) {
+                const current = (await options.store.saveAuthority.read()).operations.find(o => o.receipt.operationId === op.receipt.operationId);
+                if (!current)
+                    throw new StudioError('SAVE_OPERATION_NOT_FOUND', 404);
+                return current;
+            }
+            if (error instanceof StudioError && error.code === 'SAVE_REVISION_CONFLICT')
+                throw error;
+            const latest = (await options.store.saveAuthority.read()).operations.find(o => o.receipt.operationId === op.receipt.operationId);
+            if (!latest)
+                throw new StudioError('SAVE_OPERATION_NOT_FOUND', 404);
+            op = latest;
+            if (op.receipt.state === 'SAVED')
+                return op;
+            const classified = await recoveryFailure(op, workerCode(error instanceof StudioError ? error.code : 'SAVE_WRITE_FAILED'));
+            const code = classified.code;
+            const unsafe = ['SAVE_PATH_UNSAFE', 'SAVE_TARGET_CONFLICT', 'SAVE_BINDING_MISMATCH'].includes(code);
+            const retryable = !unsafe;
+            await update({ state: unsafe ? 'BLOCKED' : op.receipt.state === 'SAVING' ? 'RECOVERY_REQUIRED' : op.receipt.state, facts: { ...op.receipt.facts, file: unsafe ? 'UNSAFE' : classified.safeRetry ? 'NOT_CHECKED' : 'UNKNOWN' }, safeRetry: classified.safeRetry, retryable, mayAlreadyBeSaved: true, error: diagnostic(code, retryable, true) });
+            throw error instanceof StudioError ? error : new StudioError('SAVE_WRITE_FAILED', 409);
+        }
+    }
+    function serialize(action) {
+        const next = queue.catch(() => { }).then(action);
+        queue = next.then(() => { }, () => { });
+        return next;
+    }
+    async function containFailure(id) {
+        // An unavailable journal cannot always be amended. Preserve a safe idle()
+        // diagnostic and make a best-effort durable checkpoint once it is readable.
+        failures.push(new StudioError('SAVE_AUTHORITY_UNAVAILABLE', 503));
+        try {
+            const op = (await options.store.saveAuthority.read()).operations.find(o => o.receipt.operationId === id);
+            if (!op || !['ACCEPTED', 'SAVING'].includes(op.receipt.state))
+                return;
+            await options.store.saveAuthority.advanceWorker(op, {
+                state: 'RECOVERY_REQUIRED', safeRetry: false, retryable: true, mayAlreadyBeSaved: null,
+                error: { ...cloudDiagnostic(new StudioError('SAVE_AUTHORITY_UNAVAILABLE', 503)), retryable: true, mayAlreadyBeSaved: null },
+            });
+        }
+        catch { /* No fabricated receipt when the authority remains unavailable. */ }
+    }
+    async function execute(id) {
+        let op = (await options.store.saveAuthority.read()).operations.find(o => o.receipt.operationId === id);
+        if (!op || !(op.receipt.state === 'ACCEPTED' || (op.receipt.state === 'SAVING' && op.receipt.stage === 'RECONCILING')) || closed)
+            return;
+        progress.delete(id);
+        if (suspended.has(op.connectionId)) {
+            await options.store.saveAuthority.advanceWorker(op, { state: 'RECOVERY_REQUIRED', safeRetry: false, retryable: true });
+            return;
+        }
+        const update = async (patch, transfer) => {
+            op = await options.store.saveAuthority.advanceWorker(op, patch, transfer);
+            return op;
+        };
+        let published = false;
+        let timedOut = false;
+        let ownedTemporary = false;
+        let transportFailed = false;
+        activeConnection = op.connectionId;
+        controller = new AbortController();
+        const signal = controller.signal;
+        const expire = () => { timedOut = true; controller?.abort(); };
+        const cancelDeadline = options.armDeadline ? options.armDeadline(120_000, expire) : (() => { const timer = setTimeout(expire, 120_000); timer.unref(); return () => clearTimeout(timer); })();
+        try {
+            await options.hooks?.afterAcceptedCommit?.();
+            signal.throwIfAborted();
+            const snapshot = await options.store.saveAuthority.read();
+            const connection = snapshot.connections.find(c => c.connectionId === op.connectionId);
+            const run = (await options.store.runs.read()).runs.find(r => r.runId === op.receipt.runId);
+            if (!run || run.binding !== connection?.bindingDigestRef || run.job?.jobId !== op.receipt.jobId)
+                throw new StudioError('SAVE_BINDING_MISMATCH', 403);
+            // A persisted URL is only historical evidence. Renew through the same
+            // authenticated job identity before any asset transport is allowed.
+            let rawJob;
+            let secret;
+            if (options.refreshJob)
+                rawJob = await options.refreshJob(structuredClone(op), signal);
+            else {
+                if (!options.loadConfig)
+                    throw new StudioError('SAVE_CLOUD_CONFIG_REQUIRED', 409);
+                const config = { ...await options.loadConfig() };
+                secret = config.apiKey?.trim();
+                if (!secret || studioBindingDigest(new URL(config.baseUrl).origin, secret) !== connection.bindingDigestRef)
+                    throw new StudioError('SAVE_BINDING_MISMATCH', 403);
+                config.apiKey = secret;
+                const client = new LumenKeyClient(config);
+                client.requireKey();
+                rawJob = await client.getJob(op.receipt.jobId, { signal });
+            }
+            signal.throwIfAborted();
+            const fresh = projectJob(rawJob, secret ?? '', run.job, true);
+            if (fresh.jobId !== op.receipt.jobId)
+                throw new StudioError('SAVE_OUTPUT_IDENTITY_CONFLICT', 409);
+            const view = projectOutputViews({ ...run, job: fresh }, { rootReady: true, authorityHealthy: true }).find(v => v.localOutputId === op.receipt.localOutputId && v.gatewayAssetId?.toLowerCase() === op.receipt.gatewayAssetId.toLowerCase());
+            if (!view?.saveAllowed)
+                throw new StudioError('SAVE_SOURCE_UNAVAILABLE', 409);
+            const source = fresh.outputs.find(o => o.assetId?.toLowerCase() === op.receipt.gatewayAssetId.toLowerCase());
+            if (!source)
+                throw new StudioError('SAVE_SOURCE_UNAVAILABLE', 409);
+            const url = new URL(source.url);
+            if (url.protocol !== 'https:' || url.username || url.password)
+                throw new StudioError('SAVE_MEDIA_UNSUPPORTED', 415);
+            const root = await prepareStudioRoot(options.outputDir);
+            if (root.assetsDir !== snapshot.canonicalAssetsPath)
+                throw new StudioError('SAVE_PATH_UNSAFE', 409);
+            const attempt = op.receipt.state === 'SAVING' ? op.receipt.attempt : op.receipt.attempt + 1;
+            const transfer = { temporaryName: `${op.assetId}.${attempt}.part` };
+            await update({ state: 'SAVING', stage: 'DOWNLOADING', attempt, facts: { file: 'ABSENT', registration: 'ABSENT', relation: 'ABSENT' } }, transfer);
+            await assertStudioRoot(root);
+            signal.throwIfAborted();
+            const handle = await open(path.join(root.assetsDir, transfer.temporaryName), 'wx', 0o600);
+            ownedTemporary = true;
+            let result;
+            let declared = '';
+            try {
+                const owned = await handle.stat();
+                transfer.owner = { dev: String(owned.dev), ino: String(owned.ino), birthtimeMs: owned.birthtimeMs };
+                await update({}, transfer); // durable exclusive-open proof precedes network
+                const fetched = await (options.fetchAsset ?? assetFetch)(url.href, { redirect: 'error', signal }).catch(error => { transportFailed = true; throw error; });
+                try {
+                    if (!fetched.response.ok || !fetched.response.body)
+                        throw new StudioError('SAVE_SOURCE_UNAVAILABLE', 409);
+                    declared = (fetched.response.headers.get('content-type') ?? '').split(';')[0].trim().toLowerCase();
+                    const rawLength = fetched.response.headers.get('content-length');
+                    if (rawLength !== null && !/^\d+$/.test(rawLength))
+                        throw new StudioError('SAVE_LENGTH_MISMATCH', 422);
+                    result = await streamAssetBodyToFile(fetched.response.body, handle, { limit, signal, requireNonEmpty: true, onReadError: () => { transportFailed = true; }, ...(rawLength !== null ? { expectedBytes: Number(rawLength) } : {}), onProgress: async (receivedBytes) => {
+                            progress.set(id, { revision: op.receipt.revision, attempt: op.receipt.attempt, receivedBytes, totalBytes: rawLength !== null && Number(rawLength) > 0 ? Number(rawLength) : null });
+                            await options.hooks?.duringDownload?.(receivedBytes);
+                        } });
+                }
+                finally {
+                    await fetched.dispose();
+                }
+            }
+            finally {
+                await handle.close();
+            }
+            let mediaType;
+            try {
+                mediaType = detectStudioMediaType(result.prefix);
+            }
+            catch {
+                throw new StudioError('SAVE_MEDIA_UNSUPPORTED', 415);
+            }
+            if ((declared && declared !== 'application/octet-stream' && declared !== mediaType) || source.type !== mediaType.split('/')[0])
+                throw new StudioError('SAVE_MEDIA_UNSUPPORTED', 415);
+            const relativePath = `assets/${op.assetId}.${mediaExtensions[mediaType]}`;
+            const asset = { assetId: op.assetId, displayName: `${op.assetId}.${mediaExtensions[mediaType]}`, mediaType, relativePath, byteLength: result.byteLength, sha256: result.sha256, savedAt: op.receipt.createdAt };
+            transfer.completed = { mediaType, relativePath, byteLength: result.byteLength, sha256: result.sha256 };
+            await update({ facts: { file: 'PARTIAL', registration: 'ABSENT', relation: 'ABSENT' } }, transfer);
+            await assertStudioRoot(root);
+            signal.throwIfAborted();
+            const evidence = await reconcilePublishedSaveFile(options.outputDir, op, limit, async () => {
+                published = true;
+                await options.hooks?.afterLinkBeforeUnlink?.();
+            });
+            const absolutePath = evidence.absolutePath;
+            published = true;
+            await options.hooks?.afterFilePublishBeforeCheckpoint?.();
+            await update({ stage: 'FILE_READY', facts: { file: 'NOT_CHECKED', registration: 'ABSENT', relation: 'ABSENT' }, mayAlreadyBeSaved: true });
+            await options.hooks?.beforeCatalogCommit?.();
+            await options.store.registerExistingManagedFile(asset);
+            await update({ stage: 'REGISTERED', asset: { ...assetReceipt(asset), absolutePath }, facts: { file: 'NOT_CHECKED', registration: 'PRESENT', relation: 'ABSENT' } });
+            await options.hooks?.afterCatalogBeforeRelation?.();
+            await update({ state: 'SAVED', stage: 'LINKED', facts: { file: 'NOT_CHECKED', registration: 'PRESENT', relation: 'PRESENT' }, error: null, safeRetry: false, retryable: false, mayAlreadyBeSaved: true, checkedAt: null });
+            await options.hooks?.afterRelationBeforeResponse?.();
+        }
+        catch (error) {
+            const latest = (await options.store.saveAuthority.read()).operations.find(o => o.receipt.operationId === id);
+            if (!latest || latest.receipt.state === 'SAVED')
+                return;
+            op = latest;
+            const conflict = hasFsCode(error, 'EEXIST');
+            const initialCode = timedOut ? 'SAVE_DOWNLOAD_TIMEOUT' : conflict ? 'SAVE_TARGET_CONFLICT' : error instanceof StudioError ? error.code : error instanceof LumenKeyError && error.code === 'DOWNLOAD_TOO_LARGE' ? 'SAVE_MEDIA_TOO_LARGE' : error instanceof LumenKeyError && ['DOWNLOAD_LENGTH_MISMATCH', 'DOWNLOAD_EMPTY'].includes(error.code) ? 'SAVE_LENGTH_MISMATCH' : signal.aborted || transportFailed ? 'SAVE_NETWORK_ERROR' : 'SAVE_WRITE_FAILED';
+            const classified = await recoveryFailure(op, workerCode(initialCode), published);
+            const code = classified.code;
+            const status = code === 'SAVE_MEDIA_TOO_LARGE' ? 413 : code === 'SAVE_LENGTH_MISMATCH' ? 422 : code === 'SAVE_DOWNLOAD_TIMEOUT' || code === 'SAVE_NETWORK_ERROR' ? 503 : error instanceof StudioError ? error.status : 409;
+            const diagnostic = cloudDiagnostic(new StudioError(code, status));
+            const retryable = !conflict && !['SAVE_MEDIA_TOO_LARGE', 'SAVE_MEDIA_UNSUPPORTED', 'SAVE_LENGTH_MISMATCH', 'SAVE_PATH_UNSAFE', 'SAVE_OUTPUT_IDENTITY_CONFLICT', 'SAVE_BINDING_MISMATCH'].includes(code);
+            await update({ state: conflict || ['SAVE_PATH_UNSAFE', 'SAVE_TARGET_CONFLICT'].includes(code) ? 'BLOCKED' : published || signal.aborted ? 'RECOVERY_REQUIRED' : 'FAILED', error: { ...diagnostic, retryable, mayAlreadyBeSaved: published ? true : ownedTemporary ? null : false }, retryable, safeRetry: classified.safeRetry, mayAlreadyBeSaved: published ? true : ownedTemporary ? null : false });
+        }
+        finally {
+            cancelDeadline();
+            controller = undefined;
+            activeConnection = undefined;
+            progress.delete(id);
+        }
+    }
+    const worker = {
+        progress(id, revision, attempt) { const p = progress.get(id); return p && p.revision === revision && p.attempt === attempt ? { receivedBytes: p.receivedBytes, totalBytes: p.totalBytes } : null; },
+        suspend(connectionId) { suspended.add(connectionId); if (activeConnection === connectionId)
+            controller?.abort(); },
+        activate(connectionId) { if (!closed)
+            suspended.delete(connectionId); },
+        enqueue(id) {
+            if (closed || scheduled.has(id))
+                return;
+            scheduled.add(id);
+            queue = queue.catch(() => { }).then(() => execute(id)).catch(() => containFailure(id)).finally(() => { scheduled.delete(id); });
+        },
+        async idle() { await queue; const error = failures.shift(); if (error)
+            throw error; },
+        close() {
+            return closePromise ??= (async () => {
+                closed = true;
+                controller?.abort();
+                await queue;
+                const snapshot = await options.store.saveAuthority.read();
+                for (const op of snapshot.operations)
+                    if (['ACCEPTED', 'SAVING'].includes(op.receipt.state)) {
+                        await options.store.saveAuthority.advanceWorker(op, {
+                            state: 'RECOVERY_REQUIRED', safeRetry: false, retryable: true, mayAlreadyBeSaved: null,
+                            error: { ...cloudDiagnostic(new StudioError('SAVE_NETWORK_ERROR', 503)), retryable: true, mayAlreadyBeSaved: null },
+                        });
+                    }
+            })();
+        },
+        recover: () => serialize(async () => {
+            const snapshot = await options.store.saveAuthority.read();
+            for (const op of snapshot.operations)
+                if (['ACCEPTED', 'SAVING', 'RECOVERY_REQUIRED'].includes(op.receipt.state) || (op.receipt.state === 'FAILED' && op.receipt.retryable && ['SAVE_WRITE_FAILED', 'SAVE_NETWORK_ERROR', 'SAVE_DOWNLOAD_TIMEOUT', 'SAVE_REGISTRATION_PENDING', 'SAVE_RELATION_PENDING'].includes(op.receipt.error?.code ?? ''))) {
+                    try {
+                        await localRecovery(op);
+                    }
+                    catch (error) {
+                        if (!(error instanceof StudioError) || ['SAVE_AUTHORITY_INVALID', 'SAVE_AUTHORITY_UNAVAILABLE', 'STUDIO_JOURNAL_INVALID', 'STUDIO_CATALOG_INVALID', 'STUDIO_STORAGE_CLOSED', 'STUDIO_STORAGE_BUSY', 'STUDIO_STORAGE_FAILED', 'SAVE_REVISION_CONFLICT'].includes(error.code))
+                            throw error;
+                        const current = (await options.store.saveAuthority.read()).operations.find(o => o.receipt.operationId === op.receipt.operationId);
+                        const pending = current && ['SAVE_REGISTRATION_PENDING', 'SAVE_RELATION_PENDING'].includes(current.receipt.error?.code ?? '') && workerCode(error.code) === 'SAVE_WRITE_FAILED';
+                        if (!current || (!pending && current.receipt.error?.code !== workerCode(error.code)) || !['FAILED', 'RECOVERY_REQUIRED', 'BLOCKED'].includes(current.receipt.state))
+                            throw error;
+                        if (!pending)
+                            failures.push(error); // pending already has its classified durable diagnostic
+                    }
+                }
+        }),
+        retry: (id, connectionId, revision) => serialize(async () => {
+            const op = (await options.store.saveAuthority.read()).operations.find(o => o.receipt.operationId === id);
+            if (!op)
+                throw new StudioError('SAVE_OPERATION_NOT_FOUND', 404);
+            if (op.connectionId !== connectionId)
+                throw new StudioError('SAVE_BINDING_MISMATCH', 403);
+            if (op.receipt.revision !== revision)
+                throw Object.assign(new StudioError('SAVE_REVISION_CONFLICT', 409), { operation: op });
+            if (!['FAILED', 'RECOVERY_REQUIRED'].includes(op.receipt.state))
+                throw new StudioError('SAVE_RETRY_NOT_ALLOWED', 409);
+            if (closed || suspended.has(connectionId))
+                throw new StudioError('SAVE_BINDING_REQUIRED', 403);
+            if (!op.transfer?.completed) {
+                if (closed)
+                    throw new StudioError('STUDIO_STORAGE_CLOSED', 409);
+                const checked = await localRecovery(op);
+                if (!checked.receipt.safeRetry)
+                    throw new StudioError('SAVE_RETRY_NOT_ALLOWED', 409);
+                const claimed = await options.store.saveAuthority.update(id, connectionId, checked.receipt.revision, { state: 'SAVING', stage: 'RECONCILING', attempt: checked.receipt.attempt + 1, safeRetry: false, error: null });
+                worker.enqueue(id);
+                return claimed;
+            }
+            return localRecovery(op);
+        }),
+    };
+    workers.set(options.store, worker);
+    return worker;
+}
+function assetReceipt(asset) {
+    const { savedAt: _savedAt, ...rest } = asset;
+    return { ...rest, contentUrl: `/studio/api/assets/${asset.assetId}/content` };
+}
+//# sourceMappingURL=output-save-worker.js.map

package/dist/studio/paths.d.ts

@@ -0,0 +1,6 @@
+import type { StudioAsset, StudioRoot } from './types.js';
+export declare function prepareStudioRoot(outputDir: string): Promise<StudioRoot>;
+export declare function assertStudioRoot(root: StudioRoot): Promise<void>;
+export declare function assertRegularFile(file: string): Promise<void>;
+export declare function resolveStudioAssetPath(root: StudioRoot, asset: StudioAsset): Promise<string>;
+//# sourceMappingURL=paths.d.ts.map

package/dist/studio/paths.js

@@ -0,0 +1,68 @@
+import { lstat, mkdir, realpath } from 'node:fs/promises';
+import path from 'node:path';
+import { hasFsCode, storageError, StudioError } from './errors.js';
+import { mediaExtensions, validateStudioAssetId } from './media.js';
+async function directoryChain(absolute, create) {
+    const parsed = path.parse(absolute);
+    let current = parsed.root;
+    for (const segment of absolute.slice(parsed.root.length).split(path.sep).filter(Boolean)) {
+        current = path.join(current, segment);
+        if (create) {
+            try {
+                await mkdir(current);
+            }
+            catch (error) {
+                if (!hasFsCode(error, 'EEXIST'))
+                    throw error;
+            }
+        }
+        const info = await lstat(current);
+        if (!info.isDirectory() || info.isSymbolicLink())
+            throw new StudioError('STUDIO_PATH_UNSAFE', 409);
+    }
+}
+export async function prepareStudioRoot(outputDir) {
+    if (typeof outputDir !== 'string' || !path.isAbsolute(outputDir) || /[\u0000-\u001f]/.test(outputDir))
+        throw new StudioError('STUDIO_OUTPUT_ROOT_REQUIRED');
+    try {
+        const absolute = path.resolve(outputDir);
+        await directoryChain(absolute, true);
+        const canonicalOutputDir = await realpath(absolute);
+        const root = { canonicalOutputDir, managedDir: path.join(canonicalOutputDir, 'LumenKey'), assetsDir: path.join(canonicalOutputDir, 'LumenKey', 'assets') };
+        await directoryChain(root.assetsDir, true);
+        await assertStudioRoot(root);
+        return root;
+    }
+    catch (error) {
+        throw storageError(error);
+    }
+}
+export async function assertStudioRoot(root) {
+    try {
+        await directoryChain(root.assetsDir, false);
+        for (const p of [root.canonicalOutputDir, root.managedDir, root.assetsDir]) {
+            if (await realpath(p) !== p)
+                throw new StudioError('STUDIO_PATH_UNSAFE', 409);
+        }
+    }
+    catch (error) {
+        if (error instanceof StudioError)
+            throw error;
+        throw new StudioError('STUDIO_PATH_UNSAFE', 409);
+    }
+}
+export async function assertRegularFile(file) {
+    const info = await lstat(file);
+    if (!info.isFile() || info.isSymbolicLink() || info.nlink !== 1)
+        throw new StudioError('STUDIO_PATH_UNSAFE', 409);
+}
+export async function resolveStudioAssetPath(root, asset) {
+    await assertStudioRoot(root);
+    validateStudioAssetId(asset.assetId);
+    if (asset.relativePath !== `assets/${asset.assetId}.${mediaExtensions[asset.mediaType]}`)
+        throw new StudioError('STUDIO_PATH_UNSAFE', 409);
+    const file = path.join(root.managedDir, asset.relativePath);
+    await assertRegularFile(file);
+    return file;
+}
+//# sourceMappingURL=paths.js.map