@lumenkey/cli 0.3.1 → 0.4.0-rc.1

package/dist/studio/web/save-controller.js

@@ -0,0 +1,495 @@
+import { uiError } from './controller.js';
+import { parseReceipt, mergeReceipt, pollDelay, backoffDelay, pendingDelay, isSaving, invalidSaveResponse } from './save-model.js';
+import { createSaveQueue } from './save-queue.js';
+const id = (v) => typeof v === 'string' && /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i.test(v);
+const record = (v) => !!v && typeof v === 'object' && !Array.isArray(v);
+const integer = (v) => typeof v === 'number' && Number.isSafeInteger(v) && v >= 0;
+function sameSnapshot(a, b) {
+    if (a === b)
+        return true;
+    if (Array.isArray(a) && Array.isArray(b))
+        return a.length === b.length && a.every((v, i) => sameSnapshot(v, b[i]));
+    return record(a) && record(b) && Object.keys(a).length === Object.keys(b).length && Object.keys(a).every(key => Object.hasOwn(b, key) && sameSnapshot(a[key], b[key]));
+}
+const reasons = ['LEGACY_AWAITING_FRESH_GET', 'JOB_UNAVAILABLE', 'NO_VERIFIABLE_OUTPUTS', 'IDENTITY_CONFLICT'];
+const blockers = ['SAVE_OUTPUT_ROOT_REQUIRED', 'SAVE_ROOT_NOT_ALLOWED', 'SAVE_OUTPUT_IDENTITY_UNVERIFIED', 'SAVE_OUTPUT_IDENTITY_CONFLICT', 'SAVE_JOB_NOT_TERMINAL', 'SAVE_MEDIA_UNSUPPORTED', 'SAVE_SOURCE_UNAVAILABLE', 'SAVE_OPERATION_EXISTS'];
+function invalid() { throw Object.assign(new Error('本机回复不符合页面契约。'), { code: 'STUDIO_RESPONSE_INVALID' }); }
+function isScope(value) { return record(value) && (value.rootId === null || id(value.rootId)) && id(value.connectionId); }
+export function parseBinding(value) {
+    if (!record(value) || !isScope(value.scope))
+        return invalid();
+    if (value.root === null && value.scope.rootId === null && value.code === 'SAVE_OUTPUT_ROOT_REQUIRED')
+        return value;
+    if (record(value.root) && typeof value.root.absolutePath === 'string' && value.root.absolutePath.length > 0 && id(value.scope.rootId) && value.code === null)
+        return value;
+    return invalid();
+}
+export function parseOutputs(value, scope, runId) {
+    if (!record(value) || !isScope(value.scope) || value.scope.rootId !== scope.rootId || value.scope.connectionId !== scope.connectionId || !integer(value.revision) || !Array.isArray(value.items))
+        return invalid();
+    for (const item of value.items) {
+        if (!record(item) || item.runId !== runId || !id(item.jobId) || !integer(item.displayOrdinal) || item.displayOrdinal < 1 ||
+            !(item.outputIndex === null || integer(item.outputIndex)) || !(item.localOutputId === null || id(item.localOutputId)) || !(item.gatewayAssetId === null || id(item.gatewayAssetId)) ||
+            ![null, 'image', 'video', 'audio'].includes(item.outputType) || !(item.mediaType === null || typeof item.mediaType === 'string') || !record(item.identity) ||
+            !(item.identity.status === 'VERIFIED' && item.identity.reason === null && id(item.localOutputId) && id(item.gatewayAssetId) || item.identity.status === 'UNVERIFIED' && reasons.includes(item.identity.reason) && item.localOutputId === null && item.gatewayAssetId === null) ||
+            !['ACCEPTED', 'NEVER_ACCEPTED', 'UNKNOWN'].includes(item.acceptance) || typeof item.saveAllowed !== 'boolean' ||
+            !(item.saveAllowed ? item.saveBlockedCode === null : blockers.includes(item.saveBlockedCode)))
+            return invalid();
+        if (item.save === null) {
+            if (item.saveOperationId !== null || item.acceptance === 'ACCEPTED')
+                return invalid();
+        }
+        else {
+            const save = parseReceipt(item.save);
+            if (item.saveOperationId !== save.operationId || item.acceptance !== 'ACCEPTED' || item.saveAllowed || save.runId !== runId || save.jobId !== item.jobId || item.localOutputId !== null && save.localOutputId !== item.localOutputId || item.gatewayAssetId !== null && save.gatewayAssetId !== item.gatewayAssetId)
+                return invalid();
+        }
+    }
+    return value;
+}
+export function createSaveController(options) {
+    const state = { binding: { status: 'idle' }, outputs: {}, operations: {}, targets: {} };
+    const clock = options.clock ?? { now: Date.now, setTimeout: (fn, ms) => setTimeout(fn, ms), clearTimeout: (handle) => clearTimeout(handle) };
+    const uuid = options.uuid ?? (() => crypto.randomUUID()), queue = options.queue ?? createSaveQueue();
+    let follows = new Map(), visible = new Set(), lazy = new Set(), pageVisible = true, timer;
+    const mutations = new Map();
+    const skipped = Symbol('paused'), expiredRead = Symbol('pending-expired'), cappedRead = Symbol('follow-limit');
+    let epoch = 0, binding;
+    let reads = new Map();
+    const emit = () => options.onChange?.();
+    const call = (key, priority, task) => queue.run(`save:${epoch}:${key}`, priority, task);
+    function stopTimer() { if (timer !== undefined)
+        clock.clearTimeout(timer); timer = undefined; }
+    function invalidate() { epoch++; queue.reset('save:'); stopTimer(); follows = new Map(); visible = new Set(); lazy = new Set(); binding = undefined; reads = new Map(); mutations.clear(); state.binding = { status: 'idle' }; state.outputs = {}; state.operations = {}; state.targets = {}; emit(); }
+    function bind() {
+        if (binding)
+            return binding;
+        invalidate();
+        const started = epoch;
+        state.binding = { status: 'loading' };
+        emit();
+        const pending = (async () => {
+            try {
+                const value = parseBinding(await call('bind', 1, () => options.api('saves/bind', {})));
+                if (started === epoch)
+                    state.binding = { status: 'ready', value };
+            }
+            catch (error) {
+                if (started === epoch)
+                    state.binding = { status: 'error', error: uiError(error) };
+            }
+            finally {
+                if (started === epoch) {
+                    binding = undefined;
+                    emit();
+                }
+            }
+        })();
+        binding = pending;
+        return pending;
+    }
+    function readOutputs(runId, retry = true) {
+        if (state.binding.status === 'idle' || state.binding.status === 'loading') {
+            const waiting = binding ?? bind(), waitingEpoch = epoch;
+            return waiting.then(() => waitingEpoch === epoch ? readOutputs(runId, retry) : undefined);
+        }
+        const shared = reads.get(runId);
+        if (shared)
+            return shared;
+        const registry = reads;
+        const pending = (async () => {
+            const started = epoch, bound = state.binding.value;
+            if (state.binding.status !== 'ready' || !bound?.root) {
+                state.outputs[runId] = { status: 'error', error: state.binding.error ?? uiError({ code: 'SAVE_OUTPUT_ROOT_REQUIRED', message: '尚未设置可用保存目录。' }) };
+                emit();
+                return;
+            }
+            const previous = state.outputs[runId]?.value;
+            state.outputs[runId] = { status: 'loading', ...(previous ? { value: previous } : {}) };
+            emit();
+            try {
+                const value = parseOutputs(await call(`list:${runId}`, 1, () => options.api(`runs/${runId}/outputs`)), bound.scope, runId);
+                if (started === epoch) {
+                    state.outputs[runId] = { status: 'ready', value };
+                    for (const output of value.items)
+                        if (output.save)
+                            rememberReceipt(output.save);
+                }
+            }
+            catch (error) {
+                if (started !== epoch)
+                    return;
+                if (retry && uiError(error).code === 'SAVE_BINDING_REQUIRED') {
+                    const recovery = bind(), recoveryEpoch = epoch;
+                    await recovery;
+                    if (recoveryEpoch === epoch)
+                        await readOutputs(runId, false);
+                    return;
+                }
+                // A refused authority read must not keep displaying old saveAllowed or
+                // NEVER_ACCEPTED facts as if they belonged to the current connection.
+                state.outputs[runId] = { status: 'error', error: uiError(error) };
+            }
+            finally {
+                if (started === epoch)
+                    emit();
+            }
+        })().finally(() => { if (registry.get(runId) === pending)
+            registry.delete(runId); });
+        registry.set(runId, pending);
+        return pending;
+    }
+    function context(id) { let value = follows.get(id); if (!value) {
+        value = { follows: 0, failures: 0 };
+        follows.set(id, value);
+    } return value; }
+    function rememberReceipt(next) {
+        const incoming = parseReceipt(next), before = state.operations[incoming.operationId]?.value;
+        if (before && incoming.revision < before.revision)
+            return before;
+        const save = mergeReceipt(before, incoming);
+        state.operations[save.operationId] = { status: 'ready', value: save };
+        state.targets[save.localOutputId] = { status: 'known', operationId: save.operationId };
+        const follow = context(save.operationId);
+        if (isSaving(save)) {
+            if (!before || !isSaving(before))
+                follow.activeSince = clock.now();
+            follow.next ??= clock.now() + pollDelay(clock.now() - (follow.activeSince ?? clock.now()));
+        }
+        else {
+            follow.activeSince = undefined;
+            if (save.integrityCheck === 'IDLE')
+                follow.next = undefined;
+        }
+        arm();
+        emit();
+        return save;
+    }
+    function scopeResponse(value) {
+        const bound = state.binding.value;
+        if (!record(value) || !bound || !isScope(value.scope) || value.scope.rootId !== bound.scope.rootId || value.scope.connectionId !== bound.scope.connectionId || !integer(value.revision))
+            return invalidSaveResponse();
+    }
+    function receiptResponse(value, id) {
+        scopeResponse(value);
+        const save = parseReceipt(value.save);
+        if (id && save.operationId !== id)
+            return invalidSaveResponse();
+        return save;
+    }
+    function transient(error) {
+        const status = error?.status ?? uiError(error).httpStatus;
+        return status === 503 || status === undefined && (!(error?.code) || uiError(error).code === 'STUDIO_REQUEST_FAILED');
+    }
+    const cancelled = Symbol('old-epoch');
+    async function readBound(route, key, priority, adoptEpoch) {
+        const started = epoch;
+        try {
+            return await call(key, priority, () => options.api(route));
+        }
+        catch (error) {
+            if (started !== epoch)
+                return cancelled;
+            if (uiError(error).code !== 'SAVE_BINDING_REQUIRED')
+                throw error;
+            const recovery = bind(), recovering = epoch;
+            await recovery;
+            if (recovering !== epoch)
+                return cancelled;
+            adoptEpoch(recovering);
+            if (state.binding.status !== 'ready')
+                throw state.binding.error;
+            // This is a GET only. A second REQUIRED/MISMATCH is returned, never looped.
+            return call(key, priority, () => options.api(route));
+        }
+    }
+    function expirePending(id, follow) {
+        if (follow.pendingSince !== undefined && clock.now() >= follow.pendingSince + 120_000) {
+            follow.next = undefined;
+            if (state.operations[id])
+                state.operations[id].notice = follow.failures ? '暂不可核对 · 核对保存状态' : '核验尚未完成 · 核对保存状态';
+            queue.cancel(`save:${epoch}:operation:${id}`, expiredRead);
+            return true;
+        }
+        return false;
+    }
+    function arm() {
+        stopTimer();
+        if (!pageVisible)
+            return;
+        const deadlines = [];
+        for (const [id, follow] of follows) {
+            if (expirePending(id, follow))
+                continue;
+            if (follow.busy) {
+                if (follow.pendingSince !== undefined)
+                    deadlines.push(follow.pendingSince + 120_000);
+                continue;
+            }
+            if (follow.next !== undefined)
+                deadlines.push(follow.pendingSince === undefined ? follow.next : Math.min(follow.next, follow.pendingSince + 120_000));
+        }
+        if (deadlines.length)
+            timer = clock.setTimeout(tick, Math.max(0, Math.min(...deadlines) - clock.now()));
+    }
+    function tick() {
+        timer = undefined;
+        if (!pageVisible)
+            return;
+        for (const [id, follow] of follows) {
+            if (expirePending(id, follow) || follow.busy)
+                continue;
+            if (follow.next !== undefined && follow.next <= clock.now())
+                void readOperation(id, { automatic: true });
+        }
+        arm();
+        emit();
+    }
+    function readOperation(id, readOptions = {}) {
+        let follow = context(id);
+        if (follow.busy)
+            return follow.busy;
+        const current = state.operations[id]?.value;
+        if (!current || state.binding.status !== 'ready')
+            return Promise.resolve();
+        let started = epoch;
+        const originalNext = follow.next;
+        follow.next = undefined;
+        if (readOptions.manual) {
+            follow.pendingSince = undefined;
+            follow.follows = 0;
+            follow.failures = 0;
+        }
+        const previousObservation = state.operations[id];
+        const loadingObservation = { ...previousObservation, status: 'loading' };
+        state.operations[id] = loadingObservation;
+        emit();
+        function acceptRead(incoming) {
+            const held = state.operations[id]?.value;
+            if (held && incoming.revision < held.revision) {
+                if (state.operations[id] === loadingObservation)
+                    state.operations[id] = previousObservation;
+                follow.next ??= originalNext;
+                return;
+            }
+            const save = rememberReceipt(incoming);
+            follow.failures = 0;
+            if (isSaving(save))
+                follow.next = clock.now() + pollDelay(clock.now() - (follow.activeSince ?? clock.now()));
+            else if (save.state === 'SAVED' && save.integrityCheck === 'PENDING') {
+                follow.pendingSince ??= clock.now();
+                if (!expirePending(id, follow))
+                    follow.next = follow.follows < 13 ? clock.now() + pendingDelay(follow.follows) : follow.pendingSince + 120_000;
+            }
+            else {
+                follow.next = undefined;
+                follow.pendingSince = undefined;
+            }
+        }
+        const pending = (async () => {
+            try {
+                const value = await call(`operation:${id}`, isSaving(current) ? 0 : readOptions.manual ? 1 : 2, async () => {
+                    if (started !== epoch || !pageVisible || readOptions.lazy && !visible.has(id))
+                        return skipped;
+                    if (expirePending(id, follow))
+                        return expiredRead;
+                    if (readOptions.automatic && follow.pendingSince !== undefined && follow.follows >= 13 && !isSaving(current))
+                        return cappedRead;
+                    if (readOptions.lazy)
+                        lazy.add(id);
+                    if (readOptions.automatic && follow.pendingSince !== undefined && !isSaving(current))
+                        follow.follows++;
+                    return options.api(`saves/${id}`);
+                });
+                if (started !== epoch)
+                    return;
+                if (value === skipped || value === expiredRead || value === cappedRead) {
+                    if (value === skipped)
+                        follow.next = originalNext;
+                    if (value === cappedRead)
+                        follow.next = follow.pendingSince + 120_000;
+                    if (state.operations[id] === loadingObservation)
+                        state.operations[id] = { ...previousObservation, ...(state.operations[id].notice ? { notice: state.operations[id].notice } : {}) };
+                    return;
+                }
+                acceptRead(receiptResponse(value, id));
+            }
+            catch (error) {
+                if (started !== epoch)
+                    return;
+                if (uiError(error).code === 'SAVE_BINDING_REQUIRED') {
+                    try {
+                        const recovery = bind(), recovering = epoch;
+                        await recovery;
+                        if (recovering !== epoch)
+                            return;
+                        started = recovering;
+                        follow = context(id);
+                        if (state.binding.status !== 'ready')
+                            throw state.binding.error;
+                        const save = receiptResponse(await call(`operation:${id}`, 1, () => options.api(`saves/${id}`)), id);
+                        if (started === epoch) {
+                            acceptRead(save);
+                            // Rebinding removed old-scope rows. Re-read the authorized list so
+                            // the recovered receipt remains reachable in the actual page.
+                            await readOutputs(save.runId, false);
+                        }
+                    }
+                    catch (retryError) {
+                        if (started === epoch)
+                            state.operations[id] = { status: 'error', error: uiError(retryError), notice: '保存结果尚未确认 · 核对保存状态' };
+                    }
+                    return;
+                }
+                state.operations[id] = { ...state.operations[id], status: 'error', error: uiError(error), notice: '保存结果尚未确认 · 核对保存状态' };
+                if (transient(error) && (isSaving(current) || follow.pendingSince !== undefined) && !expirePending(id, follow))
+                    follow.next = clock.now() + backoffDelay(follow.failures++);
+                else
+                    follow.next = undefined;
+            }
+            finally {
+                if (started === epoch) {
+                    follow.busy = undefined;
+                    arm();
+                    emit();
+                }
+            }
+        })();
+        follow.busy = pending;
+        return pending;
+    }
+    function markVisible(id, onScreen) {
+        if (onScreen)
+            visible.add(id);
+        else
+            visible.delete(id);
+        if (pageVisible && onScreen && !lazy.has(id) && state.operations[id]?.value?.state === 'SAVED')
+            void readOperation(id, { lazy: true });
+    }
+    function setPageVisible(value) {
+        pageVisible = value;
+        if (value)
+            for (const id of visible)
+                if (!lazy.has(id) && state.operations[id]?.value?.state === 'SAVED')
+                    void readOperation(id, { lazy: true });
+        arm();
+        emit();
+    }
+    function checkOutput(runId, outputId) {
+        const key = `${epoch}:check:${outputId}`, shared = mutations.get(key);
+        if (shared)
+            return shared;
+        let started = epoch;
+        state.targets[outputId] = { ...state.targets[outputId] ?? { status: 'unknown' }, checking: true };
+        emit();
+        const pending = (async () => {
+            try {
+                const value = await readBound(`runs/${runId}/outputs/${outputId}/save`, state.targets[outputId]?.operationId ? `operation:${state.targets[outputId].operationId}` : key, 1, value => { started = value; });
+                if (value === cancelled || started !== epoch)
+                    return;
+                scopeResponse(value);
+                const parsed = parseOutputs({ scope: value.scope, revision: value.revision, items: [value.output] }, value.scope, runId).items[0];
+                if ((parsed.localOutputId ?? parsed.save?.localOutputId) !== outputId)
+                    return invalidSaveResponse();
+                if (value.acceptance !== parsed.acceptance || (value.save === null) !== (parsed.save === null))
+                    return invalidSaveResponse();
+                if (parsed.save) {
+                    const save = parseReceipt(value.save);
+                    if (!sameSnapshot(save, parsed.save))
+                        return invalidSaveResponse();
+                    rememberReceipt(save);
+                }
+                else if (parsed.acceptance === 'NEVER_ACCEPTED' && parsed.saveAllowed)
+                    state.targets[outputId] = { status: 'idle' };
+                else
+                    state.targets[outputId] = { status: 'unknown' };
+                const list = state.outputs[runId]?.value;
+                if (list)
+                    list.items = list.items.map(item => (item.localOutputId ?? item.save?.localOutputId) === outputId ? parsed : item);
+            }
+            catch (error) {
+                if (started === epoch)
+                    state.targets[outputId] = { status: 'unknown', error: uiError(error) };
+            }
+            finally {
+                mutations.delete(key);
+                if (started === epoch) {
+                    if (state.targets[outputId])
+                        state.targets[outputId].checking = false;
+                    emit();
+                }
+            }
+        })();
+        mutations.set(key, pending);
+        return pending;
+    }
+    function saveOutput(runId, outputId) {
+        const key = `${epoch}:save:${outputId}`, shared = mutations.get(key);
+        if (shared)
+            return shared;
+        const output = state.outputs[runId]?.value?.items.find(o => o.localOutputId === outputId), target = state.targets[outputId];
+        if (state.binding.status !== 'ready' || !output || output.acceptance !== 'NEVER_ACCEPTED' || !output.saveAllowed || target && target.status !== 'idle')
+            return Promise.resolve();
+        const started = epoch;
+        state.targets[outputId] = { status: 'submitting' };
+        emit();
+        const pending = (async () => {
+            try {
+                const value = await call(key, 1, () => options.api(`runs/${runId}/outputs/${outputId}/save`, { requestId: uuid() }));
+                if (started !== epoch)
+                    return;
+                const save = receiptResponse(value);
+                if (save.localOutputId !== outputId || save.runId !== runId)
+                    return invalidSaveResponse();
+                rememberReceipt(save);
+            }
+            catch (error) {
+                if (started !== epoch)
+                    return;
+                state.targets[outputId] = { status: 'unknown', error: uiError(error) };
+                emit();
+                await checkOutput(runId, outputId);
+            }
+            finally {
+                mutations.delete(key);
+                if (started === epoch)
+                    emit();
+            }
+        })();
+        mutations.set(key, pending);
+        return pending;
+    }
+    function retryOperation(id) {
+        const key = `${epoch}:retry:${id}`, shared = mutations.get(key);
+        if (shared)
+            return shared;
+        const save = state.operations[id]?.value;
+        if (!save?.safeRetry || !['FAILED', 'RECOVERY_REQUIRED'].includes(save.state) || state.operations[id]?.status !== 'ready' || context(id).busy)
+            return Promise.resolve();
+        const started = epoch;
+        state.operations[id] = { ...state.operations[id], status: 'loading' };
+        emit();
+        const pending = (async () => {
+            try {
+                const value = await call(`operation:${id}`, 1, () => options.api(`saves/${id}/retry`, { expectedRevision: save.revision }));
+                if (started === epoch)
+                    rememberReceipt(receiptResponse(value, id));
+            }
+            catch (error) {
+                if (started === epoch) {
+                    state.operations[id] = { ...state.operations[id], status: 'error', error: uiError(error), notice: '保存结果尚未确认 · 核对保存状态' };
+                    await readOperation(id, { manual: true });
+                }
+            }
+            finally {
+                mutations.delete(key);
+                if (started === epoch)
+                    emit();
+            }
+        })();
+        mutations.set(key, pending);
+        return pending;
+    }
+    return { state, invalidate, bind, readOutputs, rememberReceipt, readOperation, checkOutput, saveOutput, retryOperation, markVisible, setPageVisible, dispose: invalidate };
+}
+//# sourceMappingURL=save-controller.js.map

package/dist/studio/web/save-model.d.ts

@@ -0,0 +1,63 @@
+export type SaveStage = 'QUEUED' | 'DOWNLOADING' | 'FILE_READY' | 'REGISTERED' | 'LINKED' | 'RECONCILING';
+export interface SaveReceipt {
+    operationId: string;
+    revision: number;
+    localOutputId: string;
+    runId: string;
+    jobId: string;
+    gatewayAssetId: string;
+    state: 'ACCEPTED' | 'SAVING' | 'SAVED' | 'FAILED' | 'RECOVERY_REQUIRED' | 'BLOCKED';
+    stage: SaveStage;
+    attempt: number;
+    facts: {
+        file: 'NOT_CHECKED' | 'ABSENT' | 'PARTIAL' | 'VERIFIED' | 'MISSING' | 'MODIFIED' | 'UNSAFE' | 'UNKNOWN';
+        registration: 'ABSENT' | 'PRESENT' | 'UNKNOWN';
+        relation: 'ABSENT' | 'PRESENT' | 'UNKNOWN';
+    };
+    asset: {
+        assetId: string;
+        displayName: string;
+        mediaType: string;
+        byteLength: number;
+        sha256: string;
+        relativePath: string;
+        absolutePath: string;
+        contentUrl: string;
+    } | null;
+    progress: {
+        receivedBytes: number;
+        totalBytes: number | null;
+    } | null;
+    error: {
+        code: string;
+        message: string;
+        type: string;
+        httpStatus?: number;
+        retryable: boolean;
+        mayAlreadyBeSaved: boolean | null;
+    } | null;
+    retryable: boolean;
+    safeRetry: boolean;
+    mayAlreadyBeSaved: boolean | null;
+    checkedAt: string | null;
+    integrityCheck: 'IDLE' | 'PENDING';
+    createdAt: string;
+    updatedAt: string;
+}
+export declare const isRecord: (v: unknown) => v is Record<string, unknown>;
+export declare const isId: (v: unknown) => v is string;
+export declare function invalidSaveResponse(): never;
+export declare function parseReceipt(v: unknown): SaveReceipt;
+export declare function mergeReceipt(before: SaveReceipt | undefined, next: SaveReceipt): SaveReceipt;
+export declare const pollDelay: (elapsed: number) => 1000 | 5000 | 2000;
+export declare const backoffDelay: (failures: number) => number;
+export declare const pendingDelay: (read: number) => 5000 | 10000 | 2000;
+export declare const isSaving: (save: SaveReceipt) => boolean;
+export declare function receiptPresentation(save: SaveReceipt, observationFailed?: boolean): {
+    status: string;
+    progress: string;
+    canRetry: boolean;
+    error: string;
+    stage: "排队中" | "接收文件" | "文件已写入" | "素材已登记" | "记录已关联" | "核对原保存记录";
+};
+//# sourceMappingURL=save-model.d.ts.map

package/dist/studio/web/save-model.js

@@ -0,0 +1,64 @@
+import { messageForCode } from './messages.js';
+export const isRecord = (v) => !!v && typeof v === 'object' && !Array.isArray(v);
+export const isId = (v) => typeof v === 'string' && /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i.test(v);
+const integer = (v) => typeof v === 'number' && Number.isSafeInteger(v) && v >= 0;
+const string = (v) => typeof v === 'string' && v.length > 0;
+const date = (v) => string(v) && Number.isFinite(Date.parse(v));
+const nullableBoolean = (v) => v === null || typeof v === 'boolean';
+export function invalidSaveResponse() { throw Object.assign(new Error('保存回复不符合页面契约。'), { code: 'STUDIO_RESPONSE_INVALID' }); }
+export function parseReceipt(v) {
+    if (!isRecord(v) || !['operationId', 'localOutputId', 'runId', 'jobId', 'gatewayAssetId'].every(k => isId(v[k])) || !integer(v.revision) || v.revision < 1 || !integer(v.attempt) ||
+        !['ACCEPTED', 'SAVING', 'SAVED', 'FAILED', 'RECOVERY_REQUIRED', 'BLOCKED'].includes(v.state) || !['QUEUED', 'DOWNLOADING', 'FILE_READY', 'REGISTERED', 'LINKED', 'RECONCILING'].includes(v.stage) ||
+        !isRecord(v.facts) || !['NOT_CHECKED', 'ABSENT', 'PARTIAL', 'VERIFIED', 'MISSING', 'MODIFIED', 'UNSAFE', 'UNKNOWN'].includes(v.facts.file) || !['ABSENT', 'PRESENT', 'UNKNOWN'].includes(v.facts.registration) || !['ABSENT', 'PRESENT', 'UNKNOWN'].includes(v.facts.relation) ||
+        typeof v.retryable !== 'boolean' || typeof v.safeRetry !== 'boolean' || !nullableBoolean(v.mayAlreadyBeSaved) || !(v.checkedAt === null || date(v.checkedAt)) || !['IDLE', 'PENDING'].includes(v.integrityCheck) || !date(v.createdAt) || !date(v.updatedAt))
+        return invalidSaveResponse();
+    if (v.progress !== null && (!isRecord(v.progress) || !integer(v.progress.receivedBytes) || !(v.progress.totalBytes === null || integer(v.progress.totalBytes) && v.progress.totalBytes > 0)))
+        return invalidSaveResponse();
+    if (v.error !== null && (!isRecord(v.error) || !string(v.error.code) || typeof v.error.message !== 'string' || !string(v.error.type) || typeof v.error.retryable !== 'boolean' || !nullableBoolean(v.error.mayAlreadyBeSaved) || v.error.httpStatus !== undefined && (!integer(v.error.httpStatus) || v.error.httpStatus < 400 || v.error.httpStatus > 599)))
+        return invalidSaveResponse();
+    if (v.asset !== null && (!isRecord(v.asset) || !isId(v.asset.assetId) || !['displayName', 'relativePath', 'absolutePath', 'contentUrl'].every(k => string(v.asset[k])) || !['image/png', 'image/jpeg', 'image/webp', 'video/mp4', 'video/webm'].includes(v.asset.mediaType) || !integer(v.asset.byteLength) || v.asset.byteLength < 1 || typeof v.asset.sha256 !== 'string' || !/^[a-f0-9]{64}$/.test(v.asset.sha256)))
+        return invalidSaveResponse();
+    return v;
+}
+export function mergeReceipt(before, next) {
+    if (!before)
+        return next;
+    for (const key of ['operationId', 'localOutputId', 'runId', 'jobId', 'gatewayAssetId', 'createdAt'])
+        if (before[key] !== next[key])
+            return invalidSaveResponse();
+    if (next.revision < before.revision)
+        return before;
+    if (next.revision > before.revision)
+        return next;
+    if (next.attempt !== before.attempt || next.state !== before.state || next.stage !== before.stage)
+        return invalidSaveResponse();
+    const progress = next.progress && before.progress ? { receivedBytes: Math.max(next.progress.receivedBytes, before.progress.receivedBytes), totalBytes: next.progress.totalBytes ?? before.progress.totalBytes } : next.progress ?? before.progress;
+    return { ...next, progress };
+}
+export const pollDelay = (elapsed) => elapsed < 10_000 ? 1000 : elapsed < 60_000 ? 2000 : 5000;
+export const backoffDelay = (failures) => [2000, 4000, 8000, 16000, 30000][Math.min(failures, 4)];
+export const pendingDelay = (read) => read === 0 ? 2000 : read === 1 ? 5000 : 10000;
+export const isSaving = (save) => save.state === 'ACCEPTED' || save.state === 'SAVING';
+export function receiptPresentation(save, observationFailed = false) {
+    let status;
+    if (isSaving(save))
+        status = ['FILE_READY', 'REGISTERED'].includes(save.stage) ? '文件已写入，正在核对记录' : save.state === 'ACCEPTED' ? '等待保存到本机' : '正在保存到本机';
+    else if (save.state === 'SAVED') {
+        if (['MISSING', 'MODIFIED', 'UNSAFE'].includes(save.facts.file))
+            status = '曾保存，文件现已' + { MISSING: '缺失', MODIFIED: '变更', UNSAFE: '不安全' }[save.facts.file];
+        else if (save.integrityCheck === 'PENDING')
+            status = '曾保存，正在检查';
+        else if (save.facts.file === 'VERIFIED' && save.facts.registration === 'PRESENT' && save.facts.relation === 'PRESENT' && save.checkedAt)
+            status = '已保存到本机（当前已核验）';
+        else
+            status = save.facts.file === 'NOT_CHECKED' ? '已保存 · 尚未核验' : '曾保存，当前状态未确认';
+    }
+    else
+        status = save.state === 'FAILED' ? '未保存成功' : save.state === 'BLOCKED' ? '需要人工处理' : '文件保存需要恢复';
+    if (observationFailed)
+        status = save.state === 'SAVED' ? '曾保存，当前状态未确认' : '保存结果尚未确认';
+    const progress = !isSaving(save) ? '' : save.progress === null ? '正在保存，进度暂不可用' : save.progress.totalBytes === null ? `已接收 ${save.progress.receivedBytes.toLocaleString()} 字节` : `已接收 ${save.progress.receivedBytes.toLocaleString()} / ${save.progress.totalBytes.toLocaleString()} 字节`;
+    const interrupted = !save.error && ['FAILED', 'RECOVERY_REQUIRED'].includes(save.state) ? '保存中断' + (save.safeRetry ? '，可重试原保存' : '，请核对原保存记录') : '';
+    return { status, progress, canRetry: save.safeRetry && ['FAILED', 'RECOVERY_REQUIRED'].includes(save.state), error: save.error ? messageForCode(save.error.code, save.error.message) + ` (${save.error.code})` : interrupted, stage: { QUEUED: '排队中', DOWNLOADING: '接收文件', FILE_READY: '文件已写入', REGISTERED: '素材已登记', LINKED: '记录已关联', RECONCILING: '核对原保存记录' }[save.stage] };
+}
+//# sourceMappingURL=save-model.js.map

package/dist/studio/web/save-queue.d.ts

@@ -0,0 +1,7 @@
+export declare function createSaveQueue(): {
+    has: (key: string) => boolean;
+    cancel(key: string, value: unknown): void;
+    run<T>(key: string, priority: number, task: () => Promise<T>): Promise<T>;
+    reset(prefix?: string): void;
+};
+//# sourceMappingURL=save-queue.d.ts.map