@agentshouse/mdruntime 0.1.0-cd50a4607cb7d → 0.1.0-cd76160689224

package/dist/connection.js

@@ -1,8 +1,9 @@
 import { attachedModel } from './attached-model.js';
 import { cached, modelTypes, NO_MODEL, sameModel, } from './model.js';
-import { observing } from './observation.js';
-import { filterOf, identityOf, planOf, } from './query.js';
+import { observing, whole } from './observation.js';
+import { filterOf, identityOf, planOf, queryKey, } from './query.js';
 import { createReadSide } from './read-side.js';
+import { seededResult } from './seed.js';
 import { markdownPath, roomOfKey } from './rows.js';
 import { createSearchIndex, searchPlanOf, } from './search.js';
 import { bootstrapRoom } from './bootstrap.js';
@@ -13,14 +14,17 @@ import { indexReferrers, referencesIndexed, validRoot, } from './collection.js';
 import { runtimeError } from './failure.js';
 import { createLog } from './log.js';
 import { binaryRecord } from './binary.js';
-import { absentBinary, binaryAnswer, calledResult, failure, historyAnswer, undeclared, UNCERTAIN, } from './outcome.js';
+import { absentBinary, binaryAnswer, binaryLinkAnswer, calledResult, failure, historyAnswer, undeclared, UNCERTAIN, } from './outcome.js';
 import { createRecovery } from './recovery.js';
+import { doorReads } from './reads.js';
 import { refreshRoom } from './refresh.js';
 import { buildBatch, joined, limitedIn, requeued } from './save.js';
 import { applyReturned, compositionOf, confirmedOf, landed, readReclassified, replicaOf, sameMembership, withdrawals, } from './replica.js';
 import { binaryBase, changedParts, changesOf, held, heldFile, joinedDraft, readParts, returnedBy, returnedInto, staleWrite, underneath, withdrawnDrafts, } from './room-draft.js';
 import { same, saving, STARTING, transferring, } from './status.js';
 import { detectStorageLoss, nextGeneration } from './durability.js';
+import { demanded, narrower, WHOLE_DEMAND, wider } from './acquisition.js';
+import { readinessOf, SETTLED_ROOMS, } from './readiness.js';
 import { FencedMap } from './fence.js';
 import { tally } from './shared.js';
 import { inChunks, ROW_WEIGHT, yielded } from './turn.js';
@@ -29,6 +33,14 @@ import { beneath, normalize } from './paths.js';
 import { openRuntimeStore, } from './store.js';
 import { unconfirmed } from './transfer.js';
 import { governs, holds, narrowed, planReach, } from './reach.js';
+function roomsAlone(plan) {
+    return (plan.reach === null &&
+        plan.root.types === null &&
+        plan.root.where === null &&
+        plan.root.pathPrefix === null &&
+        plan.hop === null &&
+        plan.backlinks === null);
+}
 function within(root, path) {
     return root === '' || beneath(root, path);
 }
@@ -46,6 +58,10 @@ const OPENING_LANE = 'opening';
 const CONVERSATION_LANE = 'conversations';
 const ROOM_READS = 256;
 const ROOM_ATTEMPTS = 16;
+function operationOf(input) {
+    const operation = input?.operation_id;
+    return typeof operation === 'string' ? operation : null;
+}
 const outside = new Map();
 function outsideOf(roots) {
     const key = JSON.stringify(roots);
@@ -85,6 +101,8 @@ export function composeRuntime(options) {
     const replicas = new FencedMap(isFenced);
     const queuesWithoutReplica = new FencedMap(isFenced);
     const pendings = new Map();
+    const seeds = new Map();
+    const seedWatchers = new Map();
     const roomDrafts = new FencedMap(isFenced);
     const presentations = new Map();
     let limits = [];
@@ -97,6 +115,7 @@ export function composeRuntime(options) {
     const liveModels = new FencedMap(isModelFenced);
     const invalidModels = new Set();
     const discovered = new Map();
+    const reads = doorReads(options.adapter, (locator) => discovered.get(locator), () => generation);
     let roomsListed = false;
     const scopedRefusals = new Map();
     const sourceRefusals = new Map();
@@ -133,6 +152,7 @@ export function composeRuntime(options) {
     let handed = false;
     const recovery = (options.recovery ?? createRecovery()).scope(ROOM_ATTEMPTS);
     const repairing = new Set();
+    const calling = new Set();
     const repairable = new Map();
     let outcomeRetention = null;
     const answering = new Map();
@@ -166,8 +186,18 @@ export function composeRuntime(options) {
     const memberListeners = new Set();
     const prepared = new Set();
     const projecting = new Set();
-    const demanded = new Set();
+    const unpreparedDemand = new Set();
+    const unindexable = new Set();
     let preparing = false;
+    let demand = WHOLE_DEMAND;
+    let narrowing = null;
+    let targets = {};
+    let persistence = options.shell.persistence;
+    let capacity = null;
+    const paused = new Set();
+    let rechecking = null;
+    const readinessWatches = new Set();
+    let readinessQueued = false;
     const catching = new Set();
     const transfers = new FencedMap(isFenced);
     const conversations = createConversationStore({
@@ -325,15 +355,18 @@ export function composeRuntime(options) {
     }
     function emitRooms() {
         readSide.recover();
+        queueReadiness();
         const value = listed();
         for (const listener of roomListeners)
             listener(value);
     }
     function emitRefusal() {
+        queueReadiness();
         for (const listener of refusalListeners)
             listener(refusal);
     }
     function emitStorageLoss() {
+        queueReadiness();
         for (const listener of storageLossListeners)
             listener(storageLoss);
     }
@@ -350,7 +383,8 @@ export function composeRuntime(options) {
     function show() {
         if (closed)
             return;
-        const next = status.state === 'synced' && !conversations.current()
+        queueReadiness();
+        const next = status.state === 'synced' && demand.conversations && !conversations.current()
             ? { ...status, state: 'syncing' }
             : status;
         if (same(shown, next))
@@ -427,13 +461,19 @@ export function composeRuntime(options) {
         }
         conversations.changed(mergeChangeSets(entered));
         readSide.recover();
+        queueReadiness();
     }
     function unprepared() {
-        return [...demanded, ...replicas.keys()].find((locator) => !prepared.has(locator));
+        return [...unpreparedDemand, ...replicas.keys()].find((locator) => !prepared.has(locator) && !unindexable.has(locator));
+    }
+    function unbuilt(locator, error) {
+        unindexable.add(locator);
+        journal.record(`index failed ${locator} ${error instanceof Error ? error.name : 'unknown'}`);
+        queueReadiness();
     }
     function prepare(locators = []) {
         for (const locator of locators)
-            demanded.add(locator);
+            unpreparedDemand.add(locator);
         if (preparing)
             return;
         preparing = true;
@@ -443,8 +483,8 @@ export function composeRuntime(options) {
                     await yielded();
                     if (closed)
                         return;
-                    demanded.delete(waiting);
-                    await prepareReplica(waiting);
+                    unpreparedDemand.delete(waiting);
+                    await prepareReplica(waiting).catch((error) => unbuilt(waiting, error));
                 }
             }
             finally {
@@ -462,7 +502,8 @@ export function composeRuntime(options) {
         return [...new Set(named)].filter((locator) => reached === null || reached.has(locator)).sort();
     }
     function awaited(locator) {
-        return rooms.has(locator) || !roomsListed;
+        return (!roomsListed ||
+            (rooms.has(locator) && discovered.get(locator)?.replica.admission === 'admitted'));
     }
     function covered(plan) {
         const locators = reachedRooms(plan);
@@ -502,9 +543,332 @@ export function composeRuntime(options) {
         if (waiting.length > 0)
             prepare(waiting.map(({ room }) => room));
     }
+    function acquires(room) {
+        return (demanded(demand, room) ||
+            (replicas.get(room.locator)?.queue.length ?? 0) > 0 ||
+            queuesWithoutReplica.has(room.locator));
+    }
+    function acquiredLocators() {
+        return [...discovered.values()]
+            .filter(acquires)
+            .map((room) => room.locator)
+            .sort();
+    }
+    function heldLocators(acquired) {
+        return demand.whole ? acquired : [...new Set([...acquired, ...demand.rooms])].sort();
+    }
+    function heldDemand(acquired) {
+        if (demand.whole)
+            return null;
+        return {
+            rooms: heldLocators(acquired.map((room) => room.locator)),
+            conversations: demand.conversations,
+        };
+    }
+    function applyDemand(next) {
+        const before = heldLocators(acquiredLocators());
+        const { whole, conversations: conversed } = demand;
+        demand = next;
+        const after = heldLocators(acquiredLocators());
+        queueReadiness();
+        if (!conversed && next.conversations)
+            scheduleCurrency();
+        if (JSON.stringify(before) === JSON.stringify(after) &&
+            whole === next.whole &&
+            conversed === next.conversations)
+            return;
+        journal.record(`acquisition ${next.whole ? 'whole' : after.length}`);
+        if (options.adapter.roomStream === undefined)
+            void sync('unstreamed');
+        else if (socketOpen)
+            options.adapter.roomStream.reopen();
+    }
+    function acquire(next) {
+        if (closed)
+            return;
+        if (narrowing !== null)
+            clearTimeout(narrowing);
+        narrowing = null;
+        const widening = wider(next, demand);
+        if (!widening && !narrower(next, demand))
+            return;
+        if (widening || !roomsListed) {
+            applyDemand(next);
+            return;
+        }
+        // A narrower demand waits five seconds, so a tab that reloads returns before the stream reopens twice.
+        narrowing = setTimeout(() => {
+            narrowing = null;
+            applyDemand(next);
+        }, 5_000);
+    }
+    function requiredRooms(reach) {
+        if (reach === null)
+            return { listed: roomsListed, rooms: [...rooms.keys()].sort() };
+        const named = [...new Set(reach.rooms)].sort();
+        if (roomsListed)
+            return { listed: true, rooms: named.filter((room) => rooms.has(room)) };
+        return { listed: named.every((room) => replicas.has(room)), rooms: named };
+    }
+    function roomState(locator, search) {
+        if (sourceRefusals.has(locator))
+            return 'refused';
+        const listedRoom = discovered.get(locator);
+        if (roomsListed &&
+            (listedRoom === undefined ||
+                listedRoom.replica.admission !== 'admitted' ||
+                unreadable.has(locator)))
+            return 'unadmitted';
+        if (!replicas.has(locator))
+            return 'acquiring';
+        if (!prepared.has(locator))
+            return 'preparing';
+        if (search && !searchIndex.rooms().has(locator))
+            return 'indexing';
+        return 'complete';
+    }
+    function conversationCoverage(reach, search) {
+        const declared = reach === null || reach.conversations;
+        if (!declared || options.adapter.conversations === undefined || declaredAgents() === undefined)
+            return 'undeclared';
+        if (!conversations.known() || !conversations.current())
+            return 'acquiring';
+        if (!search)
+            return 'complete';
+        const unindexed = conversations
+            .searchable()
+            .filter((one) => conversations.acquired(one) && !searchIndex.conversations().has(one));
+        if (unindexed.length === 0)
+            return 'complete';
+        index([], unindexed);
+        return 'indexing';
+    }
+    function connectionOf() {
+        if (socketOpen)
+            return 'connected';
+        if (status.providerUnreachable)
+            return 'unreachable';
+        return options.adapter.roomStream === undefined && status.lastCompleted !== null
+            ? 'connected'
+            : 'connecting';
+    }
+    function refusedIn(locators) {
+        return locators.flatMap((room) => {
+            const held = sourceRefusals.get(room);
+            if (held === undefined)
+                return [];
+            const { file, location } = held.fields;
+            return [
+                {
+                    room,
+                    file: typeof file === 'string' ? file : '',
+                    rule: held.code,
+                    location: typeof location === 'string' ? location : null,
+                },
+            ];
+        });
+    }
+    function readinessFor(port, reach) {
+        const required = requiredRooms(reach);
+        const search = port.search === 'required';
+        const coverage = required.rooms.map((room) => ({ room, state: roomState(room, search) }));
+        const building = (state) => coverage
+            .filter((room) => room.state === state && !unindexable.has(room.room))
+            .map(({ room }) => room);
+        const preparing = building('preparing');
+        if (preparing.length > 0)
+            prepare(preparing);
+        const indexing = building('indexing');
+        if (indexing.length > 0)
+            index(indexing, []);
+        return readinessOf({
+            code: port.code,
+            coverage: {
+                listed: required.listed,
+                rooms: coverage,
+                conversations: conversationCoverage(reach, search),
+                search: search ? 'required' : 'unused',
+            },
+            persistence,
+            connection: connectionOf(),
+            house: refusal !== null ? 'refused' : writesHeld() ? 'write-halted' : 'open',
+            capacity: capacity !== null &&
+                coverage.some(({ room, state }) => paused.has(room) || !SETTLED_ROOMS.has(state))
+                ? capacity
+                : port.capacity,
+            refused: refusedIn(required.rooms),
+            lost: storageLoss !== null,
+            established: targets[port.target]?.established === true,
+        });
+    }
+    function establish(name) {
+        targets = { ...targets, [name]: { established: true } };
+        queueReadiness();
+        void durably((local) => local.keepTargets(targets)).catch(() => {
+            journal.record(`target record failed ${name}`);
+        });
+    }
+    function deliverReadiness(watch) {
+        if (!readinessWatches.has(watch))
+            return;
+        const readiness = readinessFor(watch.port, watch.reach);
+        if (readiness.ready && targets[watch.port.target]?.established !== true) {
+            establish(watch.port.target);
+        }
+        const shown = JSON.stringify(readiness);
+        if (shown === watch.last)
+            return;
+        watch.last = shown;
+        watch.deliver(structuredClone(readiness));
+    }
+    function queueReadiness() {
+        if (readinessQueued || closed || readinessWatches.size === 0)
+            return;
+        readinessQueued = true;
+        queueMicrotask(() => {
+            readinessQueued = false;
+            if (closed)
+                return;
+            for (const watch of [...readinessWatches])
+                deliverReadiness(watch);
+        });
+    }
+    function watchReadiness(port, reach, deliver) {
+        const watch = { port, reach, deliver, last: null };
+        readinessWatches.add(watch);
+        void openLocal().then(() => deliverReadiness(watch), () => deliverReadiness(watch));
+        return () => {
+            readinessWatches.delete(watch);
+        };
+    }
+    function layerBytes(layer) {
+        let bytes = 0;
+        for (const [path, text] of Object.entries(layer.documents))
+            bytes += (path.length + text.length) * 2;
+        return bytes;
+    }
+    function grownBy(next, previous) {
+        if (previous === undefined)
+            return layerBytes(next);
+        const documents = Object.fromEntries(Object.entries(next.documents).filter(([path, text]) => previous.documents[path] !== text));
+        return layerBytes({ ...next, documents });
+    }
+    function exceeded(error) {
+        return (typeof error === 'object' &&
+            error !== null &&
+            error.name === 'QuotaExceededError');
+    }
+    async function estimated() {
+        const estimate = options.shell.estimate === undefined ? null : await options.shell.estimate();
+        return estimate === null ? null : Math.max(0, estimate.quota - estimate.usage);
+    }
+    function pause(locator, cause) {
+        paused.add(locator);
+        capacity = cause;
+        journal.record(`capacity ${cause.cause} ${locator} ${cause.needed} ${cause.available ?? '-'}`);
+        queueReadiness();
+        if (rechecking !== null)
+            return;
+        // A paused preparation measures the browser's space again each minute, so space freed elsewhere resumes it without a retry.
+        rechecking = setInterval(() => {
+            void recheck();
+        }, 60_000);
+    }
+    async function recheck() {
+        const held = capacity;
+        if (held === null || closed)
+            return;
+        const available = await estimated().catch(() => null);
+        if (available === null || available < (held.needed ?? 0))
+            return;
+        if (held.cause === 'quota-exceeded' && (held.available === null || available <= held.available))
+            return;
+        resume();
+    }
+    function resume() {
+        if (rechecking !== null)
+            clearInterval(rechecking);
+        rechecking = null;
+        if (paused.size === 0 && capacity === null)
+            return;
+        paused.clear();
+        capacity = null;
+        journal.record('capacity resumed');
+        queueReadiness();
+        if (!closed && authorization !== undefined)
+            void sync('unstreamed');
+    }
+    async function reclaimed(local) {
+        const unreferenced = [...transfers.keys()].filter((locator) => {
+            const room = discovered.get(locator);
+            return room === undefined || !acquires(room);
+        });
+        for (const locator of unreferenced) {
+            await local.abandon(locator);
+            transfers.delete(locator);
+        }
+        if (unreferenced.length > 0)
+            journal.record(`capacity reclaimed ${unreferenced.length}`);
+        return unreferenced.length > 0;
+    }
+    async function admitted(local, locator, needed) {
+        if (paused.has(locator))
+            return false;
+        let available = await estimated().catch(() => null);
+        if (available === null || available >= needed)
+            return true;
+        if (await reclaimed(local))
+            available = await estimated().catch(() => null);
+        if (available === null || available >= needed)
+            return true;
+        pause(locator, { cause: 'insufficient-space', needed, available });
+        return false;
+    }
+    async function exceededOn(locator, bytes) {
+        const available = await estimated().catch(() => null);
+        pause(locator, { cause: 'quota-exceeded', needed: bytes, available });
+    }
+    function seedRoomHeld(room, version) {
+        return prepared.has(room) && reachedBy(room, version);
+    }
+    function seedHeld(at) {
+        return Object.entries(at).every(([room, version]) => (roomsListed && !rooms.has(room)) || seedRoomHeld(room, version));
+    }
+    function seedApplies(plan) {
+        const seed = seeds.get(plan.key);
+        if (seed === undefined)
+            return null;
+        if (!seedHeld(seed.at))
+            return seed;
+        seeds.delete(plan.key);
+        return null;
+    }
+    function seedBehind(plan, cover) {
+        const seed = seedApplies(plan);
+        if (seed === null || 'pending' in cover)
+            return cover;
+        return {
+            pending: Object.entries(seed.at)
+                .filter(([room, version]) => !seedRoomHeld(room, version))
+                .map(([room]) => ({ room, awaits: 'acquisition' })),
+        };
+    }
+    function seed(entry) {
+        if (seedHeld(entry.at))
+            return;
+        for (const { query, rows } of entry.queries) {
+            const key = queryKey(query);
+            seeds.set(key, { rows, at: entry.at });
+            for (const shown of seedWatchers.get(key) ?? [])
+                shown();
+        }
+    }
     async function rowsQuery(plan) {
         const before = covered(plan);
         awaitPreparation(before);
+        const seeded = seedApplies(plan);
+        if (seeded !== null)
+            return seededResult(seeded).result;
         if ('pending' in before)
             return before;
         const { rows, at: cover } = await readSide.query(plan, () => covered(plan));
@@ -529,10 +893,12 @@ export function composeRuntime(options) {
         }
     }
     function indexNext() {
-        const room = [...roomsToIndex].find((locator) => !searchIndex.rooms().has(locator));
+        const room = [...roomsToIndex].find((locator) => !searchIndex.rooms().has(locator) && !unindexable.has(locator));
         if (room !== undefined) {
             roomsToIndex.delete(room);
-            return () => (prepared.has(room) ? searchIndex.indexRoom(room) : undefined);
+            return () => prepared.has(room)
+                ? searchIndex.indexRoom(room).catch((error) => unbuilt(room, error))
+                : undefined;
         }
         const conversation = [...conversationsToIndex].find((one) => !searchIndex.conversations().has(one));
         if (conversation === undefined)
@@ -553,6 +919,7 @@ export function composeRuntime(options) {
                 for (let unit = indexNext(); unit !== null && !closed; unit = indexNext()) {
                     await yielded();
                     await unit();
+                    queueReadiness();
                 }
             }
             finally {
@@ -660,6 +1027,9 @@ export function composeRuntime(options) {
             if (fence !== undefined && fence.erased && fence.at < started)
                 fences.delete(room.locator);
         }
+        await loseRooms(found
+            .filter((room) => room.replica.admission !== 'admitted' && heldLocally(room.locator))
+            .map((room) => room.locator));
         const listed = found.filter((room) => !fences.has(room.locator));
         const listedLocators = new Set(listed.map((room) => room.locator));
         for (const locator of listedLocators)
@@ -684,6 +1054,12 @@ export function composeRuntime(options) {
         emitRooms();
         return listed;
     }
+    function heldLocally(locator) {
+        return (replicas.has(locator) ||
+            roomDrafts.has(locator) ||
+            transfers.has(locator) ||
+            queuesWithoutReplica.has(locator));
+    }
     function unlistedHeld(listed) {
         return [
             ...new Set([
@@ -726,6 +1102,8 @@ export function composeRuntime(options) {
             unreadable.delete(locator);
             stale.delete(locator);
             repairable.delete(locator);
+            unindexable.delete(locator);
+            paused.delete(locator);
             scopedRefusals.delete(locator);
             sourceRefusals.delete(locator);
             declarationRefusals.delete(locator);
@@ -779,7 +1157,7 @@ export function composeRuntime(options) {
         return model;
     }
     async function hydrate(opened) {
-        const [records, queues, kept, presented, held, chatDrafts, lastCompleted, declared, named, known, staged,] = await Promise.all([
+        const [records, queues, kept, presented, held, chatDrafts, lastCompleted, declared, named, known, staged, heldTargets,] = await Promise.all([
             opened.all(),
             opened.queues(),
             opened.roomDrafts(),
@@ -791,7 +1169,9 @@ export function composeRuntime(options) {
             opened.capabilities(),
             opened.member(),
             opened.transfers(),
+            opened.targets(),
         ]);
+        targets = heldTargets;
         transfers.clear();
         for (const record of staged)
             transfers.set(record.locator, record);
@@ -1037,7 +1417,18 @@ export function composeRuntime(options) {
                 const accepted = pendings.get(batch.id)?.accepted;
                 return (accepted !== undefined && options.adapter.reached(room.locator, roomVersion, accepted));
             });
-            const set = (await settle(local, room.locator, prior, confirmed, queue.filter((batch) => !accepted.includes(batch)), { room: true, ...(stored === undefined ? {} : { stored }) }))();
+            let settled;
+            try {
+                settled = await settle(local, room.locator, prior, confirmed, queue.filter((batch) => !accepted.includes(batch)), { room: true, ...(stored === undefined ? {} : { stored }) });
+            }
+            catch (error) {
+                if (!exceeded(error))
+                    throw error;
+                await exceededOn(room.locator, grownBy(confirmed.record, prior?.confirmed.record));
+                caughtUpTo(room.locator);
+                return true;
+            }
+            const set = settled();
             if (stored !== undefined) {
                 transfers.delete(room.locator);
                 catching.delete(room.locator);
@@ -1045,6 +1436,7 @@ export function composeRuntime(options) {
             for (const batch of accepted)
                 pendings.delete(batch.id);
             stale.delete(room.locator);
+            unindexable.delete(room.locator);
             if (unreadable.delete(room.locator))
                 scopedRefusals.delete(room.locator);
             sourceRefusals.delete(room.locator);
@@ -1288,7 +1680,7 @@ export function composeRuntime(options) {
         const scope = options.adapter.referrerScope(request.referrer);
         return scope?.kind === 'room' ? scope.locator : null;
     }
-    async function readBinary(request) {
+    async function transferBinary(request, transfer, answer) {
         if (closed || refusal !== null)
             return UNCERTAIN;
         try {
@@ -1304,40 +1696,41 @@ export function composeRuntime(options) {
             ? `transfer binary ${request.locator} ${request.path}`
             : `transfer binary ${request.fileRef}`);
         try {
-            const result = await options.adapter.binary(authorization, request);
-            journal.record(`outcome binary ${result.kind}`);
+            const result = await transfer(authorization);
+            const settled = result;
+            journal.record(`outcome binary ${settled.kind}`);
             const locator = binaryRoom(request);
             if (locator !== null && fencedSince(locator, since))
                 return failure({ kind: 'room-not-readable', locator });
-            if (result.kind === 'scoped-refusal') {
-                const room = replicas.get(result.locator)?.confirmed.record;
+            if (settled.kind === 'scoped-refusal') {
+                const room = replicas.get(settled.locator)?.confirmed.record;
                 if (room !== undefined)
-                    await scoped(result, room, await openLocal());
+                    await scoped(settled, room, await openLocal());
             }
-            if (result.kind === 'revoked-authorization')
+            if (settled.kind === 'revoked-authorization')
                 await refuse('revoked-authorization');
-            return binaryAnswer(result);
+            return answer(result);
         }
         catch {
             journal.record('outcome binary transport-uncertainty');
             return UNCERTAIN;
         }
     }
-    async function readBinaryPath(locator, path, revision) {
-        await ready;
+    function readBinary(request) {
+        return transferBinary(request, (held) => options.adapter.binary(held, request), binaryAnswer);
+    }
+    function binaryPath(locator, path, revision) {
         if (revision !== undefined)
-            return readBinary({ kind: 'path', locator, path, revision });
+            return { kind: 'path', locator, path, revision };
         const visible = replicas.get(locator)?.visible;
         const held = visible?.binaries[path];
         if (visible === undefined || held === undefined)
-            return absentBinary(path);
-        if (held.state === 'pending') {
-            const blob = queuedBlob(locator, path, held.localId);
-            return blob === null ? absentBinary(path) : { kind: 'binary', blob };
-        }
+            return null;
+        if (held.state === 'pending')
+            return { kind: 'pending', localId: held.localId };
         const record = binaryRecord(path, held, visible.revisions[path]);
         if (record.state !== 'accepted')
-            return absentBinary(path);
+            return null;
         const replica = replicas.get(locator);
         const queued = (replica?.queue ?? []).flatMap((batch) => batch.changes);
         const holds = (at) => {
@@ -1352,13 +1745,31 @@ export function composeRuntime(options) {
             if (change.kind === 'move' && change.to === confirmed)
                 confirmed = change.path;
         }
-        return readBinary({
+        return {
             kind: 'path',
             locator,
             path: confirmed,
             revision: record.revision,
             fileRef: record.fileRef,
-        });
+        };
+    }
+    async function readBinaryPath(locator, path, revision) {
+        await ready;
+        const asked = binaryPath(locator, path, revision);
+        if (asked === null)
+            return absentBinary(path);
+        if (asked.kind === 'pending') {
+            const blob = queuedBlob(locator, path, asked.localId);
+            return blob === null ? absentBinary(path) : { kind: 'binary', blob };
+        }
+        return readBinary(asked);
+    }
+    async function linkBinaryPath(locator, path, revision) {
+        await ready;
+        const asked = binaryPath(locator, path, revision);
+        if (asked === null || asked.kind === 'pending')
+            return absentBinary(path);
+        return transferBinary(asked, (held) => options.adapter.link(held, asked), binaryLinkAnswer);
     }
     async function readBinaryReference(reference) {
         await ready;
@@ -1384,7 +1795,7 @@ export function composeRuntime(options) {
         }
         return undefined;
     }
-    async function invokeAction(name, input) {
+    async function invokeAction(name, input, dispatching) {
         await ready;
         if (closed || refusal !== null)
             return UNCERTAIN;
@@ -1398,6 +1809,7 @@ export function composeRuntime(options) {
         }
         if (closed || authorization === undefined || refusal !== null)
             return UNCERTAIN;
+        await dispatching?.();
         journal.record(`transfer action ${name}`);
         try {
             const result = await options.adapter.action(authorization, { name, input });
@@ -1418,6 +1830,60 @@ export function composeRuntime(options) {
             return UNCERTAIN;
         }
     }
+    function unsettled(result) {
+        return result.kind !== 'action' && result.retryable;
+    }
+    async function recoveredAction(name, input) {
+        const operation = operationOf(input);
+        if (operation === null)
+            return invokeAction(name, input);
+        const kept = async () => (await openLocal()).keepCall({ operation, name, input });
+        calling.add(operation);
+        try {
+            let result = await invokeAction(name, input, kept);
+            if (unsettled(result)) {
+                await recovery.attempt(`action ${operation}`, async () => {
+                    if (closed || refusal !== null)
+                        return 'done';
+                    if (!socketOpen)
+                        return 'again';
+                    result = await invokeAction(name, input, kept);
+                    return unsettled(result) ? 'again' : 'done';
+                }, { again: true });
+            }
+            if (!unsettled(result))
+                await (await openLocal()).dropCall(operation);
+            return result;
+        }
+        finally {
+            calling.delete(operation);
+        }
+    }
+    async function resendCalls(signal) {
+        if (!socketOpen || closed || stopping)
+            return 'done';
+        const local = await openLocal();
+        for (const held of await local.calls()) {
+            if (calling.has(held.operation))
+                continue;
+            if (closed || signal.aborted)
+                return 'done';
+            if (pastHorizon(held.operation)) {
+                await local.dropCall(held.operation);
+                continue;
+            }
+            calling.add(held.operation);
+            try {
+                if (unsettled(await invokeAction(held.name, held.input)))
+                    return 'again';
+                await local.dropCall(held.operation);
+            }
+            finally {
+                calling.delete(held.operation);
+            }
+        }
+        return 'done';
+    }
     function continuing() {
         return !closed && !discoveryPaused;
     }
@@ -1435,8 +1901,9 @@ export function composeRuntime(options) {
     async function pullRefresh(authorized, confirmed, live) {
         if (!live())
             return unconfirmed;
+        const turn = generation;
         try {
-            const result = await refreshRoom(options.adapter, authorized, confirmed, (models, held) => (live() ? remodel(confirmed.record.locator, models, held) : held), live);
+            const result = await refreshRoom(reads, authorized, confirmed, (models, held) => (live() ? remodel(confirmed.record.locator, models, held) : held), live);
             const detail = result.kind === 'advanced' ? result.confirmed.record.roomVersion : result.kind;
             journal.record(`transfer refresh ${confirmed.record.locator} ${detail}`);
             return result;
@@ -1445,6 +1912,9 @@ export function composeRuntime(options) {
             journal.record(`transfer refresh ${confirmed.record.locator} transport-uncertainty`);
             throw error;
         }
+        finally {
+            reads.finished(confirmed.record.locator, turn);
+        }
     }
     function staging(local, live) {
         return {
@@ -1453,7 +1923,18 @@ export function composeRuntime(options) {
             stage: (record, page) => exclusive(async () => {
                 if (!live())
                     return false;
-                await local.stage(record, page);
+                const bytes = layerBytes(page);
+                if (!(await admitted(local, record.locator, bytes)))
+                    return false;
+                try {
+                    await local.stage(record, page);
+                }
+                catch (error) {
+                    if (!exceeded(error))
+                        throw error;
+                    await exceededOn(record.locator, bytes);
+                    return false;
+                }
                 transfers.set(record.locator, record);
                 readSide.recover();
                 return true;
@@ -1476,12 +1957,13 @@ export function composeRuntime(options) {
     async function pullBootstrap(authorized, room, local, live) {
         if (!live())
             return unconfirmed;
+        const turn = generation;
         if (replicas.has(room.locator)) {
             catching.add(room.locator);
             readSide.recover();
         }
         try {
-            const result = await bootstrapRoom(options.adapter, authorized, room, {
+            const result = await bootstrapRoom(reads, authorized, room, {
                 collection: modelOf(room.locator),
                 selection: modelOf(room.locator, 'typed-selection'),
             }, (models, held) => (live() ? remodel(room.locator, models, held) : held), live, staging(local, live), reusable(room));
@@ -1496,14 +1978,30 @@ export function composeRuntime(options) {
             caughtUpTo(room.locator);
             throw error;
         }
+        finally {
+            reads.finished(room.locator, turn);
+        }
     }
     function caughtUpTo(locator) {
         if (catching.delete(locator))
             readSide.recover();
     }
+    function behind(room) {
+        const held = replicas.get(room.locator)?.confirmed.record.roomVersion;
+        return (held !== undefined &&
+            [announced.get(room.locator), room.roomVersion].some((later) => later !== undefined && !options.adapter.reached(room.locator, held, later)));
+    }
     async function advance(room, local, authorized, live) {
+        const carried = reads.carried(room.locator);
+        const withheld = await advanceOnce(room, local, authorized, live);
+        if (withheld !== null || reads.carried(room.locator) === carried || !behind(room)) {
+            return withheld;
+        }
+        return advanceOnce(room, local, authorized, live);
+    }
+    async function advanceOnce(room, local, authorized, live) {
         await referenced(room.locator);
-        if (!live())
+        if (!live() || paused.has(room.locator))
             return unconfirmed;
         const held = replicas.get(room.locator);
         if (held !== undefined) {
@@ -1938,6 +2436,11 @@ export function composeRuntime(options) {
         });
     }
     async function scoped(result, room, local) {
+        if ((result.scope === 'content' || result.scope === 'sync') && !result.retryable) {
+            journal.record(`scoped refusal ${room.locator} ${result.scope} ${result.code}`);
+            await loseRooms([room.locator]);
+            return;
+        }
         scopedRefusals.set(room.locator, {
             code: result.code,
             fields: result.fields,
@@ -1984,15 +2487,16 @@ export function composeRuntime(options) {
         });
     }
     async function synchronize(listed, local, progress, attempt, live) {
-        const prepared = await Promise.allSettled(listed.map((room) => prepareRoom(room, local, progress)));
+        const acquired = listed.filter(acquires);
+        const prepared = await Promise.allSettled(acquired.map((room) => prepareRoom(room, local, progress)));
         if (!live())
             return;
-        const ready = listed.filter((_, index) => {
+        const ready = acquired.filter((_, index) => {
             const outcome = prepared[index];
             return outcome?.status === 'fulfilled' && outcome.value;
         });
         if (attempt === 'opened') {
-            options.adapter.roomStream?.hold(heldRooms(ready));
+            options.adapter.roomStream?.hold(heldRooms(ready), heldDemand(acquired));
             handed = true;
         }
         discovering?.release();
@@ -2020,19 +2524,10 @@ export function composeRuntime(options) {
             await retainModel(local, room, 'collection', modelOf(room.locator));
         if (discoveryPaused || authorization === undefined)
             return false;
-        if (room.replica.admission !== 'admitted') {
-            if (replicas.has(room.locator))
-                progress.complete = false;
-            return false;
-        }
-        return true;
+        return room.replica.admission === 'admitted';
     }
     async function caughtUp(room, local, progress, live) {
-        const held = replicas.get(room.locator)?.confirmed.record.roomVersion;
-        if (held === undefined || authorization === undefined || !live())
-            return;
-        const behind = [announced.get(room.locator), room.roomVersion].some((later) => later !== undefined && !options.adapter.reached(room.locator, held, later));
-        if (!behind)
+        if (authorization === undefined || !live() || !behind(room))
             return;
         const withheld = await advance(room, local, authorization, live);
         if (withheld !== null)
@@ -2260,9 +2755,43 @@ export function composeRuntime(options) {
             options.adapter.roomStream?.reopen();
         });
     }
-    function closedSocket(revoked) {
+    function rediscover() {
+        return task(OPENING_LANE, async (live) => {
+            if (!live() || !socketOpen)
+                return;
+            const progress = { complete: true, reachable: true };
+            const gate = discover();
+            moveTo(transferring(status));
+            try {
+                const local = await openLocal();
+                if (!live())
+                    return;
+                await ensureAuthorization();
+                if (!live())
+                    return;
+                await discoverRooms(local, progress, 'authorized', live);
+            }
+            catch {
+                progress.complete = false;
+            }
+            finally {
+                gate.release();
+                notifyReady();
+            }
+            if (!live())
+                return;
+            if (!progress.complete)
+                complete = false;
+            await rest(progress, live);
+        });
+    }
+    function closedSocket(revoked, lost) {
         const opened = socketOpen;
         socketOpen = false;
+        if (lost) {
+            reads.lost();
+            conversations.lost();
+        }
         if (revoked) {
             void refuse('revoked-authorization');
             return;
@@ -2449,6 +2978,7 @@ export function composeRuntime(options) {
                 progress.complete = false;
                 return;
             }
+            reads.applied();
             submitAll();
             for (const locator of stale)
                 if (repairable.has(locator))
@@ -2457,9 +2987,12 @@ export function composeRuntime(options) {
             if (status.providerUnreachable)
                 conversations.reconnected();
             const reading = { complete: true, reachable: true };
-            await conversations.catchUp(reading);
+            if (demand.conversations)
+                await conversations.catchUp(reading);
             if (progress.reachable && reading.reachable)
                 await conversations.resend(reading);
+            if (progress.reachable)
+                void recovery.attempt('calls', resendCalls);
             if (!reading.reachable) {
                 progress.reachable = false;
                 resendLater();
@@ -2520,7 +3053,7 @@ export function composeRuntime(options) {
                 return;
             const room = discovered.get(locator);
             const held = replicas.get(locator);
-            if (room === undefined || room.replica.admission !== 'admitted')
+            if (room === undefined || room.replica.admission !== 'admitted' || !acquires(room))
                 return;
             if (held !== undefined &&
                 (held.confirmed.record.replica.selection !== room.replica.selection ||
@@ -2572,14 +3105,17 @@ export function composeRuntime(options) {
             if (event.kind === 'opened') {
                 socketOpen = true;
                 generation += 1;
+                reads.opened();
                 conversations.reopened();
                 recovery.resume();
                 void sync('opened');
             }
             else if (event.kind === 'closed')
-                closedSocket(event.revoked);
+                closedSocket(event.revoked, event.lost);
             else if (event.kind === 'opening')
                 void applyOpening(event.expired);
+            else if (event.kind === 'authority-changed')
+                void rediscover();
             else
                 void applyRoom(event.locator, event.roomVersion);
         }, receipts);
@@ -2597,6 +3133,7 @@ export function composeRuntime(options) {
             haltedRefusal = false;
         if (mode !== serviceMode) {
             serviceMode = mode;
+            queueReadiness();
             journal.record(`service mode ${mode}`);
             for (const listener of serviceModeListeners)
                 listener(mode);
@@ -2609,6 +3146,8 @@ export function composeRuntime(options) {
         if (stream === undefined || withdrawConversations !== undefined)
             return;
         withdrawConversations = stream.observe((event) => {
+            if (event.kind === 'list' || event.kind === 'listed' || event.kind === 'unlisted')
+                queueReadiness();
             if (conversations.receive(event)) {
                 void ready.then(scheduleCurrency);
                 return;
@@ -2631,7 +3170,7 @@ export function composeRuntime(options) {
         if (!live())
             return;
         await conversations.reconcile();
-        if (conversations.current()) {
+        if (conversations.current() || !demand.conversations) {
             show();
             return;
         }
@@ -2649,6 +3188,11 @@ export function composeRuntime(options) {
         if (closed)
             return;
         closed = true;
+        if (narrowing !== null)
+            clearTimeout(narrowing);
+        if (rechecking !== null)
+            clearInterval(rechecking);
+        readinessWatches.clear();
         withdrawStream?.();
         withdrawStream = undefined;
         withdrawConversations?.();
@@ -2696,11 +3240,38 @@ export function composeRuntime(options) {
         return planOf(input, roomFacts(reach), planReach(reach));
     }
     function watchPlan(plan, deliver) {
-        return readSide.watch(plan, identityOf(plan), () => {
+        let seeded = false;
+        let pending = true;
+        const shown = () => {
+            const seed = seeds.get(plan.key);
+            if (seed === undefined || seeded || !pending)
+                return;
+            seeded = true;
+            deliver(seededResult(seed));
+        };
+        const watchers = seedWatchers.get(plan.key) ?? new Set();
+        seedWatchers.set(plan.key, watchers);
+        watchers.add(shown);
+        const stop = readSide.watch(plan, identityOf(plan), () => {
             const cover = covered(plan);
             awaitPreparation(cover);
-            return cover;
-        }, deliver);
+            return seedBehind(plan, cover);
+        }, (message) => {
+            const answered = message;
+            pending = whole(answered) && 'pending' in answered.result;
+            if (pending && seeds.has(plan.key)) {
+                shown();
+                return;
+            }
+            seeded = false;
+            deliver(message);
+        });
+        return () => {
+            watchers.delete(shown);
+            if (watchers.size === 0)
+                seedWatchers.delete(plan.key);
+            stop();
+        };
     }
     async function searched(input, reach) {
         const plan = searchPlanOf(input);
@@ -2709,40 +3280,60 @@ export function composeRuntime(options) {
             const cover = covered(filter);
             awaitPreparation(cover);
             const pending = 'pending' in cover ? [...cover.pending] : [];
-            const covering = 'pending' in cover ? [] : cover.coverage.rooms;
+            const awaited = new Set('pending' in cover ? cover.pending.map(({ room }) => room) : []);
+            const held = covered({
+                ...filter,
+                rooms: reachedRooms(filter).filter((room) => !awaited.has(room)),
+            });
+            const covering = 'pending' in held ? [] : held.coverage.rooms;
             const unindexed = covering
                 .filter(({ room }) => !searchIndex.rooms().has(room))
                 .map(({ room }) => room);
             for (const room of unindexed)
                 pending.push({ room, awaits: 'index' });
-            const held = conversations.searchable();
+            const listed = conversations.searchable();
             const named = reach !== null && !reach.conversations
                 ? []
-                : (plan.conversations ?? held).filter((one) => held.includes(one) && conversations.acquired(one));
+                : (plan.conversations ?? listed).filter((one) => listed.includes(one) && conversations.acquired(one));
             const waiting = named.filter((one) => !searchIndex.conversations().has(one));
             for (const conversation of waiting)
                 pending.push({ conversation, awaits: 'index' });
             if (unindexed.length > 0 || waiting.length > 0)
                 index(unindexed, waiting);
-            if (pending.length > 0 || 'pending' in cover)
-                return { pending };
+            const complete = pending.length === 0 && !('pending' in cover);
+            const answering = complete
+                ? filter
+                : {
+                    ...filter,
+                    rooms: covering
+                        .filter(({ room }) => searchIndex.rooms().has(room))
+                        .map(({ room }) => room),
+                };
+            const answered = covered(answering);
+            if ('pending' in answered)
+                continue;
+            const searchedConversations = named.filter((one) => searchIndex.conversations().has(one));
             const seen = searchIndex.changes();
             await searchIndex.caughtUp();
-            const selected = plan.documents === undefined && reach === null ? null : await rowsQuery(filter);
+            const selected = roomsAlone(answering) ? null : await rowsQuery(answering);
             if (selected !== null && 'pending' in selected)
-                return selected;
+                continue;
             if (searchIndex.changes() !== seen ||
-                JSON.stringify(covered(filter)) !== JSON.stringify(cover))
+                JSON.stringify(covered(answering)) !== JSON.stringify(answered))
                 continue;
-            return {
-                ...searchIndex.search(plan, selected === null ? null : selected.documents, named),
-                coverage: {
-                    rooms: covering,
-                    conversations: named,
-                    index: searchIndex.generation(),
-                    overlay: cover.coverage.overlay,
-                },
+            const hits = searchIndex.search(plan, selected === null ? null : selected.documents, searchedConversations, answering.rooms === null ? null : new Set(answering.rooms), plan.collection
+                ? new Map(answered.coverage.rooms.map(({ room }) => [
+                    room,
+                    replicas.get(room)?.confirmed.record.typedSelection?.roots ?? [],
+                ]))
+                : null);
+            const coverage = {
+                rooms: answered.coverage.rooms,
+                conversations: searchedConversations,
+                index: searchIndex.generation(),
+                overlay: answered.coverage.overlay,
             };
+            return complete ? { ...hits, coverage } : { pending, ...hits, coverage };
         }
     }
     const watch = (topic, input, deliver) => {
@@ -2789,6 +3380,9 @@ export function composeRuntime(options) {
                 presentationListeners.delete(listener);
             };
         }
+        if (topic === 'readiness') {
+            return watchReadiness({ target: '', code: 'stored', capacity: null, search: 'unused' }, null, deliver);
+        }
         if (topic === 'rooms') {
             roomListeners.add(deliver);
             deliver(listed());
@@ -2941,10 +3535,11 @@ export function composeRuntime(options) {
         },
         binaryFile: {
             read: readBinaryPath,
+            link: linkBinaryPath,
             readReference: readBinaryReference,
         },
         call(name, input) {
-            return invokeAction(name, input);
+            return recoveredAction(name, input);
         },
         reached(locator, roomVersion, path) {
             return path === undefined
@@ -2955,7 +3550,13 @@ export function composeRuntime(options) {
             return journal.export();
         },
         persistence() {
-            return options.shell.persistentStorage;
+            return persistence === 'granted';
+        },
+        async retry() {
+            journal.record('retry');
+            unindexable.clear();
+            queueReadiness();
+            resume();
         },
         observe: observing(watch),
         async reauthorize() {
@@ -2982,6 +3583,22 @@ export function composeRuntime(options) {
         query: (plan) => rowsQuery(plan),
         watchPlan,
         search: searched,
+        watchReadiness,
+    };
+    return {
+        md,
+        seed,
+        stop,
+        lose: loseRooms,
+        watch,
+        acquire,
+        persisted(answer) {
+            if (answer === persistence)
+                return;
+            persistence = answer;
+            journal.record(`persistence ${answer}`);
+            queueReadiness();
+        },
+        within: (reach, port) => narrowed(reachable, reach, port),
     };
-    return { md, stop, lose: loseRooms, watch, within: (reach) => narrowed(reachable, reach) };
 }