@lumenkey/cli 0.3.1 → 0.4.0-rc.1

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

@@ -0,0 +1,287 @@
+import { randomUUID } from 'node:crypto';
+import { link, lstat, open, readdir, rename, unlink } from 'node:fs/promises';
+import path from 'node:path';
+import { z } from 'zod';
+import { assertRegularFile, assertStudioRoot } from './paths.js';
+import { prepareDocumentAuthority } from './document-authority.js';
+import { hasFsCode, StudioError } from './errors.js';
+import { saveOperation, legacySaveOperation, saveAcceptInput, saveMutable, integrityFact } from './output-save-contract.js';
+import { isVerifiedHashResult } from './asset-integrity-hash.js';
+import { uuid, isoDate } from './run-journal.js';
+const digest = z.string().regex(/^[a-f0-9]{64}$/);
+const observationValue = z.object({ file: integrityFact, checkedAt: isoDate.nullable(), integrityCheck: z.enum(['IDLE', 'PENDING']), signature: z.string().min(1).max(500).optional(), errorCode: z.enum(['SAVE_FILE_MISSING', 'SAVE_FILE_MODIFIED', 'SAVE_FILE_UNSAFE', 'SAVE_FILE_READ_FAILED']).optional() }).strict().refine(v => (v.integrityCheck !== 'PENDING' || (v.file === 'NOT_CHECKED' && !v.signature && !v.errorCode)) && (v.file !== 'VERIFIED' || (v.checkedAt !== null && v.integrityCheck === 'IDLE' && !!v.signature && !v.errorCode)));
+const observation = z.object({ assetId: uuid, revision: z.number().int().positive().safe(), value: observationValue }).transform(v => ({ assetId: v.assetId, revision: v.revision, ...v.value }));
+const persistedObservation = z.object({ assetId: uuid, revision: z.number().int().positive().safe() }).merge(observationValue.innerType()).strict().refine(v => {
+    const { assetId: _id, revision: _rev, ...value } = v;
+    return observationValue.safeParse(value).success;
+});
+const schema = z.object({ schemaVersion: z.literal(2), revision: z.number().int().nonnegative().safe(), rootId: z.string().uuid(),
+    canonicalAssetsPath: z.string().min(1),
+    connections: z.array(z.object({ connectionId: z.string().uuid(), bindingDigestRef: digest }).strict()).max(10000),
+    operations: z.array(saveOperation).max(10000),
+    integrityObservations: z.array(persistedObservation).max(100000),
+}).strict().refine(v => {
+    const observations = new Map(v.integrityObservations.map(o => [o.assetId, o]));
+    return new Set(v.connections.map(c => c.connectionId)).size === v.connections.length && new Set(v.connections.map(c => c.bindingDigestRef)).size === v.connections.length &&
+        new Set(v.integrityObservations.map(o => o.assetId)).size === v.integrityObservations.length &&
+        new Set(v.operations.map(o => o.receipt.operationId)).size === v.operations.length && new Set(v.operations.map(o => o.assetId)).size === v.operations.length &&
+        new Set(v.operations.map(o => `${o.connectionId}:${o.receipt.localOutputId}`)).size === v.operations.length &&
+        new Set(v.operations.flatMap(o => o.requestIds)).size === v.operations.reduce((n, o) => n + o.requestIds.length, 0) &&
+        v.operations.every(o => v.connections.some(c => c.connectionId === o.connectionId)) &&
+        v.operations.every(o => {
+            const r = o.receipt, observed = observations.get(o.assetId);
+            if (r.asset && observed)
+                return r.facts.file === observed.file && r.checkedAt === observed.checkedAt && r.integrityCheck === observed.integrityCheck;
+            return r.checkedAt === null && r.integrityCheck === 'IDLE' && !['VERIFIED', 'MODIFIED'].includes(r.facts.file);
+        });
+});
+const legacySchema = schema.innerType().omit({ integrityObservations: true }).extend({ schemaVersion: z.literal(1), operations: z.array(legacySaveOperation).max(10000) }).strict();
+const LIMIT = 16 * 1024 * 1024;
+/** Internal control flow, never a business failure or a new public error code. */
+export class SaveIntegrityPending extends StudioError {
+    constructor() { super('SAVE_RETRY_NOT_ALLOWED', 409); }
+}
+/** Private authority; the asset-store owns the sole writer and shared lifecycle queue. */
+export function createSaveAuthority(root, serial, hooks = {}) {
+    const file = path.join(root.managedDir, 'output-saves.json');
+    let current;
+    let coldReady = false;
+    let legacy = false;
+    async function disk() {
+        await assertStudioRoot(root);
+        try {
+            await assertRegularFile(file);
+            const handle = await open(file, 'r');
+            try {
+                if ((await handle.stat()).size > LIMIT)
+                    throw new Error();
+                const raw = JSON.parse(await handle.readFile('utf8'));
+                const old = z.object({ schemaVersion: z.literal(1) }).passthrough().safeParse(raw);
+                const value = schema.parse(old.success ? { ...legacySchema.parse(raw), schemaVersion: 2, integrityObservations: [] } : raw);
+                legacy = old.success || JSON.stringify(raw) !== JSON.stringify(value);
+                if (value.canonicalAssetsPath !== root.assetsDir)
+                    throw new Error();
+                return value;
+            }
+            finally {
+                await handle.close();
+            }
+        }
+        catch (error) {
+            if (hasFsCode(error, 'ENOENT'))
+                return undefined;
+            throw new StudioError('SAVE_AUTHORITY_INVALID', 409);
+        }
+    }
+    async function commit(next, initial = false) {
+        const canonical = schema.parse(next);
+        const text = JSON.stringify(canonical);
+        if (Buffer.byteLength(text) > LIMIT)
+            throw new StudioError('SAVE_AUTHORITY_INVALID', 409);
+        await assertStudioRoot(root);
+        const temp = path.join(root.managedDir, `output-saves.${randomUUID()}.tmp`);
+        try {
+            const h = await open(temp, 'wx', 0o600);
+            try {
+                await h.writeFile(text);
+                await h.sync();
+            }
+            finally {
+                await h.close();
+            }
+            await hooks.beforeCommit?.();
+            await assertStudioRoot(root);
+            if (initial) {
+                await link(temp, file);
+                await unlink(temp);
+            }
+            else {
+                await assertRegularFile(file);
+                await rename(temp, file);
+            }
+        }
+        catch {
+            try {
+                await unlink(temp);
+            }
+            catch (error) {
+                if (!hasFsCode(error, 'ENOENT'))
+                    throw new StudioError('SAVE_AUTHORITY_UNAVAILABLE', 503);
+            }
+            throw new StudioError('SAVE_AUTHORITY_UNAVAILABLE', 503);
+        }
+        current = canonical;
+    }
+    function applyObservation(operation, value) {
+        if (!operation.receipt.asset)
+            return operation;
+        const previous = operation.receipt;
+        const integrityError = previous.error?.type === 'integrity' && previous.error.code.startsWith('SAVE_FILE_');
+        const error = previous.error && !integrityError ? previous.error : value.errorCode ? { code: value.errorCode, message: new StudioError(value.errorCode).message, type: 'integrity', httpStatus: 409, retryable: false, mayAlreadyBeSaved: true } : null;
+        const receipt = { ...previous, facts: { ...previous.facts, file: value.file }, checkedAt: value.checkedAt, integrityCheck: value.integrityCheck, safeRetry: value.integrityCheck === 'PENDING' ? false : previous.safeRetry, error };
+        if (JSON.stringify(receipt) === JSON.stringify(previous))
+            return operation;
+        return saveOperation.parse({ ...operation, receipt: { ...receipt, revision: previous.revision + 1, updatedAt: new Date().toISOString() } });
+    }
+    async function authority(initialize) {
+        const loaded = await disk();
+        if (loaded)
+            await prepareDocumentAuthority(root, 'output-saves', true, 'SAVE_AUTHORITY_INVALID');
+        if (current && (!loaded || JSON.stringify(current) !== JSON.stringify(loaded)))
+            throw new StudioError('SAVE_AUTHORITY_INVALID', 409);
+        if (loaded) {
+            if (!coldReady) {
+                const entries = loaded.integrityObservations.map(o => ({ assetId: o.assetId, revision: o.revision + 1, file: 'NOT_CHECKED', checkedAt: o.checkedAt, integrityCheck: 'IDLE' }));
+                const changed = loaded.integrityObservations.some(o => o.file !== 'NOT_CHECKED' || o.integrityCheck !== 'IDLE' || o.signature !== undefined || o.errorCode !== undefined);
+                const reset = changed ? { ...loaded, revision: loaded.revision + 1, integrityObservations: entries, operations: loaded.operations.map(op => { const entry = entries.find(o => o.assetId === op.assetId); return entry ? applyObservation(op, entry) : op; }) } : loaded;
+                if (legacy || changed)
+                    await commit(reset);
+                current = reset;
+                coldReady = true;
+                return reset;
+            }
+            current = loaded;
+            return loaded;
+        }
+        if (!initialize)
+            throw new StudioError('SAVE_AUTHORITY_INVALID', 409);
+        if ((await readdir(root.managedDir)).some(n => /^output-saves\..+\.tmp$/.test(n)))
+            throw new StudioError('SAVE_AUTHORITY_INVALID', 409);
+        await prepareDocumentAuthority(root, 'output-saves', false, 'SAVE_AUTHORITY_INVALID');
+        const empty = { schemaVersion: 2, revision: 0, rootId: randomUUID(), canonicalAssetsPath: root.assetsDir, connections: [], operations: [], integrityObservations: [] };
+        await commit(empty, true);
+        coldReady = true;
+        return empty;
+    }
+    async function updateOperation(operationId, connectionId, expectedRevision, patch, transfer, executionRevision) {
+        const before = await authority(false);
+        const operation = before.operations.find(o => o.receipt.operationId === operationId);
+        if (!operation)
+            throw new StudioError('SAVE_OPERATION_NOT_FOUND', 404);
+        if (operation.connectionId !== connectionId)
+            throw new StudioError('SAVE_BINDING_MISMATCH', 403);
+        if (executionRevision === undefined ? operation.receipt.revision !== expectedRevision : operation.executionRevision !== executionRevision)
+            throw Object.assign(new StudioError('SAVE_REVISION_CONFLICT', 409), { operation: structuredClone(operation) });
+        const checked = saveMutable.partial().safeParse(patch);
+        if (!checked.success)
+            throw new StudioError('SAVE_TRANSITION_INVALID', 409);
+        if (operation.receipt.integrityCheck === 'PENDING' && checked.data.state === 'SAVING' && operation.receipt.state !== 'SAVING')
+            throw new SaveIntegrityPending();
+        const receipt = { ...operation.receipt, ...checked.data, revision: operation.receipt.revision + 1, updatedAt: new Date().toISOString() };
+        const edges = { ACCEPTED: ['ACCEPTED', 'SAVING', 'RECOVERY_REQUIRED', 'BLOCKED', 'FAILED'], SAVING: ['SAVING', 'SAVED', 'FAILED', 'RECOVERY_REQUIRED', 'BLOCKED'], SAVED: ['SAVED'], FAILED: ['FAILED', 'SAVING', 'RECOVERY_REQUIRED', 'BLOCKED'], RECOVERY_REQUIRED: ['RECOVERY_REQUIRED', 'SAVING', 'BLOCKED'], BLOCKED: ['BLOCKED'] };
+        if (operation.receipt.state === 'FAILED' && receipt.state === 'RECOVERY_REQUIRED') {
+            const pending = operation.transfer?.completed ? (operation.receipt.facts.registration === 'ABSENT' ? 'SAVE_REGISTRATION_PENDING' : operation.receipt.facts.registration === 'PRESENT' && operation.receipt.facts.relation === 'ABSENT' ? 'SAVE_RELATION_PENDING' : undefined) : undefined;
+            if (!pending || receipt.error?.code !== pending)
+                throw new StudioError('SAVE_TRANSITION_INVALID', 409);
+        }
+        if (!edges[operation.receipt.state].includes(receipt.state) || (receipt.state === 'SAVING' && operation.receipt.state !== 'SAVING' && (receipt.attempt !== operation.receipt.attempt + 1 || (operation.receipt.state !== 'ACCEPTED' && !operation.receipt.safeRetry))) || (receipt.state === 'SAVING' && operation.receipt.state === 'SAVING' && receipt.attempt !== operation.receipt.attempt))
+            throw new StudioError('SAVE_TRANSITION_INVALID', 409);
+        let observed = before.integrityObservations.find(o => o.assetId === operation.assetId);
+        let integrityObservations = before.integrityObservations;
+        // A negative filesystem finding may invalidate a completed observation; it
+        // cannot mint VERIFIED. Do not cancel/replace a running hash's observation.
+        if (observed?.integrityCheck === 'IDLE' && checked.data.facts && ['UNSAFE', 'UNKNOWN', 'MISSING'].includes(checked.data.facts.file)) {
+            const file = checked.data.facts.file;
+            observed = { assetId: operation.assetId, revision: observed.revision + 1, file, checkedAt: observed.checkedAt, integrityCheck: 'IDLE', errorCode: { UNSAFE: 'SAVE_FILE_UNSAFE', UNKNOWN: 'SAVE_FILE_READ_FAILED', MISSING: 'SAVE_FILE_MISSING' }[file] };
+            integrityObservations = before.integrityObservations.map(o => o.assetId === operation.assetId ? observed : o);
+        }
+        const candidate = { ...operation, executionRevision: operation.executionRevision + 1, ...(transfer ? { transfer } : {}), receipt };
+        const projected = observed ? applyObservation(candidate, observed) : candidate;
+        const parsed = saveOperation.safeParse({ ...projected, receipt: { ...projected.receipt, revision: receipt.revision } });
+        if (!parsed.success)
+            throw new StudioError('SAVE_TRANSITION_INVALID', 409);
+        await commit({ ...before, revision: before.revision + 1, integrityObservations, operations: before.operations.map(o => o === operation ? parsed.data : o) });
+        return structuredClone(parsed.data);
+    }
+    return {
+        readIntegrity: () => serial(async () => {
+            const loaded = await disk();
+            if (!loaded) {
+                try {
+                    await lstat(path.join(root.managedDir, '.output-saves.initialized'));
+                }
+                catch (error) {
+                    if (hasFsCode(error, 'ENOENT') && !current)
+                        return undefined;
+                    throw new StudioError('SAVE_AUTHORITY_INVALID', 409);
+                }
+                throw new StudioError('SAVE_AUTHORITY_INVALID', 409);
+            }
+            return structuredClone(await authority(false));
+        }),
+        observeIntegrity: (assetId, expectedRevision, value, proof) => serial(async () => {
+            if (!uuid.safeParse(assetId).success || !Number.isSafeInteger(expectedRevision) || expectedRevision < 0)
+                throw new StudioError('SAVE_TRANSITION_INVALID', 409);
+            const checked = observationValue.safeParse(value);
+            if (!checked.success)
+                throw new StudioError('SAVE_TRANSITION_INVALID', 409);
+            if (value.file === 'VERIFIED' && (!isVerifiedHashResult(assetId, proof) || proof.checkedAt !== value.checkedAt || proof.signature !== value.signature))
+                throw new StudioError('SAVE_TRANSITION_INVALID', 409);
+            const before = await authority(true);
+            const previous = before.integrityObservations.find(o => o.assetId === assetId);
+            if ((previous?.revision ?? 0) !== expectedRevision)
+                throw new StudioError('SAVE_REVISION_CONFLICT', 409);
+            if (value.file !== 'VERIFIED' && value.checkedAt !== (previous?.checkedAt ?? null))
+                throw new StudioError('SAVE_TRANSITION_INVALID', 409);
+            const next = observation.parse({ assetId, revision: expectedRevision + 1, value: checked.data });
+            await commit({ ...before, revision: before.revision + 1, integrityObservations: [...before.integrityObservations.filter(o => o.assetId !== assetId), next], operations: before.operations.map(o => o.assetId === assetId ? applyObservation(o, value) : o) });
+            return structuredClone(next);
+        }),
+        accept: input => serial(async () => {
+            const parsed = saveAcceptInput.safeParse(input);
+            if (!parsed.success)
+                throw new StudioError('STUDIO_INPUT_INVALID');
+            const req = parsed.data;
+            const before = await authority(false);
+            if (!before.connections.some(c => c.connectionId === req.connectionId))
+                throw new StudioError('SAVE_BINDING_MISMATCH', 403);
+            const replay = before.operations.find(o => o.requestIds.includes(req.requestId));
+            if (replay && (replay.connectionId !== req.connectionId || replay.receipt.localOutputId !== req.localOutputId || replay.receipt.runId !== req.runId || replay.receipt.jobId !== req.jobId || replay.receipt.gatewayAssetId !== req.gatewayAssetId))
+                throw new StudioError('SAVE_REQUEST_CONFLICT', 409);
+            const existing = before.operations.find(o => o.connectionId === req.connectionId && o.receipt.localOutputId === req.localOutputId);
+            if (existing) {
+                if (existing.receipt.runId !== req.runId || existing.receipt.jobId !== req.jobId || existing.receipt.gatewayAssetId !== req.gatewayAssetId)
+                    throw new StudioError('SAVE_REQUEST_CONFLICT', 409);
+                if (!existing.requestIds.includes(req.requestId)) {
+                    if (existing.requestIds.length >= 1000)
+                        throw new StudioError('SAVE_AUTHORITY_INVALID', 409);
+                    const next = { ...existing, requestIds: [...existing.requestIds, req.requestId] };
+                    await commit({ ...before, revision: before.revision + 1, operations: before.operations.map(o => o === existing ? next : o) });
+                    return structuredClone(next);
+                }
+                return structuredClone(existing);
+            }
+            if (before.operations.length >= 10000)
+                throw new StudioError('SAVE_AUTHORITY_INVALID', 409);
+            const now = new Date().toISOString();
+            const operation = { connectionId: req.connectionId, requestIds: [req.requestId], assetId: randomUUID(), executionRevision: 1, receipt: {
+                    operationId: randomUUID(), revision: 1, localOutputId: req.localOutputId, runId: req.runId, jobId: req.jobId, gatewayAssetId: req.gatewayAssetId,
+                    state: 'ACCEPTED', stage: 'QUEUED', attempt: 0, facts: { file: 'NOT_CHECKED', registration: 'ABSENT', relation: 'ABSENT' }, asset: null, error: null,
+                    retryable: false, safeRetry: false, mayAlreadyBeSaved: false, checkedAt: null, integrityCheck: 'IDLE', createdAt: now, updatedAt: now
+                } };
+            await commit({ ...before, revision: before.revision + 1, operations: [...before.operations, operation] });
+            return structuredClone(operation);
+        }),
+        update: (...args) => serial(() => updateOperation(...args)),
+        advanceWorker: (expected, patch, transfer) => serial(() => {
+            const checked = saveOperation.safeParse(expected);
+            if (!checked.success)
+                throw new StudioError('SAVE_TRANSITION_INVALID', 409);
+            return updateOperation(expected.receipt.operationId, expected.connectionId, expected.receipt.revision, patch, transfer, checked.data.executionRevision);
+        }),
+        read: () => serial(async () => structuredClone(await authority(false))),
+        bind: bindingDigestRef => serial(async () => {
+            if (!digest.safeParse(bindingDigestRef).success)
+                throw new StudioError('SAVE_AUTHORITY_INVALID', 409);
+            const before = await authority(true);
+            if (before.connections.some(c => c.bindingDigestRef === bindingDigestRef))
+                return structuredClone(before);
+            if (before.connections.length >= 10000)
+                throw new StudioError('SAVE_AUTHORITY_INVALID', 409);
+            const next = { ...before, revision: before.revision + 1, connections: [...before.connections, { connectionId: randomUUID(), bindingDigestRef }] };
+            await commit(next);
+            return structuredClone(next);
+        }),
+    };
+}
+//# sourceMappingURL=output-save-journal.js.map

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

@@ -0,0 +1,18 @@
+import { type SaveOperation } from './output-save-contract.js';
+/** A partial is disposable only after its exclusive-open inode was durably
+ * recorded. Pre-open names alone never confer ownership of a user file. */
+export declare function reconcilePartialSaveFile(outputDir: string, value: SaveOperation): Promise<void>;
+/** Local-only ownership recovery, not phase-3 integrity observation or network
+ * retry. Does not register, overwrite, or delete any unproved file. */
+export declare function reconcilePublishedSaveFile(outputDir: string, value: SaveOperation, maxBytes: number, afterLinkBeforeUnlink?: () => void | Promise<void>, inspectOnly?: boolean): Promise<{
+    absolutePath: string;
+    completed: {
+        sha256: string;
+        byteLength: number;
+        mediaType: "image/png" | "image/jpeg" | "image/webp" | "video/mp4" | "video/webm";
+        relativePath: string;
+    };
+    repairedOwnedPair: boolean;
+    publishedFromTemporary: boolean;
+}>;
+//# sourceMappingURL=output-save-recovery.d.ts.map

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

@@ -0,0 +1,161 @@
+import { createHash } from 'node:crypto';
+import { lstat, open, unlink, readdir, link } from 'node:fs/promises';
+import path from 'node:path';
+import { saveOperation } from './output-save-contract.js';
+import { assertStudioRoot } from './paths.js';
+import { detectStudioMediaType } from './media.js';
+import { hasFsCode, StudioError } from './errors.js';
+/** A partial is disposable only after its exclusive-open inode was durably
+ * recorded. Pre-open names alone never confer ownership of a user file. */
+export async function reconcilePartialSaveFile(outputDir, value) {
+    const parsed = saveOperation.safeParse(value);
+    if (!parsed.success)
+        throw new StudioError('SAVE_TARGET_CONFLICT', 409);
+    const op = parsed.data;
+    if (op.transfer?.completed)
+        throw new StudioError('SAVE_TARGET_CONFLICT', 409);
+    const canonicalOutputDir = path.resolve(outputDir);
+    const managedDir = path.join(canonicalOutputDir, 'LumenKey');
+    const root = { canonicalOutputDir, managedDir, assetsDir: path.join(managedDir, 'assets') };
+    await assertStudioRoot(root);
+    const names = (await readdir(root.assetsDir)).filter(n => n.startsWith(`${op.assetId}.`));
+    if (names.some(n => n !== op.transfer?.temporaryName))
+        throw new StudioError('SAVE_TARGET_CONFLICT', 409);
+    if (!names.length)
+        return;
+    const transfer = op.transfer;
+    if (!transfer?.owner)
+        throw new StudioError('SAVE_TARGET_CONFLICT', 409);
+    const file = path.join(root.assetsDir, transfer.temporaryName);
+    const matches = (s) => s.isFile() && !s.isSymbolicLink() && s.nlink === 1 && String(s.dev) === transfer.owner.dev && String(s.ino) === transfer.owner.ino && s.birthtimeMs === transfer.owner.birthtimeMs;
+    if (!matches(await lstat(file)))
+        throw new StudioError('SAVE_PATH_UNSAFE', 409);
+    const h = await open(file, 'r');
+    try {
+        const before = await h.stat();
+        const current = await lstat(file);
+        if (!matches(before) || !matches(current) || before.size !== current.size || before.mtimeMs !== current.mtimeMs)
+            throw new StudioError('SAVE_PATH_UNSAFE', 409);
+        await assertStudioRoot(root);
+        const last = await lstat(file);
+        if (!matches(last) || last.size !== before.size || last.mtimeMs !== before.mtimeMs)
+            throw new StudioError('SAVE_PATH_UNSAFE', 409);
+        await unlink(file);
+    }
+    finally {
+        await h.close();
+    }
+}
+/** Local-only ownership recovery, not phase-3 integrity observation or network
+ * retry. Does not register, overwrite, or delete any unproved file. */
+export async function reconcilePublishedSaveFile(outputDir, value, maxBytes, afterLinkBeforeUnlink, inspectOnly = false) {
+    const parsed = saveOperation.safeParse(value);
+    if (!parsed.success || !parsed.data.transfer?.completed)
+        throw new StudioError('SAVE_TARGET_CONFLICT', 409);
+    const op = parsed.data;
+    const transfer = op.transfer;
+    const completed = transfer.completed;
+    const limit = Math.min(128 * 1024 * 1024, maxBytes);
+    if (!Number.isSafeInteger(limit) || completed.byteLength > limit)
+        throw new StudioError('SAVE_TARGET_CONFLICT', 409);
+    const canonicalOutputDir = path.resolve(outputDir);
+    const root = { canonicalOutputDir, managedDir: path.join(canonicalOutputDir, 'LumenKey'), assetsDir: path.join(canonicalOutputDir, 'LumenKey', 'assets') };
+    await assertStudioRoot(root);
+    const absolutePath = path.join(root.managedDir, completed.relativePath);
+    const temporaryPath = path.join(root.assetsDir, transfer.temporaryName);
+    let unpublished = false;
+    let candidate = absolutePath;
+    let finalStat;
+    try {
+        finalStat = await lstat(absolutePath);
+    }
+    catch (error) {
+        if (!hasFsCode(error, 'ENOENT'))
+            throw error;
+        if (inspectOnly)
+            throw new StudioError('SAVE_TARGET_CONFLICT', 409);
+        unpublished = true;
+        candidate = temporaryPath;
+        try {
+            finalStat = await lstat(temporaryPath);
+        }
+        catch {
+            throw new StudioError('SAVE_TARGET_CONFLICT', 409);
+        }
+    }
+    if (!finalStat.isFile() || finalStat.isSymbolicLink() || ![1, 2].includes(finalStat.nlink))
+        throw new StudioError('SAVE_PATH_UNSAFE', 409);
+    if (transfer.owner && (String(finalStat.dev) !== transfer.owner.dev || String(finalStat.ino) !== transfer.owner.ino || finalStat.birthtimeMs !== transfer.owner.birthtimeMs))
+        throw new StudioError('SAVE_PATH_UNSAFE', 409);
+    if (unpublished && finalStat.nlink !== 1)
+        throw new StudioError('SAVE_PATH_UNSAFE', 409);
+    let temporaryStat;
+    try {
+        temporaryStat = await lstat(temporaryPath);
+    }
+    catch (error) {
+        if (!hasFsCode(error, 'ENOENT'))
+            throw error;
+    }
+    const same = (a, b) => a.ino !== 0 && a.dev === b.dev && a.ino === b.ino;
+    const pair = finalStat.nlink === 2 && temporaryStat?.isFile() && !temporaryStat.isSymbolicLink() && temporaryStat.nlink === 2 && same(finalStat, temporaryStat);
+    if (!unpublished && ((finalStat.nlink === 2 && !pair) || (temporaryStat && !pair)))
+        throw new StudioError('SAVE_PATH_UNSAFE', 409);
+    const h = await open(candidate, 'r');
+    try {
+        const before = await h.stat();
+        if (!same(before, finalStat) || before.size !== completed.byteLength || before.nlink !== finalStat.nlink)
+            throw new StudioError('SAVE_TARGET_CONFLICT', 409);
+        const hash = createHash('sha256');
+        const buffer = Buffer.alloc(256 * 1024);
+        let offset = 0;
+        let prefix = Buffer.alloc(0);
+        for (;;) {
+            const { bytesRead } = await h.read(buffer, 0, Math.min(buffer.length, limit + 1 - offset), offset);
+            if (!bytesRead)
+                break;
+            offset += bytesRead;
+            if (offset > limit || offset > completed.byteLength)
+                throw new StudioError('SAVE_TARGET_CONFLICT', 409);
+            if (!prefix.length)
+                prefix = Buffer.from(buffer.subarray(0, Math.min(4096, bytesRead)));
+            hash.update(buffer.subarray(0, bytesRead));
+        }
+        if (offset !== completed.byteLength || hash.digest('hex') !== completed.sha256 || detectStudioMediaType(prefix) !== completed.mediaType)
+            throw new StudioError('SAVE_TARGET_CONFLICT', 409);
+        const after = await h.stat();
+        const current = await lstat(candidate);
+        const stable = (s) => same(before, s) && s.size === before.size && s.mtimeMs === before.mtimeMs && s.ctimeMs === before.ctimeMs && s.nlink === before.nlink && s.isFile() && !s.isSymbolicLink();
+        if (!stable(after) || !stable(current))
+            throw new StudioError('SAVE_PATH_UNSAFE', 409);
+        await assertStudioRoot(root);
+        if (!inspectOnly && (pair || unpublished)) {
+            const tempNow = await lstat(temporaryPath);
+            if (!stable(tempNow))
+                throw new StudioError('SAVE_PATH_UNSAFE', 409);
+            if (unpublished) {
+                // Exclusive publication only after transport checkpoint/hash/type proof.
+                try {
+                    await link(temporaryPath, absolutePath);
+                }
+                catch (error) {
+                    if (hasFsCode(error, 'EEXIST'))
+                        throw new StudioError('SAVE_TARGET_CONFLICT', 409);
+                    throw error;
+                }
+                await afterLinkBeforeUnlink?.();
+            }
+            await unlink(temporaryPath);
+            const single = await lstat(absolutePath);
+            const handleSingle = await h.stat();
+            if (!same(before, single) || !same(before, handleSingle) || single.nlink !== 1 || handleSingle.nlink !== 1 || single.size !== before.size || single.mtimeMs !== before.mtimeMs)
+                throw new StudioError('SAVE_PATH_UNSAFE', 409);
+        }
+        // No checkedAt / VERIFIED fact is returned by this repair primitive.
+        return { absolutePath, completed: structuredClone(completed), repairedOwnedPair: !!pair, publishedFromTemporary: unpublished };
+    }
+    finally {
+        await h.close();
+    }
+}
+//# sourceMappingURL=output-save-recovery.js.map