@agentshouse/mdruntime 0.1.0-cefbc8bb8a1c0 → 0.1.0-cf04ede9fb796

package/dist/saves.js

@@ -0,0 +1,1008 @@
+import { parseFrontmatter } from '@agentshouse/mdmodel';
+import { binaryRecord } from './binary.js';
+import { changeSet, mergeChangeSets } from './change-set.js';
+import { leaving as leavingIn, partnerOf, queuedFile, } from './change.js';
+import { available, composedOf } from './collection.js';
+import { runtimeError } from './failure.js';
+import { attachedFile } from './file.js';
+import { roomDraftRevision } from './identity.js';
+import { confirmedAgain } from './install.js';
+import { compositionFor } from './listing.js';
+import { absentBinary, attachAnswer, binaryAnswer, binaryLinkAnswer, failure, OFFLINE, UNCERTAIN, } from './outcome.js';
+import { sameBinary } from './overlay.js';
+import { ancestors } from './paths.js';
+import { connectionNow, prepare } from './preparation.js';
+import { entryAt, landed, movedBy, overlayOf, replaying, slicing, slicingWith, standing, storedRecord, touchedBy, } from './replica.js';
+import { binaryBase, changedParts, changesOf, held, heldFile, joinedDraft, moveTarget, readSavedParts, returnedBy, returnedInto, withdrawnDrafts, } from './room-draft.js';
+import { refuse } from './refusal.js';
+import { visibleOf } from './room-drafts.js';
+import { documentKey } from './rows.js';
+import { buildBatch, buildMove, joined, limiting, queuedDocuments, requeuing, } from './save.js';
+import { pendingShown } from './shown.js';
+import { paced, ROW_WEIGHT, stepped } from './turn.js';
+import { validatedNeighbourhood } from './validation.js';
+export function withdrawable(states) {
+    return (batch) => {
+        const state = states.get(batch.id);
+        return state !== undefined && state.submission.state !== 'submitted' && !state.lost;
+    };
+}
+export async function sliceAt(store, record, view, queue, extra = [], moved = []) {
+    const local = await store.open();
+    const needed = new Set([...touchedBy(queue), ...extra]);
+    const movedPaths = [...new Set([...movedBy(queue, record.locator), ...moved])];
+    if (movedPaths.length > 0) {
+        for (const { path } of await local.referrers(record.key, view, movedPaths)) {
+            needed.add(path);
+        }
+    }
+    const paths = [...needed];
+    return stepped(slicing(await local.entries(record.key, view, paths), paths));
+}
+export async function landedWhole(store, locator, batch, confirmedLayer, current) {
+    if (!landed(batch, confirmedLayer, current))
+        return false;
+    const partner = partnerOf(batch, locator);
+    if (partner === null)
+        return true;
+    const other = await store.replica(partner);
+    const half = other?.queue.find((one) => one.id === batch.id);
+    if (other === undefined || half === undefined)
+        return false;
+    return landed(half, await sliceAt(store, other.record, 'confirmed', [half]));
+}
+async function carriedBack(store, locator, unlanded, written) {
+    const back = new Map();
+    const taken = [];
+    for (const batch of unlanded) {
+        const between = batch.between;
+        if (between === undefined)
+            continue;
+        const source = between.source.room;
+        const destination = between.destination.room;
+        const local = await store.open();
+        const arrived = (await local.pending(destination, batch.id)).state?.drafts ?? [];
+        for (const { path: to } of arrived) {
+            const record = await store.draft(destination, to);
+            const path = between.moves.find((move) => move.to === to)?.path;
+            if (record === undefined || path === undefined)
+                continue;
+            const [into, key] = source === locator ? [written, path] : [back, documentKey(source, path)];
+            const existing = into.get(key) ?? (await store.draft(source, path));
+            taken.push({ locator: destination, path: to });
+            into.set(key, {
+                locator: source,
+                path,
+                revision: roomDraftRevision(),
+                parts: returnedInto(existing?.parts, record.parts),
+                returned: existing?.returned ?? null,
+            });
+        }
+    }
+    const records = [...back.values()];
+    const elsewhere = taken.filter((one) => one.locator !== locator);
+    const rooms = new Set([...records, ...elsewhere].map((one) => one.locator));
+    return {
+        taken: taken.filter((one) => one.locator === locator).map(({ path }) => path),
+        writes: [...rooms].map((room) => ({
+            locator: room,
+            roomDrafts: records.filter((record) => record.locator === room),
+            consumedRoomDrafts: elsewhere.filter((one) => one.locator === room).map(({ path }) => path),
+        })),
+        changes: [...rooms].map((room) => changeSet(room, {
+            drafts: [...records, ...elsewhere]
+                .filter((one) => one.locator === room)
+                .map(({ path }) => path),
+        })),
+    };
+}
+export function preparedAfter(runtime, locator, answer) {
+    if (answer.indexed[locator] === false)
+        prepare(runtime, [locator]);
+}
+export function replayed(store, record, confirmedLayer, queue) {
+    return stepped(replaying(confirmedLayer, queue, record.locator, store.composed(record)));
+}
+export async function overlayDiff(record, before, visible, touched) {
+    const kept = before !== undefined && before.record.key === record.key ? before.overlaid : new Set();
+    return {
+        overlay: {
+            set: await stepped(overlayOf(visible, touched)),
+            cleared: [...kept].filter((path) => !touched.has(path)),
+        },
+        touched,
+    };
+}
+export async function settle(runtime, local, locator, work, record, queue, settling = {}) {
+    return together(runtime, local, [
+        await settlement(runtime, local, locator, work, record, queue, settling),
+    ]);
+}
+async function unpairedIn(store, locator, batch) {
+    const { state } = await (await store.open()).pending(locator, batch.id);
+    if (state === undefined)
+        return false;
+    return !leavingIn(batch, locator) || withdrawable(new Map([[batch.id, state]]))(batch);
+}
+export async function together(runtime, local, settlements) {
+    const settled = new Set(settlements.map(({ locator }) => locator));
+    const all = [...settlements];
+    for (let wave = settlements; wave.length > 0;) {
+        const partnered = new Map();
+        for (const { locator, left } of wave) {
+            for (const batch of left) {
+                const partner = partnerOf(batch, locator);
+                if (partner === null ||
+                    settled.has(partner) ||
+                    !(await unpairedIn(runtime.store, partner, batch))) {
+                    continue;
+                }
+                partnered.set(partner, [...(partnered.get(partner) ?? []), batch]);
+            }
+        }
+        const partners = [];
+        for (const [partner, batches] of partnered) {
+            settled.add(partner);
+            partners.push(await unpairing(runtime, local, partner, batches));
+        }
+        all.push(...partners);
+        wave = partners;
+    }
+    const answer = await local.commit({
+        rooms: all.flatMap(({ commit }) => commit.rooms),
+        writes: all.flatMap(({ commit }) => commit.writes),
+    });
+    return mergeChangeSets(all.map((one) => one.apply(answer)));
+}
+export async function settlement(runtime, local, locator, work, record, queue, settling = {}) {
+    const { store, journal, localSaves } = runtime;
+    const before = work.replica;
+    const view = settling.view ?? 'confirmed';
+    const previousQueue = work.queue;
+    const overrides = settling.changes;
+    const read = await sliceAt(store, record, view, queue, [
+        ...(before !== undefined && before.record.key === record.key ? before.overlaid : []),
+        ...(overrides?.set.map(({ path }) => path) ?? []),
+        ...(overrides?.removed ?? []),
+    ]);
+    const confirmedLayer = overrides === undefined
+        ? read
+        : await stepped(slicingWith(read, overrides.set, overrides.removed));
+    const composition = store.composed(record);
+    const shown = queue.filter((batch) => {
+        const held = store.landed.of(locator, batch.id);
+        return (held !== undefined &&
+            Object.entries(held).some(([path, revision]) => confirmedLayer.revisions[path] !== revision));
+    });
+    const unshown = queue.filter((batch) => !shown.includes(batch));
+    const { withdrawn, kept } = await stepped(standing(confirmedLayer, unshown, withdrawable(work.states), localSaves, locator, composition));
+    const founded = kept.filter((batch) => !unshown.includes(batch));
+    const queueChanged = kept.length !== previousQueue.length || founded.length > 0;
+    const unqueued = shown.map((batch) => ({ batch, landed: true }));
+    for (const batch of withdrawn) {
+        unqueued.push({ batch, landed: await landedWhole(store, locator, batch, confirmedLayer) });
+    }
+    const returning = [
+        ...[...unqueued].reverse().map(({ batch, landed: held }) => ({
+            batch,
+            returned: localSaves || held ? null : returnedBy('withdrawn'),
+        })),
+        ...(settling.leaving ?? []),
+    ];
+    const written = new Map();
+    for (const { batch, returned: reason } of returning) {
+        if (reason === null || batch.between?.destination.room === locator)
+            continue;
+        for (const saved of work.states.get(batch.id)?.drafts ?? []) {
+            const existing = written.get(saved.path) ?? (await store.draft(locator, saved.path));
+            written.set(saved.path, {
+                locator,
+                path: saved.path,
+                revision: roomDraftRevision(),
+                parts: returnedInto(existing?.parts, saved.parts),
+                returned: reason,
+            });
+        }
+    }
+    const carried = await carriedBack(store, locator, [
+        ...[...unqueued].reverse().flatMap(({ batch, landed: held }) => (held ? [] : [batch])),
+        ...(settling.leaving ?? []).flatMap(({ batch, returned }) => returned === null ? [] : [batch]),
+    ], written);
+    const replayedLayer = await replayed(store, record, confirmedLayer, kept);
+    const { overlay } = await overlayDiff(record, before, replayedLayer.visible, replayedLayer.touched);
+    const commit = {
+        rooms: [
+            {
+                locator,
+                key: record.key,
+                record: storedRecord(record),
+                roots: record.typedSelection?.roots ?? [],
+                composed: composedOf(composition),
+                ...settling.commit,
+                ...(overrides === undefined
+                    ? {}
+                    : { confirmed: { set: overrides.set, removed: overrides.removed } }),
+                overlay,
+            },
+        ],
+        writes: [
+            {
+                locator,
+                queue: kept,
+                stored: previousQueue,
+                founded,
+                roomDrafts: [...written.values()],
+                consumedRoomDrafts: carried.taken,
+            },
+            ...carried.writes,
+        ],
+    };
+    const staying = new Set(kept.map((batch) => batch.id));
+    return {
+        locator,
+        left: previousQueue.filter((batch) => !staying.has(batch.id)),
+        commit,
+        apply: (answer) => {
+            for (const batch of previousQueue) {
+                if (!staying.has(batch.id))
+                    store.landed.drop(locator, batch.id);
+            }
+            const drafts = [...written.keys(), ...carried.taken];
+            for (const { batch, landed: held } of unqueued) {
+                const outcome = localSaves ? 'dropped' : held ? 'landed' : 'withdrawn';
+                journal.record(`outcome ${locator} ${batch.id} ${outcome}`);
+            }
+            const changed = answer.changed[locator];
+            if (settling.commit?.published !== undefined ||
+                settling.commit?.refreshed === true ||
+                overrides !== undefined) {
+                confirmedAgain(store, locator);
+            }
+            preparedAfter(runtime, locator, answer);
+            return mergeChangeSets([
+                changeSet(locator, {
+                    documents: changed === undefined ? [] : changed,
+                    room: settling.room,
+                    queue: queueChanged,
+                    drafts,
+                }),
+                ...carried.changes,
+            ]);
+        },
+    };
+}
+export async function unpairing(runtime, local, locator, batches) {
+    const { store, journal, localSaves, submitLater } = runtime;
+    const ids = new Set(batches.map(({ id }) => id));
+    const leaving = batches.map((batch) => ({
+        batch,
+        returned: !localSaves && leavingIn(batch, locator) ? returnedBy('withdrawn') : null,
+    }));
+    const outcome = localSaves ? 'dropped' : 'unpaired';
+    const work = await store.work(locator);
+    const current = work.replica;
+    if (current !== undefined) {
+        const settled = await settlement(runtime, local, locator, work, current.record, current.queue.filter((one) => !ids.has(one.id)), { leaving });
+        return {
+            ...settled,
+            apply(answer) {
+                for (const batch of batches)
+                    journal.record(`outcome ${locator} ${batch.id} ${outcome}`);
+                const set = settled.apply(answer);
+                submitLater(locator);
+                return set;
+            },
+        };
+    }
+    const queue = work.queue.filter((one) => !ids.has(one.id));
+    const written = new Map();
+    for (const { batch, returned } of leaving) {
+        if (returned === null)
+            continue;
+        for (const saved of work.states.get(batch.id)?.drafts ?? []) {
+            written.set(saved.path, {
+                locator,
+                path: saved.path,
+                revision: roomDraftRevision(),
+                parts: returnedInto((written.get(saved.path) ?? (await store.draft(locator, saved.path)))?.parts, saved.parts),
+                returned,
+            });
+        }
+    }
+    const carried = await carriedBack(store, locator, leaving.flatMap(({ batch, returned }) => (returned === null ? [] : [batch])), written);
+    return {
+        locator,
+        left: batches,
+        commit: {
+            rooms: [],
+            writes: [
+                {
+                    locator,
+                    queue,
+                    stored: work.queue,
+                    roomDrafts: [...written.values()],
+                    consumedRoomDrafts: carried.taken,
+                },
+                ...carried.writes,
+            ],
+        },
+        apply() {
+            for (const batch of batches)
+                journal.record(`outcome ${locator} ${batch.id} ${outcome}`);
+            submitLater(locator);
+            return mergeChangeSets([
+                changeSet(locator, {
+                    queue: true,
+                    drafts: [...written.keys(), ...carried.taken],
+                }),
+                ...carried.changes,
+            ]);
+        },
+    };
+}
+async function savedRoom(store, locator) {
+    const local = await store.open();
+    const replica = await store.replica(locator);
+    if (replica === undefined || store.fences.has(locator)) {
+        throw runtimeError('unknown-room', `Unknown Room ${locator}`);
+    }
+    return { local, replica };
+}
+export async function saveRoomDrafts(runtime, locator, named, writtenBy) {
+    const { store } = runtime;
+    const target = await savedRoom(store, locator);
+    const drafts = new Map((await store.drafts(locator, named.map(({ path }) => path))).map((record) => [record.path, record]));
+    const saved = [];
+    for (const { path, revision } of named) {
+        const record = drafts.get(path);
+        if (record === undefined || record.revision !== revision) {
+            return { outcome: 'refused', code: 'stale', retryable: false, file: path };
+        }
+        if (!saved.some((draft) => draft.path === path))
+            saved.push({ path, parts: record.parts });
+    }
+    return committed(runtime, locator, target, saved, new Set(saved.map(({ path }) => path)), writtenBy);
+}
+export async function saveParts(runtime, locator, named, writtenBy) {
+    const { store } = runtime;
+    const read = readSavedParts(named);
+    const target = await savedRoom(store, locator);
+    const saved = [];
+    const files = [];
+    const filed = read.filter(({ parts }) => parts.file !== undefined).map(({ path }) => path);
+    const visible = filed.length === 0 ? undefined : await visibleOf(store, locator, filed);
+    for (const { path, parts } of read) {
+        const file = parts.file === undefined
+            ? undefined
+            : await heldFile(parts.file.blob, parts.file.base === undefined ? binaryBase(visible, path) : parts.file.base);
+        if (parts.file !== undefined && file !== undefined) {
+            files.push({ key: file.localId, blob: parts.file.blob });
+        }
+        saved.push({ path, parts: held(undefined, parts, file) });
+    }
+    return committed(runtime, locator, target, saved, new Set(), writtenBy, files);
+}
+async function carriedDrafts(store, locator, saved, consumed) {
+    if (!saved.some(({ parts }) => parts.move !== undefined))
+        return new Map();
+    const holding = new Map((await store.drafts(locator)).map((record) => [record.path, record]));
+    return new Map(saved.flatMap(({ path, parts }) => {
+        const record = holding.get(path);
+        if (parts.move === undefined || record === undefined || consumed.has(path))
+            return [];
+        const to = moveTarget(parts.move);
+        if (to === path || holding.has(to))
+            return [];
+        return [[path, { ...record, path: to, revision: roomDraftRevision() }]];
+    }));
+}
+async function savingIn(store, replica, changes, extra, leaving = []) {
+    const record = replica.record;
+    const local = await store.open();
+    const paths = [
+        ...extra,
+        ...changes.flatMap((change) => change.kind === 'move' ? [change.path, change.to] : [change.path]),
+    ];
+    const moved = [
+        ...leaving,
+        ...changes.flatMap((change) => (change.kind === 'move' ? [change.path] : [])),
+    ];
+    const removed = changes.flatMap((change) => (change.kind === 'remove' ? [change.path] : []));
+    const referring = removed.length === 0
+        ? []
+        : (await local.referrers(record.key, 'confirmed', removed)).map(({ path }) => path);
+    const confirmedLayer = await sliceAt(store, record, 'confirmed', replica.queue, [...paths, ...paths.flatMap(ancestors), ...referring], moved);
+    const { visible } = await replayed(store, record, confirmedLayer, replica.queue);
+    const composition = store.composed(record);
+    return {
+        record,
+        confirmed: confirmedLayer,
+        visible,
+        folders: new Set(await local.folders(record.key, 'visible', paths)),
+        *visibleOver(queue) {
+            return (yield* replaying(confirmedLayer, queue, record.locator, composition)).visible;
+        },
+    };
+}
+async function unmodeledIn(runtime, record) {
+    const composition = compositionFor(runtime, record);
+    if (available(composition))
+        return false;
+    const local = await runtime.store.open();
+    const roots = record.typedSelection?.roots ?? [];
+    return local.typedWithin(record.key, 'visible', roots, false);
+}
+function textDiffers(left, right) {
+    return ((left?.content ?? undefined) !== (right?.content ?? undefined) ||
+        !sameBinary(left?.binary ?? undefined, right?.binary ?? undefined));
+}
+function textOf(entry) {
+    if (entry === null)
+        return undefined;
+    return entry.binary !== null ? null : entry.content;
+}
+function lookupOf(local, key, view) {
+    return async (paths) => {
+        if (paths.length === 0)
+            return new Map();
+        return new Map((await local.typed(key, view, paths)).map(({ path, type, binary }) => [
+            path,
+            { type: type ?? undefined, binary },
+        ]));
+    };
+}
+function declaredOf(entry) {
+    if (entry.binary !== null)
+        return { type: undefined, binary: true };
+    const read = parseFrontmatter(entry.content ?? '');
+    return { type: read.ok ? (read.frontmatter.type ?? 'any') : undefined, binary: false };
+}
+function overriddenLookup(lookup, overrides) {
+    return async (paths) => {
+        const known = new Map(await lookup(paths.filter((path) => !overrides.has(path))));
+        for (const path of paths) {
+            const entry = overrides.get(path);
+            if (entry === undefined)
+                continue;
+            if (entry === null)
+                known.delete(path);
+            else
+                known.set(path, declaredOf(entry));
+        }
+        return known;
+    };
+}
+function validatorOf(runtime, record, confirmedLayer) {
+    return async (resulting, touched) => {
+        const local = await runtime.store.open();
+        const changes = [];
+        const overrides = new Map();
+        const pace = paced();
+        for (const path of new Set([...confirmedLayer.held, ...touched])) {
+            await pace(ROW_WEIGHT);
+            const was = entryAt(confirmedLayer, path);
+            const now = entryAt(resulting, path);
+            if (!textDiffers(was, now))
+                continue;
+            overrides.set(path, now);
+            if (textOf(was) !== textOf(now))
+                changes.push({ path, was: textOf(was), now: textOf(now) });
+        }
+        return validatedNeighbourhood(changes, compositionFor(runtime, record), {
+            lookup: overriddenLookup(lookupOf(local, record.key, 'confirmed'), overrides),
+            texts: textsOf(local, record.key, 'confirmed'),
+            referrers: referrersOf(local, record.key, 'confirmed'),
+        });
+    };
+}
+function textsOf(local, key, view) {
+    return async (paths) => new Map((await local.entries(key, view, paths)).map(({ path, content, binary }) => [
+        path,
+        binary !== null ? null : content,
+    ]));
+}
+function referrersOf(local, key, view) {
+    return async (targets) => [
+        ...new Set((await local.referrers(key, view, targets)).map(({ path }) => path)),
+    ];
+}
+async function sideOf(runtime, locator, replica, saving) {
+    const record = replica.record;
+    return {
+        room: locator,
+        handle: record.handle,
+        baseRoomVersion: record.roomVersion,
+        composition: compositionFor(runtime, record),
+        operations: record.operations,
+        providerOwnedPaths: record.providerOwnedPaths,
+        authoredPaths: record.authoredPaths,
+        visible: saving.visible,
+        folders: saving.folders,
+        queued: queuedDocuments(replica.queue),
+        unmodeled: await unmodeledIn(runtime, record),
+        validate: validatorOf(runtime, record, saving.confirmed),
+    };
+}
+function movedInto(locator, saved) {
+    const into = saved.find(({ parts }) => parts.move?.room !== undefined && parts.move.room !== locator);
+    return into?.parts.move?.room ?? null;
+}
+async function saveCommit(store, local, files, rooms) {
+    const commits = [];
+    for (const { locator, saving, before, queue } of rooms) {
+        const replayedLayer = await replayed(store, saving.record, saving.confirmed, queue);
+        const diff = await overlayDiff(saving.record, before, replayedLayer.visible, replayedLayer.touched);
+        commits.push({
+            locator,
+            key: saving.record.key,
+            roots: saving.record.typedSelection?.roots ?? [],
+            composed: composedOf(store.composed(saving.record)),
+            overlay: diff.overlay,
+        });
+    }
+    try {
+        return await local.commit({
+            rooms: commits,
+            writes: rooms.map(({ write }) => write),
+            files,
+            whole: true,
+        });
+    }
+    catch {
+        return null;
+    }
+}
+async function committedMove(runtime, locator, destination, { local, replica }, saved, consumed, writtenBy, files) {
+    const { store, localSaves } = runtime;
+    const mixed = saved.find(({ parts }) => Object.keys(parts).length !== 1 || parts.move?.room !== destination);
+    if (mixed !== undefined) {
+        return { outcome: 'refused', code: 'mixed-room-move', retryable: false, file: mixed.path };
+    }
+    const moves = saved.map(({ path, parts }) => ({ path, to: moveTarget(parts.move) }));
+    const sourceSaving = await savingIn(store, replica, moves.map(({ path }) => ({ kind: 'remove', path })), saved.map(({ path }) => path), moves.map(({ path }) => path));
+    const changed = saved.flatMap(({ path, parts }) => changedParts(path, parts, sourceSaving.visible));
+    if (changed.length > 0)
+        return { outcome: 'refused', code: 'changed-underneath', retryable: false, parts: changed };
+    const target = await store.replica(destination);
+    if (target === undefined || store.fences.has(destination)) {
+        throw runtimeError('unknown-room', `Unknown Room ${destination}`);
+    }
+    const arriving = await savingIn(store, target, [], moves.map(({ to }) => to));
+    const built = await buildMove({
+        source: await sideOf(runtime, locator, replica, sourceSaving),
+        destination: await sideOf(runtime, destination, target, arriving),
+        moves,
+        providerLimits: (await local.facts()).providerLimits,
+        pathRule: runtime.pathRule,
+        local: localSaves,
+        ...(writtenBy === undefined ? {} : { writtenBy }),
+    });
+    if (built.kind === 'refused')
+        return { outcome: 'refused', ...built.refusal };
+    const id = built.leaving.id;
+    const leavingDrafts = new Map((await store.drafts(locator, saved.map(({ path }) => path))).map((record) => [record.path, record]));
+    const arrivingDrafts = new Set((await store.drafts(destination, moves.map(({ to }) => to))).map(({ path }) => path));
+    const carrying = saved.flatMap(({ path, parts }) => {
+        const record = leavingDrafts.get(path);
+        const to = moveTarget(parts.move);
+        if (record === undefined || consumed.has(path) || arrivingDrafts.has(to)) {
+            return [];
+        }
+        const moved = {
+            ...record,
+            locator: destination,
+            path: to,
+            revision: roomDraftRevision(),
+        };
+        return [{ from: path, record: moved }];
+    });
+    const carried = carrying.map(({ record }) => record);
+    const marked = carried.map(({ path }) => ({ path, parts: {} }));
+    const left = [...consumed, ...carrying.map(({ from }) => from)];
+    const leavingQueue = [...replica.queue, built.leaving];
+    const arrivingQueue = [...target.queue, built.arriving];
+    const answer = await saveCommit(store, local, files, [
+        {
+            locator,
+            saving: sourceSaving,
+            before: replica,
+            queue: leavingQueue,
+            write: {
+                locator,
+                queue: leavingQueue,
+                stored: replica.queue,
+                saved: new Map([[id, saved]]),
+                consumedRoomDrafts: left,
+            },
+        },
+        {
+            locator: destination,
+            saving: arriving,
+            before: target,
+            queue: arrivingQueue,
+            write: {
+                locator: destination,
+                queue: arrivingQueue,
+                stored: target.queue,
+                saved: new Map([[id, marked]]),
+                roomDrafts: carried,
+            },
+        },
+    ]);
+    if (answer === null)
+        return { outcome: 'refused', code: 'durable-write', retryable: true };
+    if (answer.fenced !== null) {
+        throw runtimeError('unknown-room', `Unknown Room ${answer.fenced}`);
+    }
+    if (store.fences.has(locator) || store.fences.has(destination)) {
+        throw runtimeError('unknown-room', `Unknown Room ${locator}`);
+    }
+    preparedAfter(runtime, locator, answer);
+    preparedAfter(runtime, destination, answer);
+    const shownNow = store.changed(mergeChangeSets([
+        changeSet(locator, {
+            documents: answer.changed[locator] ?? [],
+            queue: true,
+            drafts: left,
+        }),
+        changeSet(destination, {
+            documents: answer.changed[destination] ?? [],
+            queue: true,
+            drafts: carried.map(({ path }) => path),
+        }),
+    ]));
+    await Promise.all([shownNow, queuedSave(runtime, locator)]);
+    return { outcome: 'saved', identifier: id };
+}
+function queuedSave(runtime, locator) {
+    const shownNow = pendingShown(runtime);
+    runtime.submitLater(locator);
+    return shownNow;
+}
+async function committed(runtime, locator, target, saved, consumed, writtenBy, files = []) {
+    const { store, localSaves } = runtime;
+    if (store.space.full())
+        return { outcome: 'refused', code: 'durable-write', retryable: true };
+    const into = movedInto(locator, saved);
+    if (into !== null) {
+        return committedMove(runtime, locator, into, target, saved, consumed, writtenBy, files);
+    }
+    const { local, replica } = target;
+    const { providerLimits } = await local.facts();
+    const parts = saved.map(({ path, parts: held }) => changesOf(path, held));
+    const changes = parts.flatMap(({ changes: made }) => made);
+    const saving = await savingIn(store, replica, changes, [
+        ...saved.map(({ path }) => path),
+        ...parts.flatMap(({ bases }) => bases.map(({ path }) => path)),
+    ]);
+    const changed = saved.flatMap(({ path, parts: held }) => changedParts(path, held, saving.visible));
+    if (changed.length > 0)
+        return { outcome: 'refused', code: 'changed-underneath', retryable: false, parts: changed };
+    const requeue = await stepped(requeuing(replica.queue, changes, saving.visible, withdrawable(replica.states), saving.visibleOver));
+    if (requeue.kind === 'refused')
+        return { outcome: 'refused', ...requeue.refusal };
+    const foreign = [...requeue.withdrawn.keys()].some((origin) => {
+        const writer = replica.queue.find((batch) => batch.id === origin)?.writtenBy;
+        return writer?.app !== writtenBy?.app || writer?.release !== writtenBy?.release;
+    });
+    if (foreign) {
+        return {
+            outcome: 'refused',
+            code: 'unknown-revision',
+            retryable: false,
+            file: [...requeue.queued].at(-1),
+        };
+    }
+    const withdrawing = requeue.withdrawn.size > 0;
+    const input = {
+        local: localSaves,
+        baseRoomVersion: replica.record.roomVersion,
+        composition: compositionFor(runtime, replica.record),
+        operations: replica.record.operations,
+        providerOwnedPaths: replica.record.providerOwnedPaths,
+        authoredPaths: replica.record.authoredPaths,
+        providerLimits,
+        pathRule: runtime.pathRule,
+        handle: replica.record.handle,
+        visible: saving.visible,
+        folders: saving.folders,
+        changes,
+        bases: parts.flatMap(({ bases }) => bases),
+        queued: queuedDocuments(replica.queue),
+        writtenBy,
+        unmodeled: await unmodeledIn(runtime, replica.record),
+        validate: validatorOf(runtime, replica.record, saving.confirmed),
+    };
+    const checked = withdrawing
+        ? await buildBatch({ ...input, queued: new Set([...input.queued, ...requeue.queued]) })
+        : null;
+    if (checked?.kind === 'refused')
+        return { outcome: 'refused', ...checked.refusal };
+    const owners = [...requeue.owners].flatMap((origin) => {
+        const batch = requeue.withdrawn.get(origin);
+        return batch === undefined || batch === null ? [] : [{ origin, batch }];
+    });
+    if (owners.length > 1) {
+        return {
+            outcome: 'refused',
+            code: 'unknown-revision',
+            retryable: false,
+            file: [...requeue.queued].at(-1),
+        };
+    }
+    const built = !withdrawing
+        ? await buildBatch(input)
+        : requeue.changes.length === 0
+            ? null
+            : await buildBatch({
+                ...input,
+                visible: await stepped(saving.visibleOver(requeue.queue)),
+                changes: requeue.changes,
+                queued: queuedDocuments(requeue.queue),
+            });
+    if (built?.kind === 'refused')
+        return { outcome: 'refused', ...built.refusal };
+    const [owner] = owners;
+    const join = built === null || owner === undefined ? null : joined(requeue.queue, owner.batch, built.batch);
+    if (join?.kind === 'refused')
+        return { outcome: 'refused', ...join.refusal };
+    const withdrawn = new Map(requeue.withdrawn);
+    if (join !== null && owner !== undefined)
+        withdrawn.set(owner.origin, join.batch);
+    const drafted = new Map();
+    for (const [origin, replaced] of withdrawn) {
+        if (replaced === null)
+            continue;
+        const carried = withdrawnDrafts(replica.states.get(origin)?.drafts ?? [], changes);
+        drafted.set(replaced.id, replaced === join?.batch
+            ? [
+                ...carried.map((held) => joinedDraft(held, saved)),
+                ...saved.filter((draft) => !carried.some((held) => held.path === draft.path)),
+            ]
+            : carried);
+    }
+    if (built !== null && join === null)
+        drafted.set(built.batch.id, saved);
+    const batches = join !== null ? join.queue : built === null ? requeue.queue : [...requeue.queue, built.batch];
+    for (const replaced of withdrawn.values()) {
+        if (replaced === null || !batches.includes(replaced))
+            continue;
+        const limited = await stepped(limiting(batches, replaced, providerLimits, saving.visibleOver));
+        if (limited !== null)
+            return { outcome: 'refused', ...limited };
+    }
+    const carried = await carriedDrafts(store, locator, saved, consumed);
+    const left = [...consumed, ...carried.keys()];
+    const arrived = [...carried.values()];
+    const answer = await saveCommit(store, local, files, [
+        {
+            locator,
+            saving,
+            before: replica,
+            queue: batches,
+            write: {
+                locator,
+                queue: batches,
+                stored: replica.queue,
+                saved: drafted,
+                consumedRoomDrafts: left,
+                roomDrafts: arrived,
+            },
+        },
+    ]);
+    if (answer === null)
+        return { outcome: 'refused', code: 'durable-write', retryable: true };
+    if (answer.fenced !== null) {
+        throw runtimeError('unknown-room', `Unknown Room ${answer.fenced}`);
+    }
+    if (store.fences.has(locator))
+        throw runtimeError('unknown-room', `Unknown Room ${locator}`);
+    preparedAfter(runtime, locator, answer);
+    const shownNow = store.changed(changeSet(locator, {
+        documents: answer.changed[locator] ?? [],
+        queue: true,
+        drafts: [...left, ...arrived.map(({ path }) => path)],
+    }));
+    await Promise.all([shownNow, queuedSave(runtime, locator)]);
+    const identifier = join?.batch.id ??
+        built?.batch.id ??
+        [...requeue.withdrawn].map(([origin, replaced]) => replaced?.id ?? origin).at(-1);
+    return { outcome: 'saved', identifier };
+}
+async function queuedFacts(store, locator, path, localId) {
+    for (const batch of (await store.replica(locator))?.queue ?? []) {
+        const change = batch.changes[queuedFile(batch, path, localId)];
+        if (change?.kind === 'binary')
+            return change;
+    }
+    const drafted = (await store.draft(locator, path))?.parts.file;
+    return drafted?.localId === localId ? drafted : null;
+}
+export function batchFile(store, batch) {
+    return async (localId) => {
+        const change = batch.changes.find((held) => held.kind === 'binary' && held.localId === localId);
+        return (await store.open()).file(localId, change?.kind === 'binary' ? change.mediaType : '');
+    };
+}
+async function transferBinary(runtime, request, transfer, answer) {
+    const { store, socket, journal } = runtime;
+    const { session } = socket;
+    if (socket.closed() || session.now().refusal !== null)
+        return UNCERTAIN;
+    await socket.firstDiscovery;
+    if (!session.now().roomsNamed)
+        return UNCERTAIN;
+    try {
+        await socket.authorize();
+    }
+    catch {
+        return UNCERTAIN;
+    }
+    const { closed, authorization, refusal } = session.now();
+    if (closed || authorization === undefined || refusal !== null)
+        return UNCERTAIN;
+    const since = store.fences.count();
+    journal.record(`transfer binary ${request.locator} ${request.path}`);
+    try {
+        const result = await transfer(authorization);
+        const settled = result;
+        journal.record(`outcome binary ${settled.kind}`);
+        if (store.fences.since(request.locator, since))
+            return failure({ kind: 'room-not-readable', locator: request.locator });
+        if (settled.kind === 'scoped-refusal') {
+            const room = await store.record(settled.locator);
+            if (room !== undefined)
+                await runtime.scoped(settled, room, await store.open());
+        }
+        if (settled.kind === 'revoked-authorization')
+            await refuse(runtime, 'revoked-authorization');
+        return answer(result);
+    }
+    catch {
+        journal.record('outcome binary transport-uncertainty');
+        return UNCERTAIN;
+    }
+}
+function fetchBinary(runtime, request, name) {
+    const { store, socket } = runtime;
+    return transferBinary(runtime, request, (authorization) => store.opened.fetch(name, () => socket.binary(authorization, request)), binaryAnswer);
+}
+async function readBinary(runtime, request, name) {
+    if (runtime.socket.closed())
+        return UNCERTAIN;
+    const held = await runtime.store.opened.find(name);
+    if (held !== null)
+        return held;
+    return fetchBinary(runtime, request, name);
+}
+async function binaryPath(store, locator, path, revision) {
+    if (revision !== undefined)
+        return { kind: 'path', locator, path, revision };
+    const replica = await store.replica(locator);
+    const local = await store.open();
+    const [held] = replica === undefined ? [] : await local.entries(replica.record.key, 'visible', [path]);
+    const attached = held === undefined ? store.attached.of(locator, path) : undefined;
+    if (attached !== undefined)
+        return { kind: 'path', locator, path, revision: attached.revision };
+    if (replica === undefined || held?.binary === undefined || held.binary === null)
+        return null;
+    if (held.binary.state === 'pending')
+        return { kind: 'pending', localId: held.binary.localId };
+    const record = binaryRecord(path, held.binary, held.revision ?? undefined);
+    if (record.state !== 'accepted')
+        return null;
+    const queued = replica.queue.flatMap((batch) => batch.changes);
+    const sources = queued.flatMap((change) => (change.kind === 'move' ? [change.path] : []));
+    const confirmedLayer = await stepped(slicing(await local.entries(replica.record.key, 'confirmed', [path, ...sources]), [
+        path,
+        ...sources,
+    ]));
+    const holds = (at) => {
+        const kept = confirmedLayer.binaries[at];
+        return (kept?.state === 'accepted' &&
+            kept.sha256 === record.sha256 &&
+            confirmedLayer.revisions[at] === record.revision);
+    };
+    let confirmedAt = path;
+    for (let index = queued.length - 1; index >= 0 && !holds(confirmedAt); index -= 1) {
+        const change = queued[index];
+        if (change.kind === 'move' && change.to === confirmedAt)
+            confirmedAt = change.path;
+    }
+    return {
+        kind: 'path',
+        locator,
+        path: confirmedAt,
+        revision: record.revision,
+    };
+}
+async function askedBinary({ store, socket }, locator, path, revision) {
+    await socket.ready;
+    const drafted = (await store.draft(locator, path))?.parts.file;
+    return drafted !== undefined && drafted.localId === revision
+        ? { kind: 'pending', localId: revision }
+        : binaryPath(store, locator, path, revision);
+}
+async function pendingBinary(store, locator, path, localId) {
+    const facts = await queuedFacts(store, locator, path, localId);
+    return facts === null
+        ? absentBinary(path)
+        : {
+            kind: 'binary',
+            file: localId,
+            byteLength: facts.byteLength,
+            mediaType: facts.mediaType,
+        };
+}
+async function readBinaryPath(runtime, locator, path, revision) {
+    const asked = await askedBinary(runtime, locator, path, revision);
+    if (asked === null)
+        return absentBinary(path);
+    if (asked.kind === 'pending')
+        return pendingBinary(runtime.store, locator, path, asked.localId);
+    return readBinary(runtime, asked, { locator, path: asked.path, revision: asked.revision });
+}
+async function heldMediaType(store, locator, path) {
+    const replica = await store.record(locator);
+    const [held] = replica === undefined ? [] : await (await store.open()).entries(replica.key, 'visible', [path]);
+    return held === undefined ? store.attached.of(locator, path)?.mediaType : held.binary?.mediaType;
+}
+function linkOf(runtime, asked, held) {
+    return transferBinary(runtime, asked, (authorization) => runtime.socket.link(authorization, asked), (result) => binaryLinkAnswer(result, held));
+}
+async function linkBinaryPath(runtime, locator, path, revision) {
+    const { store, socket } = runtime;
+    await socket.ready;
+    const asked = await binaryPath(store, locator, path, revision);
+    if (asked === null || asked.kind === 'pending')
+        return absentBinary(path);
+    return linkOf(runtime, asked, revision === undefined ? await heldMediaType(store, locator, path) : undefined);
+}
+async function showBinaryPath(runtime, locator, path, revision) {
+    const { store } = runtime;
+    const asked = await askedBinary(runtime, locator, path, revision);
+    if (asked === null)
+        return absentBinary(path);
+    if (asked.kind === 'pending')
+        return pendingBinary(store, locator, path, asked.localId);
+    if (runtime.socket.closed())
+        return UNCERTAIN;
+    const name = { locator, path: asked.path, revision: asked.revision };
+    const kept = await store.opened.find(name);
+    if (kept !== null)
+        return kept;
+    const mediaType = await heldMediaType(store, locator, path);
+    if (mediaType?.startsWith('image/') === true)
+        return fetchBinary(runtime, asked, name);
+    return linkOf(runtime, asked, revision === undefined ? mediaType : undefined);
+}
+async function attachBinary(runtime, locator, file) {
+    const { store, socket } = runtime;
+    await socket.ready;
+    await socket.firstDiscovery;
+    if (socket.closed() ||
+        !socket.session.now().roomsNamed ||
+        (await connectionNow(runtime)) === 'unreachable' ||
+        socket.session.now().refusal !== null)
+        return OFFLINE;
+    const request = await attachedFile(locator, file);
+    return transferBinary(runtime, { locator, path: file.name }, async (held) => {
+        const result = await socket.attach(held, request);
+        if (result.kind === 'attached') {
+            store.attached.hold(locator, result.path, {
+                revision: result.revision,
+                mediaType: request.mediaType,
+            });
+        }
+        return result;
+    }, attachAnswer);
+}
+export function binaryFileSurface(runtime) {
+    return {
+        part: runtime.store.part,
+        read: (room, path, revision) => readBinaryPath(runtime, room, path, revision),
+        link: (room, path, revision) => linkBinaryPath(runtime, room, path, revision),
+        show: (room, path, revision) => showBinaryPath(runtime, room, path, revision),
+        attach: (room, file) => attachBinary(runtime, room, file),
+    };
+}