@farmslot/protocol 0.74.9 → 0.75.0

package/dist/client-cache/cache.js

@@ -1,11 +1,13 @@
 import { Methods } from '../rpc/registry.js';
+import { runListVersion } from '../runs/list-version.js';
 import { ResourceCollectorAdmission } from './collector-admission.js';
-import { resourceBudgetEvictions, resourceContentWithinLimits, verifyResourceContent, } from './content.js';
+import { resourceBudgetEvictions, resourceContentWithinLimits, verifyResourceContent, verifyResourceContentInSlices, } from './content.js';
 import { isKnownResourceFamily, RESOURCE_PUBLISH_INTERVAL_MS, RESOURCE_REREAD_INTERVAL_MS, RESOURCE_RETRY_MAX_WAIT_MS, resourceKeyId, } from './keys.js';
 import { nativeHistoryStorageId, readNativeHistory, storedNativeHistoryMatches, } from './native-history.js';
 import { resourceQuery } from './registry.js';
+import { createRunDetailSync, runDetailTarget } from './run-details.js';
 import { isRunListCollectionRead, RUN_LIST_COLLECTION_ID, RunListCollection, runListSummaryFlags, } from './run-list-versions.js';
-import { createMemoryResourceStore, normalizeResourceStoreScope, resourceStoreScopeId, sameResourceAuthority, } from './store.js';
+import { createMemoryResourceStore, normalizeResourceStoreScope, readStoredQueryBatch, resourceStoreScopeId, sameResourceAuthority, } from './store.js';
 import { isUpstreamStoredQuery, upstreamRetentionEvictions } from './upstream-retention.js';
 import { workspaceRetentionEvictions, workspaceRetentionMembership, } from './workspace-retention.js';
 const deletionReasons = new Set([
@@ -21,6 +23,13 @@ const evictionCodes = new Set([
     'RUN_NOT_FOUND',
     'RESOURCE_NOT_FOUND',
 ]);
+/**
+ * The gateway refused the read: the resource is gone or not this principal's. The
+ * cache evicts saved data on these; a network failure or timeout is not one.
+ */
+export function readRefused(error) {
+    return Boolean(error && evictionCodes.has(error.code));
+}
 function queryError(error) {
     const code = error && typeof error === 'object' ? Reflect.get(error, 'code') : undefined;
     return {
@@ -44,6 +53,7 @@ function normalizeConnection(connection) {
     };
 }
 const defaultContentBudgetBytes = 500 * 1024 * 1024;
+const startupQueryBytes = 8 * 1024 * 1024;
 // Only the identity crosses the store seam, never a caller's other fields.
 const contentKey = ({ kind, id }) => ({ kind, id });
 function profileId(connection) {
@@ -56,6 +66,9 @@ export function createGatewayResourceCache(options) {
     const transport = options.transport;
     let store = options.store ?? createMemoryResourceStore();
     let metadata;
+    let startupStore;
+    let startupOwnerVersion = -1;
+    const startupQueries = new Map();
     let connection = normalizeConnection(transport.getConnection());
     let usable = false;
     let disposed = false;
@@ -91,9 +104,33 @@ export function createGatewayResourceCache(options) {
         maxBodyBytes: resourceQuery(Methods.RUN_LIST).maxBytes,
     });
     let runListLoad;
+    const fallbackDetailTargets = new Map();
+    const detailSync = createRunDetailSync({
+        connection: () => connection,
+        list: async () => (await readStoredContent((target) => target.listQueries())) ?? [],
+        stored: (runId) => readStoredContent((target) => target.getQuery(resourceQuery(Methods.RUN_GET, { runId }).id)),
+        touch: async (runId) => {
+            const target = store;
+            const ownerVersion = hydrationOwnerVersion;
+            await updateStore(target, () => target === store && !target.deleted && ownerVersion === hydrationOwnerVersion, () => target.touchQuery?.(resourceQuery(Methods.RUN_GET, { runId }).id, Date.now()) ??
+                Promise.resolve());
+        },
+        fetch: (runId, maxStoredBytes, signal) => retryQuery(resourceQuery(Methods.RUN_GET, { runId }), { origin: 'prefetch', cohort: 'run', maxStoredBytes }, signal),
+        onError: (error) => options.onStorageNotice?.(`Background run details could not sync: ${queryError(error).message}`),
+    });
+    function refreshDetailTargets() {
+        const versioned = runList.detailTargets();
+        detailSync.setTargets(store.persistent && usable
+            ? runList.held
+                ? versioned
+                : [...fallbackDetailTargets.values()]
+            : []);
+    }
     function forgetRunList() {
         runList.clear();
         runListLoad = undefined;
+        fallbackDetailTargets.clear();
+        detailSync.reset();
     }
     function updateCollectors() {
         collectors.update({ ...connection, foreground: usable && connection.foreground !== false }, usable
@@ -116,12 +153,29 @@ export function createGatewayResourceCache(options) {
         unsubscribeStore();
         store = next;
         storeVersion++;
+        startupStore = undefined;
+        startupQueries.clear();
+        detailSync.reset();
         unsubscribeStore = store.onDeleted(storeDeleted);
     }
+    /** Observers whose failure was already logged, so a repeating one is reported once. */
+    const failedObservers = new WeakSet();
+    /** One observer's failure is its own: the other observers and the cache's reads go on. */
+    function deliver(entry, listener) {
+        try {
+            listener(entry.state);
+        }
+        catch (error) {
+            if (failedObservers.has(listener))
+                return;
+            failedObservers.add(listener);
+            console.error(`Resource cache observer of ${entry.query.id} failed:`, error);
+        }
+    }
     function notify(entry) {
         entry.state = { ...entry.state, storageNotice };
         for (const listener of entry.listeners)
-            listener(entry.state);
+            deliver(entry, listener);
     }
     function cancelScheduledRead(entry) {
         if (entry.readTimer !== undefined)
@@ -232,6 +286,46 @@ export function createGatewayResourceCache(options) {
             if (entry.state.status !== 'ready')
                 hydrateEntry(entry);
     }
+    async function warmStoredQueries() {
+        if (!store.persistent ||
+            (startupStore === store && startupOwnerVersion === hydrationOwnerVersion))
+            return;
+        const readingStore = store;
+        const incarnation = storeVersion;
+        const ownerVersion = hydrationOwnerVersion;
+        const current = () => !disposed &&
+            store === readingStore &&
+            !readingStore.deleted &&
+            incarnation === storeVersion &&
+            ownerVersion === hydrationOwnerVersion;
+        try {
+            const batch = await readStoredQueryBatch(readingStore, startupQueryBytes);
+            if (!current())
+                return;
+            const collection = batch.find((saved) => saved.id === RUN_LIST_COLLECTION_ID);
+            const rows = collection && readingStore.getRows
+                ? await readingStore.getRows(RUN_LIST_COLLECTION_ID)
+                : undefined;
+            if (!current())
+                return;
+            startupQueries.clear();
+            let remaining = startupQueryBytes;
+            for (const saved of batch) {
+                if (saved.bytes > remaining)
+                    continue;
+                remaining -= saved.bytes;
+                if (saved.id !== RUN_LIST_COLLECTION_ID)
+                    startupQueries.set(saved.id, saved);
+            }
+            if (rows)
+                runList.hydrate(rows);
+            startupStore = readingStore;
+            startupOwnerVersion = ownerVersion;
+        }
+        catch (error) {
+            await recoverStore(error, readingStore);
+        }
+    }
     function schedule(entry) {
         if (entry.queued || disposed)
             return;
@@ -261,8 +355,13 @@ export function createGatewayResourceCache(options) {
             connection.id === next.id &&
             !scopeChanged &&
             !authorityChanged &&
-            !revoke)
+            !revoke) {
+            if (connection.metered !== next.metered) {
+                connection = { ...connection, metered: next.metered };
+                refreshDetailTargets();
+            }
             return;
+        }
         const ticket = ++version;
         runList.abort();
         // Stored facts belong to an owner, not a socket attempt. Fence a revoked
@@ -273,6 +372,7 @@ export function createGatewayResourceCache(options) {
         }
         connection = next;
         usable = false;
+        refreshDetailTargets();
         updateCollectors();
         revisions.clear();
         for (const entry of entries.values()) {
@@ -361,9 +461,14 @@ export function createGatewayResourceCache(options) {
                     await recoverStore(error, target);
                 }
             }
+            if (disposed || ticket !== version)
+                return;
+            if (!revoke && canPersist(next))
+                await warmStoredQueries();
             if (disposed || ticket !== version)
                 return;
             usable = next.connected && next.foreground !== false && !revoke;
+            refreshDetailTargets();
             updateCollectors();
             if (usable)
                 for (const entry of entries.values())
@@ -409,7 +514,7 @@ export function createGatewayResourceCache(options) {
             if (change.revision <= (revisions.get(id) ?? -1))
                 continue;
             revisions.set(id, change.revision);
-            const affected = [...entries.values()].filter((entry) => entry.query.dependencies.some((key) => resourceKeyId(key) === id));
+            const affected = [...entries.values()].filter((entry) => entry.dependencyIds.has(id));
             // Coverage counts declared dependencies only, so a known key that no entry declares (another
             // slot, an unopened workspace) changes nothing held. Only a family this client cannot name might.
             if (!affected.length && isKnownResourceFamily(change.key?.family))
@@ -441,6 +546,7 @@ export function createGatewayResourceCache(options) {
         }
         const entry = {
             query,
+            dependencyIds: new Set(query.dependencies.map(resourceKeyId)),
             state: { status: 'loading' },
             listeners: new Set(),
             hydration: Promise.resolve(),
@@ -454,9 +560,40 @@ export function createGatewayResourceCache(options) {
             failures: 0,
         };
         entries.set(query.id, entry);
-        hydrateEntry(entry);
+        const saved = isRunListView(query) ? heldRunListView(query) : takeStartupQuery(query);
+        if (applyStoredQuery(entry, saved)) {
+            entry.hydrated = true;
+            queueMicrotask(prune);
+        }
+        else
+            hydrateEntry(entry);
         return entry;
     }
+    function takeStartupQuery(query) {
+        if (startupStore !== store || startupOwnerVersion !== hydrationOwnerVersion)
+            return undefined;
+        const id = nativeHistoryStorageId(query);
+        const saved = startupQueries.get(id);
+        startupQueries.delete(id);
+        return saved;
+    }
+    function applyStoredQuery(entry, saved) {
+        const query = entry.query;
+        if (!saved ||
+            !query.persisted ||
+            saved.bytes > query.maxBytes ||
+            (query.method === Methods.NATIVE_SESSION_READ &&
+                !storedNativeHistoryMatches(query.params, saved.data)))
+            return false;
+        const sourceObservation = query.sourceObservation?.(saved.data);
+        entry.state = {
+            status: 'stale',
+            data: saved.data,
+            observedAt: saved.observedAt,
+            ...(sourceObservation ? { sourceObservation, error: sourceObservation.error } : {}),
+        };
+        return true;
+    }
     function hydrateEntry(entry) {
         const query = entry.query;
         const hydrationSerial = ++entry.hydrationSerial;
@@ -470,7 +607,8 @@ export function createGatewayResourceCache(options) {
             const readingStore = store;
             try {
                 const saved = query.persisted
-                    ? ((isRunListView(query) ? await storedRunListView(query, readingStore) : undefined) ??
+                    ? (takeStartupQuery(query) ??
+                        (isRunListView(query) ? await storedRunListView(query, readingStore) : undefined) ??
                         (await readingStore.getQuery(nativeHistoryStorageId(query))))
                     : undefined;
                 if (!disposed &&
@@ -480,17 +618,7 @@ export function createGatewayResourceCache(options) {
                     ownerVersion === hydrationOwnerVersion &&
                     entry.hydrationSerial === hydrationSerial &&
                     entry.state.status !== 'ready' &&
-                    saved &&
-                    saved.bytes <= query.maxBytes &&
-                    (query.method !== Methods.NATIVE_SESSION_READ ||
-                        storedNativeHistoryMatches(query.params, saved.data))) {
-                    const sourceObservation = query.sourceObservation?.(saved.data);
-                    entry.state = {
-                        status: 'stale',
-                        data: saved.data,
-                        observedAt: saved.observedAt,
-                        ...(sourceObservation ? { sourceObservation, error: sourceObservation.error } : {}),
-                    };
+                    applyStoredQuery(entry, saved)) {
                     notify(entry);
                 }
             }
@@ -521,6 +649,9 @@ export function createGatewayResourceCache(options) {
                 };
             await runListLoad.promise;
         }
+        return heldRunListView(query);
+    }
+    function heldRunListView(query) {
         const data = runList.view(query.params);
         return data && runList.observedAt !== undefined
             ? { id: query.id, data, observedAt: runList.observedAt, bytes: 0 }
@@ -623,7 +754,11 @@ export function createGatewayResourceCache(options) {
             const shared = entry.pending.prefetch;
             entry.pending.prefetch =
                 shared && prefetch
-                    ? { origin: 'prefetch', cohort: shared.cohort === 'gate' ? 'gate' : prefetch.cohort }
+                    ? {
+                        origin: 'prefetch',
+                        cohort: shared.cohort === 'gate' ? 'gate' : prefetch.cohort,
+                        maxStoredBytes: Math.min(shared.maxStoredBytes ?? Infinity, prefetch.maxStoredBytes ?? Infinity),
+                    }
                     : undefined;
             return entry.pending.promise;
         }
@@ -744,6 +879,7 @@ export function createGatewayResourceCache(options) {
                 const retention = entry.query.retention;
                 const saved = serialized !== undefined &&
                     bytes <= entry.query.maxBytes &&
+                    (entry.listeners.size > 0 || bytes <= (pending.prefetch?.maxStoredBytes ?? Infinity)) &&
                     (!retention || bytes <= retention.maxBytes)
                     ? {
                         id: nativeHistoryStorageId(entry.query),
@@ -816,7 +952,9 @@ export function createGatewayResourceCache(options) {
                                 (retention.cohort === 'upstream'
                                     ? isUpstreamStoredQuery(value.id)
                                     : value.id.startsWith(`${entry.query.method}:`)))
-                                .sort((a, b) => a.observedAt - b.observedAt ||
+                                .sort((a, b) => (entry.query.method === Methods.RUN_GET
+                                ? (a.accessedAt ?? a.observedAt) - (b.accessedAt ?? b.observedAt)
+                                : a.observedAt - b.observedAt) ||
                                 (entries.get(a.id)?.lastUsed ?? 0) - (entries.get(b.id)?.lastUsed ?? 0));
                             if (!current())
                                 return;
@@ -836,6 +974,14 @@ export function createGatewayResourceCache(options) {
                             await writingStore.putQuery(row);
                     });
                 }
+                if (store.persistent && entry.query.method === Methods.RUN_LIST) {
+                    const listed = reply.data;
+                    if (Array.isArray(listed.runs)) {
+                        for (const run of listed.runs)
+                            fallbackDetailTargets.set(run.id, runDetailTarget(run, runListVersion(run)));
+                    }
+                    refreshDetailTargets();
+                }
             }
             catch (error) {
                 if (disposed ||
@@ -962,14 +1108,25 @@ export function createGatewayResourceCache(options) {
         });
         return written;
     }
+    function contentWriteToken() {
+        return { connectionId: connection.id, ownerVersion: hydrationOwnerVersion, storeVersion };
+    }
     /** Stores verified bytes within the caps and the shared budget. */
-    function storeContent(input) {
+    async function storeContent(input) {
         const key = contentKey(input.key);
         const { data, origin, cohort } = input;
-        if (!resourceContentWithinLimits(key, data) ||
-            !verifyResourceContent(key, data, input.untrackedFiles))
-            return Promise.resolve(false);
-        return writeContent(input.token, async (target, current) => {
+        // Prefetch verifies between frames, so the write still answers to the owner it was asked under.
+        const token = input.token ?? contentWriteToken();
+        if (!resourceContentWithinLimits(key, data))
+            return false;
+        // Prefetch is background work; content a person opened is on their critical path and
+        // verifies at once, as before.
+        const verified = origin === 'prefetch'
+            ? await verifyResourceContentInSlices(key, data, input.untrackedFiles)
+            : verifyResourceContent(key, data, input.untrackedFiles);
+        if (!verified)
+            return false;
+        return writeContent(token, async (target, current) => {
             const accessedAt = Date.now();
             const content = await target.listContent();
             if (content.some((row) => row.kind === key.kind && row.id === key.id)) {
@@ -1019,6 +1176,13 @@ export function createGatewayResourceCache(options) {
             return true;
         });
     }
+    async function retryQuery(query, placement, signal) {
+        if (disposed)
+            throw new Error('Resource cache is disposed');
+        const entry = entryFor(query);
+        await fetchEntry(entry, false, placement, signal);
+        return entry.state;
+    }
     return {
         observedKey(match) {
             for (const entry of entries.values())
@@ -1071,7 +1235,7 @@ export function createGatewayResourceCache(options) {
                     notify(entry);
                 });
             }
-            receive(entry.state);
+            deliver(entry, receive);
             if (entry.state.status !== 'ready' || entry.dirty)
                 schedule(entry);
             return () => {
@@ -1091,13 +1255,21 @@ export function createGatewayResourceCache(options) {
                 throw new Error('Resource cache is disposed');
             return entryFor(query).state;
         },
-        async retry(query, placement, signal) {
+        async readStored(query, refresh = true) {
             if (disposed)
                 throw new Error('Resource cache is disposed');
+            const ownerVersion = hydrationOwnerVersion;
+            await barrier;
             const entry = entryFor(query);
-            await fetchEntry(entry, false, placement, signal);
+            await entry.hydration;
+            if (disposed || ownerVersion !== hydrationOwnerVersion)
+                throw new Error('The offline store owner changed');
+            // fetchEntry records network refusals in the query state and notifies its readers.
+            if (refresh && entry.state.data !== undefined)
+                void fetchEntry(entry);
             return entry.state;
         },
+        retry: retryQuery,
         async retryAfterPending(query) {
             if (disposed)
                 throw new Error('Resource cache is disposed');
@@ -1112,20 +1284,22 @@ export function createGatewayResourceCache(options) {
         readContent: (key) => readContentBytes((target) => target.getContent(contentKey(key)), false),
         runListProjections: () => runList.projections(),
         openContent: (key) => readContentBytes((target) => target.getContent(contentKey(key)), true),
+        async forgetContent(key) {
+            const target = store;
+            const ownerVersion = hydrationOwnerVersion;
+            await updateStore(target, () => target === store && !target.deleted && ownerVersion === hydrationOwnerVersion, () => target.deleteContent(contentKey(key)));
+        },
         readContentByAlias: (alias) => readContentBytes((target) => target.getContentByAlias(alias), false),
         openContentByAlias: (alias) => readContentBytes((target) => target.getContentByAlias(alias), true),
         storeContent,
         retainContent,
-        contentWriteToken: () => ({
-            connectionId: connection.id,
-            ownerVersion: hydrationOwnerVersion,
-            storeVersion,
-        }),
+        contentWriteToken,
         async dispose(reason) {
             if (disposed)
                 return;
             const withdrawing = collectors.close();
             disposed = true;
+            detailSync.reset();
             version++;
             unsubscribeChanges();
             unsubscribeConnection();