@zackbart/connecta 0.38.0 → 0.40.0

package/dist/routes/ui-data.js

@@ -9,14 +9,19 @@ import { describedTools } from "../described.js";
 import { Effect } from "effect";
 import { bindActivityRequest } from "../activity-request.js";
 import { resolveDiscoveryConcurrency } from "../concurrency.js";
+import { credentialReads } from "../credential-reads.js";
 import { credentialTestRule, describeUndeclaredCredentialFields, storedCredentialShape } from "../credential-rules.js";
+import { readVerification } from "../credential-verification.js";
 import { failureRecord, failureStatus, logFailure, recordedToolName, statusFailure } from "../operator-record.js";
 import { closeScope } from "../runtime/connector-scope.js";
+import { requestReads } from "../runtime/request-scope.js";
 import { withDeadlineEffect } from "../runtime/run.js";
 import { uiProblemFor } from "../ui.js";
 import { CONNECTA_VERSION } from "../version.js";
+import { prepareStatusSlot, readStatusObservation, storeStatusObservation, } from "../connector-status.js";
 const DETAIL_TIMEOUT_MS = 30_000;
 const DETAIL_TIMED_OUT = "Connection details timed out. Retry this connection.";
+const OBSERVE_TIMED_OUT = "Connector did not answer before the operator page's deadline.";
 function attempt(operation) {
     return Effect.tryPromise({ try: operation, catch: (error) => error });
 }
@@ -38,6 +43,35 @@ export function uiData(registry, baseUrl, options) {
             const logger = registry.contextFor(id, baseUrl, requestScope).logger;
             logFailure(logger, "operator status", failureRecord({ connector: id, state }, failure), state === "auth_required" ? "info" : "warn");
         };
+        // A stored row: the observation's state and problem, and no tools. They
+        // stay in the catalog cache (INV-8), and the browser's live read, which
+        // follows in its own request, shows them. Reading them here could connect,
+        // and the row's scope would wait for that listing to end.
+        // The credential's stored verification is local, so it is read fresh here too.
+        const observeStored = (c, stored, drift, requestScope) => drift
+            ? Effect.succeed({ status: { state: "auth_required", message: drift }, tools: [], catalogFailed: false })
+            : Effect.map(verificationFor(c, requestScope), (verification) => ({
+                status: { state: stored.state },
+                tools: [],
+                catalogFailed: stored.problem === "catalog_failed",
+                ...(stored.problem === "connector_timeout" ? { timedOut: true } : {}),
+                verification,
+            }));
+        /**
+         * The stored last verification of an operator-managed credential
+         * (src/credential-verification.ts). Read only, never probed (INV-10). A
+         * record counts only for the save it observed, whose revision the card's
+         * memoized vault read already holds; a vault without revisions has none
+         * to match.
+         */
+        const verificationFor = (c, requestScope) => c.credential && vault
+            ? attempt(async () => {
+                const metadata = await credentialReads(vault, requestReads(requestScope)).metadata(c.id, c.authScope === "personal" ? owner : undefined);
+                return metadata?.revision
+                    ? readVerification(registry.contextFor(c.id, baseUrl, requestScope).storage, metadata.revision)
+                    : undefined;
+            }).pipe(Effect.orElseSucceed(() => undefined))
+            : Effect.succeed(undefined);
         // Status first, then the catalog only when status is ok. A failed status
         // read is an error status, not a failed row: the row still reports the
         // connector's credential.
@@ -54,8 +88,9 @@ export function uiData(registry, baseUrl, options) {
                     signal,
                     ...(options.defer ? { defer: options.defer } : {}),
                 }));
+                const verification = yield* verificationFor(c, requestScope);
                 if (status.state !== "ok" || signal.aborted) {
-                    return { status, tools: [], catalogFailed: false };
+                    return { status, tools: [], catalogFailed: false, verification };
                 }
                 // A catalog is configuration the operator chose to load, and its
                 // descriptions are the agent's too, so the page shows them as text.
@@ -71,10 +106,10 @@ export function uiData(registry, baseUrl, options) {
                     name: recordedToolName(t),
                     address: `${c.id}.${recordedToolName(t)}`,
                     classification: t.classification === "read" ? "read" : "write",
-                }))).pipe(Effect.map((tools) => ({ status, tools, catalogFailed: false })), 
+                }))).pipe(Effect.map((tools) => ({ status, tools, catalogFailed: false, verification })), 
                 // The registry owns the failed catalog observation; the page only
                 // needs to know there was one.
-                Effect.catch(() => Effect.succeed({ status, tools: [], catalogFailed: !signal.aborted })), 
+                Effect.catch(() => Effect.succeed({ status, tools: [], catalogFailed: !signal.aborted, verification })), 
                 // Loading the catalog may replace an earlier clean observation.
                 // Read this view's current bounded facts without another status probe.
                 Effect.map((observed) => ({
@@ -87,9 +122,23 @@ export function uiData(registry, baseUrl, options) {
                 catalogFailed: false,
             })));
         };
+        // The observation under its own deadline. Its abort reaches the status
+        // and catalog reads through `inner`, which then settle as an error or a
+        // failed catalog; either way the reason on `inner` says the deadline
+        // ended them, so the row is a timeout rather than a failure.
+        const observeWithin = (c, drift, signal, requestScope, timeoutMs) => {
+            const timeoutError = new Error(OBSERVE_TIMED_OUT);
+            const timedOut = () => ({
+                status: failureStatus(c.id, timeoutError),
+                tools: [],
+                catalogFailed: false,
+                timedOut: true,
+            });
+            return withDeadlineEffect((inner) => observe(c, drift, inner, requestScope).pipe(Effect.map((observed) => (inner.reason === timeoutError ? timedOut() : observed))), { timeoutMs, signal, timeoutError }).pipe(Effect.catch((error) => (error === timeoutError ? Effect.succeed(timedOut()) : Effect.fail(error))));
+        };
         // The credential card, for someone who may manage this connector's auth.
         // Never fails: a vault that cannot be read is the card's own error.
-        const credentialFor = (c) => {
+        const credentialFor = (c, requestScope) => {
             const mayManageAuth = options.mayManage?.(c.id) ?? (c.authScope === "personal" ? Boolean(owner) : options.oauthManagement);
             const declared = c.credential;
             if (!declared || !vault || !mayManageAuth)
@@ -121,7 +170,9 @@ export function uiData(registry, baseUrl, options) {
                 ...(declared.placeholder ? { placeholder: declared.placeholder } : {}),
             };
             return attempt(async () => {
-                const metadata = await vault.metadata(c.id, c.authScope === "personal" ? owner : undefined);
+                // Memoized per request: the card only displays what the drift and
+                // status reads of this same detail already read.
+                const metadata = await credentialReads(vault, requestReads(requestScope)).metadata(c.id, c.authScope === "personal" ? owner : undefined);
                 const fields = credentialFields(metadata);
                 const shape = storedCredentialShape(declared, metadata?.fields ?? null);
                 return {
@@ -152,18 +203,52 @@ export function uiData(registry, baseUrl, options) {
                 });
             }));
         };
-        const detail = (c, signal, requestScope) => Effect.gen(function* () {
-            const drift = yield* attempt(() => registry.credentialDriftFor(c.id));
+        // Where this row records what it observed. A live read prepares only the
+        // generation; a stored read looks the observation up and, finding none,
+        // records the live read it falls back to.
+        const statusLookup = (c, requestScope) => options.statusObservation === "stored"
+            ? readStatusObservation(registry, c.id, baseUrl, requestScope)
+            : options.statusObservation === "record"
+                ? Effect.map(prepareStatusSlot(registry, c.id, baseUrl, requestScope), (slot) => (slot ? { slot } : {}))
+                : Effect.succeed({});
+        const detail = (c, signal, requestScope, recording) => Effect.gen(function* () {
+            // The status slot is read before the probe starts, so an invalidation
+            // during it leaves the observation under the generation it replaced.
+            const [drift, stored] = yield* Effect.all([attempt(() => registry.credentialDriftFor(c.id, requestScope)), statusLookup(c, requestScope)], { concurrency: 2 });
+            const observation = stored.observation;
+            const statusSlot = observation ? undefined : stored.slot;
+            // The row's own deadline may end it below; it records from here.
+            if (statusSlot)
+                recording.slot = statusSlot;
             // One deadline covers the whole row. The status and catalog reads once
             // had a second one of the same length inside it, which could only fire
             // after this one had already ended the row.
-            const { status, tools, catalogFailed } = yield* observe(c, drift, signal, requestScope);
-            const credential = yield* credentialFor(c);
+            // The operator page's shorter observation deadline, when it has one,
+            // bounds only the downstream: the credential card below is local
+            // storage and still renders, so a slow vendor's slot stays fixable.
+            const { status, tools, catalogFailed, timedOut, verification } = observation
+                ? yield* observeStored(c, observation, drift, requestScope)
+                : options.observeTimeoutMs === undefined
+                    ? yield* observe(c, drift, signal, requestScope)
+                    : yield* observeWithin(c, drift, signal, requestScope, options.observeTimeoutMs);
+            const credential = yield* credentialFor(c, requestScope);
             logStatus(c.id, status.state, statusFailure(status), requestScope);
-            const problem = uiProblemFor(c, status.state, {
-                credentialDrift: Boolean(drift),
-                catalogFailed,
-            });
+            const problem = timedOut
+                ? "connector_timeout"
+                : uiProblemFor(c, status.state, {
+                    credentialDrift: Boolean(drift),
+                    catalogFailed,
+                });
+            const toolCount = observation ? observation.toolCount : tools.length;
+            // Started only while the caller is still here, then awaited to its
+            // end even if the row's deadline or the caller ends it meanwhile.
+            if (statusSlot && !signal.aborted && !options.signal?.aborted)
+                yield* Effect.uninterruptible(storeStatusObservation(statusSlot, {
+                    state: status.state,
+                    ...(problem ? { problem } : {}),
+                    toolCount,
+                    observedAt: Date.now(),
+                }));
             return {
                 id: c.id,
                 authScope: c.authScope ?? "shared",
@@ -171,7 +256,7 @@ export function uiData(registry, baseUrl, options) {
                 ...(c.description !== undefined ? { description: c.description } : {}),
                 status: status.state,
                 ...(problem ? { problem } : {}),
-                toolCount: tools.length,
+                toolCount,
                 tools: tools.map((tool) => ({
                     name: tool.name,
                     address: tool.address,
@@ -186,7 +271,9 @@ export function uiData(registry, baseUrl, options) {
                     ...(status.registrationPath ? { auth: { registrationPath: status.registrationPath } } : {}),
                     catalogAgeMs: registry.catalogAgeMs(c.id),
                     lastCall: null,
+                    ...(observation ? { observedAgeMs: Math.max(0, Date.now() - observation.observedAt) } : {}),
                 },
+                ...(observation ? { observedAgeMs: Math.max(0, Date.now() - observation.observedAt) } : {}),
                 // Counts only, and only when a refresh in this runtime produced them.
                 // `Registry.withCatalogObservations` rebuilt the report through
                 ...(status.catalogAccess ? { catalogAccess: status.catalogAccess } : {}),
@@ -196,43 +283,62 @@ export function uiData(registry, baseUrl, options) {
                     : {}),
                 oauth: Boolean(c.startAuth && c.disconnectAuth),
                 ...(status.registrationPath ? { registrationPath: status.registrationPath } : {}),
+                ...(verification ? { verification } : {}),
                 ...(credential ? { credential } : {}),
             };
         });
-        const unavailable = (c, error, requestScope) => Effect.sync(() => {
+        const unavailable = (c, error, requestScope, timeoutError) => Effect.sync(() => {
             logStatus(c.id, "failed", error, requestScope);
+            // The row's own deadline is a timeout too, whichever ran out first.
+            const problem = error === timeoutError ? "connector_timeout" : "connector_unavailable";
             return {
                 id: c.id,
                 ...(c.title ? { title: c.title } : {}),
                 authScope: c.authScope ?? "shared",
                 status: "error",
-                problem: "connector_unavailable",
+                problem,
                 oauth: Boolean(c.startAuth && c.disconnectAuth),
                 toolCount: 0,
                 tools: [],
                 overlay: {
                     id: c.id,
                     status: "error",
-                    problem: "connector_unavailable",
+                    problem,
                     tools: [],
                     catalogAgeMs: registry.catalogAgeMs(c.id),
                     lastCall: null,
                 },
             };
         });
+        // The row's own deadline ended the read: record that timeout before the
+        // response, so the next stored read parks this row too. A caller who has
+        // already left records nothing. Once started, the write is awaited to its
+        // end, never raced or detached: storage writes cannot be withdrawn once
+        // sent, so the request settles only after it does, bounded by the storage
+        // layer like every other awaited write (INV-7).
+        const recordRowTimeout = (slot) => !slot || options.signal?.aborted
+            ? Effect.void
+            : Effect.uninterruptible(storeStatusObservation(slot, {
+                state: "error",
+                problem: "connector_timeout",
+                toolCount: 0,
+                observedAt: Date.now(),
+            }));
         const row = (c) => Effect.suspend(() => {
             // A row ends independently. Revoking its probe must not revoke a live
             // sibling that happens to belong to the same operator payload.
             const requestScope = {};
             if (options.activityContext)
                 bindActivityRequest(requestScope, options.activityContext);
-            return withDeadlineEffect((signal) => detail(c, signal, requestScope), {
+            const timeoutError = new Error(DETAIL_TIMED_OUT);
+            const recording = {};
+            return withDeadlineEffect((signal) => detail(c, signal, requestScope, recording), {
                 timeoutMs: options.timeoutMs ?? DETAIL_TIMEOUT_MS,
                 ...(options.signal ? { signal: options.signal } : {}),
-                timeoutError: new Error(DETAIL_TIMED_OUT),
+                timeoutError,
             }).pipe(
             // A hook that throws where it should reject fails its own row too.
-            Effect.catchDefect((defect) => Effect.fail(defect)), Effect.catch((error) => unavailable(c, error, requestScope)), Effect.ensuring(Effect.suspend(() => closeScope(c, registry.contextFor(c.id, baseUrl, requestScope), options.defer))));
+            Effect.catchDefect((defect) => Effect.fail(defect)), Effect.catch((error) => Effect.andThen(recordRowTimeout(error === timeoutError ? recording.slot : undefined), unavailable(c, error, requestScope, timeoutError))), Effect.ensuring(Effect.suspend(() => closeScope(c, registry.contextFor(c.id, baseUrl, requestScope), options.defer))));
         });
         return Effect.forEach(registry.listConnectors(), row, {
             concurrency: resolveDiscoveryConcurrency(options.discoveryConcurrency),

package/dist/routes/ui.js

@@ -134,6 +134,16 @@ function operatorView({ opts }, authz, registry) {
             : "requires_operator";
     return { visible, mayManage, permissions, activityEnabled, credentialManagement };
 }
+/**
+ * How long a detail read waits on the downstream before its row reports
+ * `connector_timeout`. A cold remote MCP handshake with an OAuth refresh is
+ * about five sequential round trips, so 8 s allows ~1.5 s each; anything
+ * slower is shown as slow or unreachable rather than holding one of the
+ * page's few detail slots for the full discovery deadline. A deployment that
+ * set a shorter `discovery.probeTimeoutMs` keeps that one deadline, which also
+ * ends in `connector_timeout`.
+ */
+const DETAIL_OBSERVE_TIMEOUT_MS = 8000;
 /** One connector's probed row, the page's second request per card. */
 function connectorDetail(context, id) {
     const { request, baseUrl, opts, defer } = context;
@@ -158,7 +168,13 @@ function connectorDetail(context, id) {
             discoveryConcurrency: 1,
             personalCredentialOwner: authz.principalKey,
             mayManage,
+            // A live read records its observation; `?observation=stored` answers
+            // from the current one instead and leaves the live read to the browser.
+            statusObservation: context.url.searchParams.get("observation") === "stored" ? "stored" : "record",
             timeoutMs: opts.config.discovery.probeTimeoutMs,
+            ...(opts.config.discovery.probeTimeoutMs > DETAIL_OBSERVE_TIMEOUT_MS
+                ? { observeTimeoutMs: DETAIL_OBSERVE_TIMEOUT_MS }
+                : {}),
             signal: request.signal,
         });
         const detail = data.connectors[0];

package/dist/runtime/call.js

@@ -1,12 +1,13 @@
 // Operation and call services. Only the Promise view bridge is keyed on a
 // context object; authority lives in Context values, shared by derived views.
+import { Routes, routesOf } from "../agent-routes.js";
 import { Context, Effect } from "effect";
 import { ConnectorCallError } from "../errors.js";
 import { dispatchProviderRequest, } from "../provider-call.js";
 import { SentSecrets, sentSecretsForRequest, registerCredentialValues } from "../sent-secrets.js";
 import { recordRecovery } from "../call-recovery.js";
 import { fromSignal, runEdge } from "./run.js";
-import { RequestScope, requestOwner as requestOf } from "./request-scope.js";
+import { RequestScope, requestOwner as requestOf, requestReads } from "./request-scope.js";
 /** Who admitted the operation; absent for a probe or a callback no request admitted. */
 export class Caller extends Context.Service()("connecta/call/Caller") {
 }
@@ -197,7 +198,7 @@ function openCall(inputs) {
                 throw ended();
             (inputs.ledger ?? detachedLedger).dispatch(request, headers, method);
         },
-    }), Context.add(CallMemo, new Map()), Context.add(ProviderLedger, inputs.providerLedger), Context.add(LogicalLedger, inputs.operation ? serviceFor(inputs.operation, LogicalLedger) : undefined));
+    }), Context.add(CallMemo, new Map()), Context.add(ProviderLedger, inputs.providerLedger), Context.add(LogicalLedger, inputs.operation ? serviceFor(inputs.operation, LogicalLedger) : undefined), Context.add(Routes, routesOf(inputs.operation)));
     const lease = {
         get services() {
             return Context.add(Context.add(services, ActiveCall, lease), Operation, inputs.operation);
@@ -338,6 +339,10 @@ export function chargeView(view) {
     const budget = recordedService(view, Budget);
     return budget ? runEdge(budget.charge) : Promise.reject(ended());
 }
+/** The read memo of the request this context belongs to (request-reads.ts). */
+export function viewReads(view) {
+    return requestReads(views.get(view)?.request ?? view.requestScope ?? view);
+}
 /** Admission is sticky until request close; ending a call never makes its copies standalone. */
 export function callScopeKnown(view) {
     const scope = requestOf(views.get(view)?.request ?? view.requestScope ?? view);

package/dist/runtime/native-storage.js

@@ -23,8 +23,20 @@ function current(receiver, key, own, args, native) {
 export function registerNativeStorage(edge, native) {
     const own = { get: edge.get, set: edge.set, delete: edge.delete, list: edge.list, compareAndSet: edge.compareAndSet };
     storageMethods.set(edge, own);
+    const getMany = native.getMany;
     storage.set(edge, {
+        accessToken: native.accessToken
+            ? (hash) => typed(() => (getNativeStorage(edge) ? native.accessToken(hash) : Effect.succeed(undefined)))
+            : undefined,
         get: (key) => current(edge, "get", own.get, [key], () => native.get(key)),
+        // A replaced `get` answers each key itself, in order, as before.
+        ...(getMany
+            ? {
+                getMany: (keys) => typed(() => Reflect.get(edge, "get") === own.get
+                    ? getMany(keys)
+                    : Effect.forEach(keys, (key) => current(edge, "get", own.get, [key], () => native.get(key)))),
+            }
+            : {}),
         set: (key, value, options) => current(edge, "set", own.set, [key, value, options], () => native.set(key, value, options)),
         delete: (key) => current(edge, "delete", own.delete, [key], () => native.delete(key)),
         list: (prefix) => current(edge, "list", own.list, [prefix], () => native.list(prefix)),

package/dist/runtime/request-reads.js

@@ -0,0 +1,207 @@
+// Request-scoped memo of storage reads (INV-7).
+//
+// One request often reads the same key many times: a catalog listing reads its
+// generation at each step, and status, drift and detail views each open the
+// same credential. A call site that has argued staleness
+// within one request is safe reads through `RequestReads.read`; every other
+// read stays a plain storage read. The memo belongs to one request owner,
+// holds plain strings only, and is emptied when the request closes. Nothing in
+// it crosses requests: each request owner has its own. Entries are keyed by
+// the physical key in the underlying store, through any namespaced views, so
+// one principal's partition never answers another's and two views of the same
+// partition share one entry.
+//
+// Freshness. Every write through a store connecta can observe — the SQL
+// drivers, `memoryStorage()`, and namespaced views over them — tells each open
+// memo over that store, in this isolate, that its key is changing: before the
+// write is submitted and again when it settles. The memo drops that key, and
+// a read of it already in flight is not recorded, since it may or may not
+// include the write. So a write by this request, or by any other request in
+// this isolate, is never hidden by a memoized value. A store whose writes
+// connecta cannot observe (a custom adapter, or a built-in one whose methods
+// were replaced) is never memoized. Writes in another isolate or process, and
+// expiry within the request, are invisible here: a memoized key can lag them
+// for the rest of the request. So no read that gates authority, sends a
+// credential or decides a write may be memoized; a call site that memoizes
+// must say why that staleness is safe.
+//
+// A `fresh` read bypasses the lookup and records what it saw, so a memoized
+// reader never returns a value older than this request's latest fresh read of
+// the same key. Only the latest read of a key this request started records:
+// an earlier read that settles later, possibly from before another isolate's
+// write, never replaces a newer observation.
+//
+// The registry of open memos holds weak references, so a request owner that is
+// never closed cannot pin its memo. A runtime without `WeakRef` and
+// `FinalizationRegistry` (workerd before compatibility date 2025-05-05 without
+// `enable_weak_ref`) memoizes nothing: every read goes to storage.
+import { Effect } from "effect";
+const roots = new WeakMap();
+const observed = new WeakMap();
+/**
+ * Open memos holding or reading entries of each store. Weak, so a request
+ * owner that is never closed still lets its memo be collected with it.
+ */
+const open = new WeakMap();
+function eachOpen(store, visit) {
+    const memos = open.get(store);
+    if (!memos)
+        return;
+    for (const ref of memos) {
+        const memo = ref.deref();
+        if (memo)
+            visit(memo);
+        else
+            memos.delete(ref);
+    }
+}
+/** A write to `key` of `store` is about to be submitted, or has settled. */
+export function noteStorageWrite(store, key) {
+    eachOpen(store, (memo) => memo.changed(store, key));
+}
+/** Wrap one write so open memos see it begin and settle, however it ends. */
+export function observedWrite(store, key, write) {
+    return Effect.suspend(() => {
+        noteStorageWrite(store, key);
+        return write;
+    }).pipe(Effect.ensuring(Effect.sync(() => noteStorageWrite(store, key))));
+}
+/**
+ * Declare that every write through `storage` reaches `noteStorageWrite` for
+ * `root`, as long as its methods stay the ones it has now; or that `storage`
+ * stores `key` at `prefix + key` in another store, observed only while that
+ * one is.
+ */
+export function observeStorageWrites(storage, layer) {
+    if ("root" in layer)
+        roots.set(layer.root, storage);
+    observed.set(storage, {
+        own: {
+            get: storage.get,
+            set: storage.set,
+            delete: storage.delete,
+            list: storage.list,
+            compareAndSet: storage.compareAndSet,
+        },
+        layer,
+    });
+    return storage;
+}
+/** The underlying store and key a read of `key` reaches, when every layer is observed. */
+function physical(storage, key) {
+    const entry = observed.get(storage);
+    if (!entry)
+        return undefined;
+    const { own, layer } = entry;
+    if (own.get !== storage.get ||
+        own.set !== storage.set ||
+        own.delete !== storage.delete ||
+        own.list !== storage.list ||
+        own.compareAndSet !== storage.compareAndSet)
+        return undefined;
+    return "root" in layer ? { store: layer.root, key } : physical(layer.storage, layer.prefix + key);
+}
+const weakReferences = () => typeof WeakRef === "function" && typeof FinalizationRegistry === "function";
+export class RequestReads {
+    closed = false;
+    stores = new Map();
+    ref = weakReferences() ? new WeakRef(this) : undefined;
+    entriesFor(store) {
+        let entries = this.stores.get(store);
+        if (!entries) {
+            entries = { values: new Map(), versions: new Map(), started: new Map() };
+            this.stores.set(store, entries);
+            eachOpen(store, () => { }); // prune collected memos
+            let memos = open.get(store);
+            if (!memos)
+                open.set(store, (memos = new Set()));
+            memos.add(this.ref);
+        }
+        return entries;
+    }
+    /** A write notice: forget `key` and refuse any read of it in flight. */
+    changed(store, key) {
+        const entries = this.stores.get(store);
+        if (!entries)
+            return;
+        entries.values.delete(key);
+        entries.versions.set(key, (entries.versions.get(key) ?? 0) + 1);
+    }
+    /** A memoized answer, or how to record the value a storage read returns. */
+    lookup(storage, key, fresh) {
+        const address = this.closed || !this.ref ? undefined : physical(storage, key);
+        if (!address)
+            return undefined;
+        const entries = this.entriesFor(address.store);
+        if (!fresh && entries.values.has(address.key))
+            return { hit: true, value: entries.values.get(address.key) };
+        const before = entries.versions.get(address.key) ?? 0;
+        const read = (entries.started.get(address.key) ?? 0) + 1;
+        entries.started.set(address.key, read);
+        return {
+            hit: false,
+            record: (value) => {
+                if (!this.closed &&
+                    entries.started.get(address.key) === read &&
+                    (entries.versions.get(address.key) ?? 0) === before)
+                    entries.values.set(address.key, value);
+            },
+        };
+    }
+    /**
+     * `load` reads `key` from `storage`. Without `fresh`, a value this request
+     * already read, with no observed write to that key since, answers instead.
+     */
+    read(storage, key, load, fresh = false) {
+        return Effect.suspend(() => {
+            const found = this.lookup(storage, key, fresh);
+            if (!found)
+                return load;
+            if (found.hit)
+                return Effect.succeed(found.value);
+            return Effect.tap(load, (value) => Effect.sync(() => found.record(value)));
+        });
+    }
+    /** Prefetch only keys whose callers already permit request-local staleness. */
+    prefetch(requests, load) {
+        return Effect.suspend(() => {
+            const pending = requests.map(({ storage, key }) => ({
+                address: physical(storage, key),
+                found: this.lookup(storage, key, false),
+            }));
+            const root = pending[0]?.address?.store;
+            const storage = root && roots.get(root);
+            if (!storage || pending.some(({ address, found }) => !found || address?.store !== root))
+                return Effect.void;
+            const misses = pending.filter(({ found }) => found && !found.hit);
+            if (!misses.length)
+                return Effect.void;
+            return Effect.map(load(storage, misses.map(({ address }) => address.key)), (values) => {
+                misses.forEach(({ found }, i) => {
+                    if (found && !found.hit)
+                        found.record(values[i] ?? null);
+                });
+            });
+        });
+    }
+    /** `read` for a Promise-shaped caller, without another Effect edge. */
+    async readPromise(storage, key, load, fresh = false) {
+        const found = this.lookup(storage, key, fresh);
+        if (!found)
+            return load();
+        if (found.hit)
+            return found.value;
+        const value = await load();
+        found.record(value);
+        return value;
+    }
+    close() {
+        if (this.closed)
+            return;
+        this.closed = true;
+        for (const store of this.stores.keys())
+            if (this.ref)
+                open.get(store)?.delete(this.ref);
+        this.stores.clear();
+    }
+}

package/dist/runtime/request-scope.js

@@ -1,6 +1,7 @@
 // One owner per existing upstream request identity. Facts survive revocation;
 // retaining them never reconstitutes a call capability or a live operation.
 import { Context, Exit, Scope } from "effect";
+import { RequestReads } from "./request-reads.js";
 import { detach } from "./run.js";
 export class RequestOwner {
     identity;
@@ -18,6 +19,7 @@ export class RequestOwner {
         secrets: undefined,
         invocations: { entered: [], authFailures: new Map(), retryReads: new Map() },
         handoffs: undefined,
+        reads: undefined,
     };
     constructor(identity) {
         this.identity = identity;
@@ -51,6 +53,7 @@ export class RequestOwner {
         }
         this.calls.clear();
         this.entries.clear();
+        this.retained.reads?.close();
         attempt(() => this.controller.abort(new Error("The request ended.")));
         for (const finalizer of this.finalizers.splice(0).reverse())
             attempt(finalizer);
@@ -61,6 +64,19 @@ export class RequestOwner {
             throw new AggregateError(failures, `Closing the request: ${failures.length} cleanup step(s) failed.`);
     }
 }
+/** This request's read memo; a closed request's memo answers nothing. */
+export function requestReads(identity) {
+    return ownerReads(requestOwner(identity));
+}
+export function ownerReads(owner) {
+    const retained = owner.retained;
+    if (!retained.reads) {
+        retained.reads = new RequestReads();
+        if (!owner.open)
+            retained.reads.close();
+    }
+    return retained.reads;
+}
 export class RequestScope extends Context.Service()("connecta/request/Scope") {
 }
 const requests = new WeakMap();

package/dist/runtime/storage.js

@@ -32,6 +32,18 @@ export function storageGet(key) {
             catch: (error) => error,
         }));
 }
+/**
+ * Read several keys, in one round trip when the store can; otherwise one
+ * `get` after another. Values come back in `keys` order.
+ */
+export function storageGetMany(keys) {
+    return Storage.use((storage) => {
+        const native = getNativeStorage(storage);
+        if (native?.getMany)
+            return native.getMany(keys);
+        return Effect.forEach(keys, (key) => storageGet(key).pipe(Effect.provideService(Storage, storage)));
+    });
+}
 /** Write one key, with the adapter's optional TTL. */
 export function storageSet(key, value, options) {
     return Storage.use((storage) => getNativeStorage(storage)?.set(key, value, options) ??