@theoremjs/react 0.0.0-stage → 0.3.1

package/hooks/use-theorem-host.js

@@ -0,0 +1,135 @@
+import { toolCallsOf, toolSnapshotFromEvents } from '@theoremjs/agents/interface';
+import { useCallback, useEffect, useMemo, useRef, useState } from 'react';
+import { clientFailure } from "../client/failure.js";
+import { withPageToolDispatch } from "../client/page-dispatch.js";
+import { continueGatedToolInvocation } from "../client/tool-resume.js";
+import { issuedOperationId } from "../client/turn-client.js";
+import { useDescribed } from "./use-described.js";
+function callId() {
+    return typeof crypto !== 'undefined' && 'randomUUID' in crypto
+        ? crypto.randomUUID()
+        : `call-${Date.now().toString(36)}-${Math.random().toString(36).slice(2, 10)}`;
+}
+function withEvent(call, event) {
+    const events = [...call.events, event];
+    const progress = event.type === 'tool' && event.tool.phase === 'progress' ? event.tool.data : call.progress;
+    return { ...call, events, call: toolCallsOf(events)[0] ?? null, progress };
+}
+/**
+ * One host profile: describe it once, then `run(name, input)` any of its tools
+ * as often as needed, and answer the gates a call pauses on. `run` returns the
+ * call's id at once; calls run side by side, and `cancel` stops one.
+ */
+export function useTheoremHost(source, pageTools) {
+    const transport = useMemo(() => withPageToolDispatch(source, pageTools), [source, pageTools]);
+    const { iface, describeFailure } = useDescribed(transport);
+    const [calls, setCalls] = useState([]);
+    const running = useRef(new Map());
+    const permissions = useRef([]);
+    const latest = useRef(calls);
+    latest.current = calls;
+    useEffect(() => {
+        const open = running.current;
+        return () => {
+            for (const controller of open.values())
+                controller.abort();
+        };
+    }, []);
+    const update = useCallback((id, change) => {
+        setCalls((previous) => previous.map((call) => (call.id === id ? change(call) : call)));
+    }, []);
+    /** Streams one request's events into the call, then marks it settled or failed. */
+    const stream = useCallback(async (id, send) => {
+        const controller = new AbortController();
+        running.current.set(id, controller);
+        const started = performance.now();
+        update(id, (call) => ({ ...call, isRunning: true, failure: null }));
+        try {
+            await send((event) => {
+                if (event.type === 'unsupported' || event.type === 'malformed')
+                    return;
+                update(id, (call) => withEvent(call, event));
+            }, controller.signal);
+            update(id, (call) => ({
+                ...call,
+                isRunning: false,
+                answering: null,
+                elapsedMs: performance.now() - started,
+            }));
+        }
+        catch (err) {
+            const failure = controller.signal.aborted ? null : clientFailure(err);
+            update(id, (call) => ({
+                ...call,
+                isRunning: false,
+                answering: null,
+                failure,
+                elapsedMs: performance.now() - started,
+            }));
+        }
+        finally {
+            if (running.current.get(id) === controller)
+                running.current.delete(id);
+        }
+    }, [update]);
+    const run = useCallback((name, input) => {
+        const id = callId();
+        setCalls((previous) => [
+            {
+                id,
+                name,
+                input,
+                events: [],
+                call: null,
+                progress: undefined,
+                isRunning: true,
+                failure: null,
+                answering: null,
+                startedAt: Date.now(),
+                elapsedMs: null,
+            },
+            ...previous,
+        ]);
+        void stream(id, (onEvent, signal) => transport.call({ name, input }, onEvent, signal));
+        return id;
+    }, [stream, transport]);
+    const answer = useCallback(async (id, resolution) => {
+        const held = latest.current.find((call) => call.id === id);
+        const state = held?.call?.state;
+        if (!held?.call || state?.phase !== 'gate')
+            return;
+        const gateId = held.call.callId;
+        const operationId = issuedOperationId(held.call);
+        const reply = continueGatedToolInvocation({
+            toolName: held.name,
+            gate: state.gate,
+            sessionPermissions: permissions.current,
+            resolution,
+        });
+        if (reply.decision === 'approve')
+            permissions.current = reply.sessionPermissions;
+        const snapshot = toolSnapshotFromEvents(held.events);
+        update(id, (call) => ({ ...call, answering: resolution.action }));
+        await stream(id, (onEvent, signal) => transport.invoke({
+            gateId,
+            operationId,
+            decision: reply.decision,
+            ...(reply.decision === 'approve' && reply.secret !== undefined
+                ? { secret: reply.secret }
+                : {}),
+            // why: A host without sessions (the studio) replays the paused call; others ignore it.
+            replay: {
+                name: held.name,
+                input: state.gate.preparedArguments ?? held.input,
+                gateKind: state.gate.kind,
+                sessionPermissions: permissions.current,
+                ...(snapshot ? { snapshot } : {}),
+            },
+        }, onEvent, signal));
+    }, [stream, transport, update]);
+    const cancel = useCallback((id) => {
+        running.current.get(id)?.abort();
+        running.current.delete(id);
+    }, []);
+    return { iface, describeFailure, calls, run, answer, cancel };
+}

package/hooks/use-theorem-interface.d.ts

@@ -0,0 +1,22 @@
+import type { ProfileInterface } from '@theoremjs/agents/interface';
+import type { ClientFailure } from '../client/failure.ts';
+import type { TheoremTransport } from '../client/transport.ts';
+/** `failure` is worded with the default labels: the profile's is not known until it loads. */
+export type TheoremInterfaceState = {
+    status: 'loading';
+    iface: null;
+    failure: null;
+} | {
+    status: 'ready';
+    iface: ProfileInterface;
+    failure: null;
+} | {
+    status: 'error';
+    iface: null;
+    failure: ClientFailure;
+};
+/**
+ * Ask the transport for the host profile's client-safe interface. A new transport keeps the last
+ * interface up until it describes itself, as {@link useDescribed} does.
+ */
+export declare function useTheoremInterface(transport: TheoremTransport): TheoremInterfaceState;

package/hooks/use-theorem-interface.js

@@ -0,0 +1,15 @@
+import { useMemo } from 'react';
+import { useDescribed } from "./use-described.js";
+const LOADING = { status: 'loading', iface: null, failure: null };
+/**
+ * Ask the transport for the host profile's client-safe interface. A new transport keeps the last
+ * interface up until it describes itself, as {@link useDescribed} does.
+ */
+export function useTheoremInterface(transport) {
+    const { iface, describeFailure } = useDescribed(transport);
+    return useMemo(() => {
+        if (describeFailure)
+            return { status: 'error', iface: null, failure: describeFailure };
+        return iface ? { status: 'ready', iface, failure: null } : LOADING;
+    }, [iface, describeFailure]);
+}

package/hooks/use-trace-records.d.ts

@@ -0,0 +1,4 @@
+import type { TraceRecord } from '@theoremjs/agents';
+import type { TraceFeed } from '../client/trace-feed.ts';
+/** The records a feed has delivered so far; none without a feed. */
+export declare function useTraceRecords(feed: TraceFeed | undefined): readonly TraceRecord[];

package/hooks/use-trace-records.js

@@ -0,0 +1,7 @@
+import { useSyncExternalStore } from 'react';
+const NONE = [];
+const noSubscription = () => () => { };
+/** The records a feed has delivered so far; none without a feed. */
+export function useTraceRecords(feed) {
+    return useSyncExternalStore(feed?.subscribe ?? noSubscription, feed?.records ?? (() => NONE));
+}

package/index.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Headless React bindings for Theorem — hooks and a transport, no styling.
+ *
+ * - `@theoremjs/react`         hooks + transport (this entry)
+ * - `@theoremjs/react/ui`      Astryx chat UI built on these hooks
+ * - `@theoremjs/react/server`  `createTheoremHandler` (and `createTheoremDecisionHandler`, `createTheoremEmbeddingHandler`, `createTheoremHostHandler`) for the host side
+ *
+ * @module
+ */
+export * from './client/index.ts';
+export { type PageDispatchResult, withPageToolDispatch } from './client/page-dispatch.ts';
+export { type EmbeddingIndex, type IndexProgress, useEmbeddingIndex, } from './hooks/use-embedding-index.ts';
+export { type SentTurn, type UseTheoremChatOptions, useTheoremChat, } from './hooks/use-theorem-chat.ts';
+export { type TheoremDecisionState, useTheoremDecision } from './hooks/use-theorem-decision.ts';
+export { type TheoremEmbeddingState, useTheoremEmbedding, } from './hooks/use-theorem-embedding.ts';
+export { type TheoremHostCall, type TheoremHostState, useTheoremHost, } from './hooks/use-theorem-host.ts';
+export { type TheoremInterfaceState, useTheoremInterface } from './hooks/use-theorem-interface.ts';

package/index.js

@@ -0,0 +1,17 @@
+/**
+ * Headless React bindings for Theorem — hooks and a transport, no styling.
+ *
+ * - `@theoremjs/react`         hooks + transport (this entry)
+ * - `@theoremjs/react/ui`      Astryx chat UI built on these hooks
+ * - `@theoremjs/react/server`  `createTheoremHandler` (and `createTheoremDecisionHandler`, `createTheoremEmbeddingHandler`, `createTheoremHostHandler`) for the host side
+ *
+ * @module
+ */
+export * from "./client/index.js";
+export { withPageToolDispatch } from "./client/page-dispatch.js";
+export { useEmbeddingIndex, } from "./hooks/use-embedding-index.js";
+export { useTheoremChat, } from "./hooks/use-theorem-chat.js";
+export { useTheoremDecision } from "./hooks/use-theorem-decision.js";
+export { useTheoremEmbedding, } from "./hooks/use-theorem-embedding.js";
+export { useTheoremHost, } from "./hooks/use-theorem-host.js";
+export { useTheoremInterface } from "./hooks/use-theorem-interface.js";

package/live.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Live (voice / video) runner, on the Astryx UI in the Theorem theme.
+ *
+ * @module
+ */
+export type { LiveCallOptions, PageTool, PageToolAnswer, PageTools, } from './client/live/live-page-tool.ts';
+export type { LiveConnection } from './client/live-client.ts';
+export type { LiveRunnerProps } from './ui/LiveRunner.tsx';
+export { LiveRunner } from './ui/LiveRunner.tsx';

package/live.js

@@ -0,0 +1,10 @@
+/**
+ * Live (voice / video) runner, on the Astryx UI in the Theorem theme.
+ *
+ * @module
+ */
+// why: Astryx's documented order: reset → components → theme.
+import '@astryxdesign/core/reset.css';
+import '@astryxdesign/core/astryx.css';
+import './ui/built/theme.css';
+export { LiveRunner } from "./ui/LiveRunner.js";

package/package.json

@@ -1,6 +1,76 @@
 {
   "name": "@theoremjs/react",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.3.1",
+  "description": "React bindings for Theorem: headless hooks + transport, an Astryx chat UI, and a Web-standard server handler.",
+  "license": "MIT",
+  "type": "module",
+  "engines": {
+    "node": ">=20"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/masudl-hub/theoremai.git",
+    "directory": "react"
+  },
+  "sideEffects": [
+    "**/*.css",
+    "./live.js",
+    "./ui/index.js"
+  ],
+  "exports": {
+    ".": {
+      "types": "./index.d.ts",
+      "default": "./index.js"
+    },
+    "./ui": {
+      "types": "./ui/index.d.ts",
+      "default": "./ui/index.js"
+    },
+    "./ui/theme": {
+      "types": "./ui/theorem-theme.d.ts",
+      "default": "./ui/theorem-theme.js"
+    },
+    "./ui/icons": {
+      "types": "./ui/icons.d.ts",
+      "default": "./ui/icons.js"
+    },
+    "./server": {
+      "types": "./server/mod.d.ts",
+      "default": "./server/mod.js"
+    },
+    "./live": {
+      "types": "./live.d.ts",
+      "default": "./live.js"
+    },
+    "./client": {
+      "types": "./client/index.d.ts",
+      "default": "./client/index.js"
+    },
+    "./styles/*": "./styles/*"
+  },
+  "dependencies": {
+    "@speed-highlight/core": "2.1.0",
+    "@tabler/icons-react": "^3.46.0",
+    "intl-messageformat": "^11.2.9",
+    "recharts": "^3.10.1"
+  },
+  "peerDependencies": {
+    "@astryxdesign/core": "0.7.0",
+    "@astryxdesign/theme-neutral": "0.7.0",
+    "@stylexjs/stylex": "0.19.0",
+    "react": "^19.0.0",
+    "react-dom": "^19.0.0",
+    "@theoremjs/agents": "^0.3.1"
+  },
+  "peerDependenciesMeta": {
+    "@astryxdesign/core": {
+      "optional": true
+    },
+    "@astryxdesign/theme-neutral": {
+      "optional": true
+    },
+    "@stylexjs/stylex": {
+      "optional": true
+    }
+  }
+}

package/server/checkpoint-ownership.d.ts

@@ -0,0 +1,6 @@
+import { type ProviderCheckpoint, type TurnHistoryMessage } from '@theoremjs/agents';
+import type { TheoremSessionState } from './session-store.ts';
+export declare function checkpointIdentity(checkpoint: ProviderCheckpoint): Promise<string>;
+export declare function checkpointOwnershipKey(identity: string, operations: TheoremSessionState['operations']): Promise<string>;
+export declare function requireOwnedCheckpoint(identities: readonly string[], checkpoint: ProviderCheckpoint | undefined, operations?: TheoremSessionState['operations'], portableHistory?: readonly TurnHistoryMessage[]): Promise<ProviderCheckpoint | undefined>;
+export declare function retainedCheckpointIdentities(existing: readonly string[], added: readonly string[], limit: number): string[];

package/server/checkpoint-ownership.js

@@ -0,0 +1,42 @@
+import { labelText, providerCheckpointSchema, TheoremError, toolInvocationHash, } from '@theoremjs/agents';
+export function checkpointIdentity(checkpoint) {
+    return toolInvocationHash(providerCheckpointSchema.parse(checkpoint));
+}
+export async function checkpointOwnershipKey(identity, operations) {
+    const rows = Object.entries(operations)
+        .sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0))
+        .map(([id, operation]) => operation.status === 'ready'
+        ? [id, operation.status, operation.profileId, operation.readyAt]
+        : [id, operation.status, operation.profileId, operation.toolId, operation.invocationHash]);
+    const epoch = await toolInvocationHash(rows);
+    return `${identity}:${epoch}`;
+}
+export async function requireOwnedCheckpoint(identities, checkpoint, operations = {}, portableHistory) {
+    if (checkpoint === undefined)
+        return undefined;
+    const parsed = providerCheckpointSchema.parse(checkpoint);
+    const identity = await checkpointIdentity(parsed);
+    const key = await checkpointOwnershipKey(identity, operations);
+    const records = Object.values(operations);
+    const portableSettlements = portableHistory !== undefined &&
+        records.length > 0 &&
+        identities.some((saved) => saved.startsWith(`${identity}:`)) &&
+        records.every((operation) => operation.status === 'settled' &&
+            operation.outcome.effects !== 'unknown' &&
+            operation.outcome.event.tool.readBack !== undefined &&
+            portableHistory.some((message) => message.role === 'tool' &&
+                message.tool_call_id === operation.callId &&
+                message.name === operation.toolId &&
+                message.content === operation.outcome.event.tool.readBack));
+    if (!identities.includes(key) &&
+        !portableSettlements &&
+        !(records.length === 0 && identities.includes(identity))) {
+        throw new TheoremError('request', labelText('session.provider_state_unowned'), {
+            copy: { key: 'session.provider_state_unowned' },
+        });
+    }
+    return parsed;
+}
+export function retainedCheckpointIdentities(existing, added, limit) {
+    return [...new Set([...existing, ...added].reverse())].slice(0, limit).reverse();
+}

package/server/conversation-store.d.ts

@@ -0,0 +1,92 @@
+/**
+ * Where a chat's conversation lives for `createTheoremHandler`: the transcript
+ * the person reads and the history the model reads next. The host owns it; the
+ * browser holds only an opaque ref the store issued, and never sends history.
+ *
+ * A database store keys the conversation by its id. The sealed store keeps
+ * nothing: its ref is the conversation itself, encrypted and signed with the
+ * host's key, so the browser carries what it cannot read or change.
+ *
+ * @module
+ */
+import { type ProviderCheckpoint, TheoremError, type TurnEvent, type TurnHistoryMessage, z } from '@theoremjs/agents';
+import type { TranscriptBlock } from '@theoremjs/agents/interface';
+import { type MemorySessionStoreOptions } from './session-store.ts';
+/** A reply paused on gates: its events so far, and the history it was given. */
+export type PausedReply = {
+    events: TurnEvent[];
+    /** The history the reply was given; its events append to this when it commits. */
+    base: TurnHistoryMessage[];
+    /** How many of `events` `base` already holds: a compaction mid-reply moves the base. */
+    baseEvents: number;
+    /** How long the reply worked before it paused (ms), approval waits excluded. */
+    workedMs: number;
+    /** When the reply last paused (epoch ms). */
+    endedAt: number;
+    /** The model and effort the reply ran with, for the run that goes on after its gates. */
+    model?: string;
+    effort?: string;
+};
+/** One conversation as the host stores it. */
+export type StoredConversation = {
+    version: 1;
+    /** What the person reads, without the paused reply. */
+    transcript: TranscriptBlock[];
+    /** What the model reads on the next turn, compacted when the profile compacts. */
+    history: TurnHistoryMessage[];
+    providerState?: ProviderCheckpoint;
+    /** The last turn's input tokens, for the compaction meter. */
+    inputTokens?: number;
+    /** The history's size in tokens as the last compaction measured it. */
+    historyTokens?: number;
+    paused?: PausedReply;
+};
+/** A stored conversation as a host's own store reads it back. */
+export declare const storedConversationSchema: z.ZodType<StoredConversation>;
+/** An empty conversation: what a chat with no ref starts from. */
+export declare function emptyConversation(): StoredConversation;
+export interface ConversationSnapshot {
+    revision: string;
+    conversation: StoredConversation;
+}
+export type ConversationWriteResult = {
+    written: true;
+    ref: string;
+    revision: string;
+} | {
+    written: false;
+};
+/**
+ * Where conversations live. `ref` is the store's own: the handler hands it to
+ * the browser and back, and never reads it. Every read and write names the
+ * session, so a ref from another session opens nothing.
+ */
+export interface TheoremConversationStore {
+    /** The conversation, or undefined when this session has none under `ref`. */
+    read(sessionId: string, ref: string): Promise<ConversationSnapshot | undefined>;
+    /**
+     * Compare and replace. A null `ref` creates a conversation; otherwise the
+     * write lands only on a conversation this session can read, while its
+     * stored revision is still `expectedRevision`.
+     */
+    write(sessionId: string, ref: string | null, expectedRevision: string | null, next: StoredConversation): Promise<ConversationWriteResult>;
+}
+/** Refuses a ref the store does not know or cannot open: the browser reads `session.conversation_unknown`. */
+export declare function unknownConversation(cause?: unknown): TheoremError;
+/** Conversations in process memory: forgotten when idle, oldest evicted first. For one instance. */
+export declare function createMemoryConversationStore(options?: Omit<MemorySessionStoreOptions, 'sessionLimits'>): TheoremConversationStore;
+export type SealedConversationStoreOptions = {
+    /** Every sealing key still in use, by version: each at least 32 bytes, kept off the browser. */
+    keys: Readonly<Record<number, string>>;
+    /** The key that seals new writes. */
+    keyVersion: number;
+};
+/**
+ * A store for a host that keeps nothing. The ref is the conversation sealed
+ * with the host's key and bound to the session: the browser carries it and
+ * cannot read or change it, and it opens in no other session.
+ *
+ * It cannot tell an older seal from the newest, so an older seal opens: like a
+ * rewind, it returns a conversation the host wrote. Its revision is the seal.
+ */
+export declare function createSealedConversationStore(options: SealedConversationStoreOptions): TheoremConversationStore;

package/server/conversation-store.js

@@ -0,0 +1,131 @@
+/**
+ * Where a chat's conversation lives for `createTheoremHandler`: the transcript
+ * the person reads and the history the model reads next. The host owns it; the
+ * browser holds only an opaque ref the store issued, and never sends history.
+ *
+ * A database store keys the conversation by its id. The sealed store keeps
+ * nothing: its ref is the conversation itself, encrypted and signed with the
+ * host's key, so the browser carries what it cannot read or change.
+ *
+ * @module
+ */
+import { labelText, providerCheckpointSchema, TheoremError, turnEventSchema, turnHistoryMessageSchema, z, } from '@theoremjs/agents';
+import { openSecret, sealSecret } from '@theoremjs/agents/kernel';
+import { transcriptBlockSchema } from "../client/transcript-schema.js";
+import { memoryStoreLimits } from "./session-store.js";
+const pausedReply = z.object({
+    events: z.array(turnEventSchema),
+    base: z.array(turnHistoryMessageSchema),
+    baseEvents: z.number().int().nonnegative(),
+    workedMs: z.number().nonnegative(),
+    endedAt: z.number(),
+    model: z.string().optional(),
+    effort: z.string().optional(),
+});
+true;
+const storedConversation = z.object({
+    version: z.literal(1),
+    transcript: z.array(transcriptBlockSchema),
+    history: z.array(turnHistoryMessageSchema),
+    providerState: providerCheckpointSchema.optional(),
+    inputTokens: z.number().optional(),
+    historyTokens: z.number().optional(),
+    paused: pausedReply.optional(),
+});
+true;
+/** A stored conversation as a host's own store reads it back. */
+export const storedConversationSchema = storedConversation;
+/** An empty conversation: what a chat with no ref starts from. */
+export function emptyConversation() {
+    return { version: 1, transcript: [], history: [] };
+}
+/** Refuses a ref the store does not know or cannot open: the browser reads `session.conversation_unknown`. */
+export function unknownConversation(cause) {
+    return new TheoremError('request', labelText('session.conversation_unknown'), {
+        copy: { key: 'session.conversation_unknown' },
+        ...(cause === undefined ? {} : { cause }),
+    });
+}
+/** Conversations in process memory: forgotten when idle, oldest evicted first. For one instance. */
+export function createMemoryConversationStore(options = {}) {
+    const { ttlMs, maxSessions } = memoryStoreLimits(options);
+    const conversations = new Map();
+    const current = (sessionId, ref) => {
+        const entry = conversations.get(ref);
+        if (!entry || entry.sessionId !== sessionId)
+            return undefined;
+        if (Date.now() - entry.touched >= ttlMs) {
+            conversations.delete(ref);
+            return undefined;
+        }
+        return entry.snapshot;
+    };
+    const written = (...[sessionId, ref, expectedRevision, next]) => {
+        const snapshot = ref === null ? undefined : current(sessionId, ref);
+        // invariant: A ref this session cannot read takes no write, so no session overwrites another's conversation.
+        if (ref !== null && snapshot === undefined)
+            return { written: false };
+        if ((snapshot?.revision ?? null) !== expectedRevision)
+            return { written: false };
+        const conversation = storedConversation.parse(next);
+        const key = ref ?? crypto.randomUUID();
+        const revision = crypto.randomUUID();
+        conversations.delete(key);
+        conversations.set(key, {
+            sessionId,
+            snapshot: { revision, conversation: structuredClone(conversation) },
+            touched: Date.now(),
+        });
+        while (conversations.size > maxSessions) {
+            const oldest = conversations.keys().next().value;
+            if (oldest === undefined)
+                break;
+            conversations.delete(oldest);
+        }
+        return { written: true, ref: key, revision };
+    };
+    return {
+        read: (sessionId, ref) => Promise.resolve(structuredClone(current(sessionId, ref))),
+        // why: A write that fails its check rejects, as any store's does, rather than throwing at the call.
+        write: (...args) => new Promise((resolve) => resolve(written(...args))),
+    };
+}
+/**
+ * A store for a host that keeps nothing. The ref is the conversation sealed
+ * with the host's key and bound to the session: the browser carries it and
+ * cannot read or change it, and it opens in no other session.
+ *
+ * It cannot tell an older seal from the newest, so an older seal opens: like a
+ * rewind, it returns a conversation the host wrote. Its revision is the seal.
+ */
+export function createSealedConversationStore(options) {
+    const sealKey = options.keys[options.keyVersion];
+    if (sealKey === undefined) {
+        throw new TheoremError('config', labelText('error.config'), {
+            cause: { code: 'conversation_seal_key_missing', keyVersion: options.keyVersion },
+        });
+    }
+    return {
+        async read(sessionId, ref) {
+            const plaintext = await openSecret({ sealed: ref, keys: options.keys, binding: [sessionId] })
+                // why: A seal that does not open is a ref this session does not own; the caller refuses it.
+                .catch(() => undefined);
+            if (plaintext === undefined)
+                return undefined;
+            const conversation = storedConversation.parse(JSON.parse(plaintext));
+            return { revision: ref, conversation };
+        },
+        async write(sessionId, ref, expectedRevision, next) {
+            if (ref !== expectedRevision)
+                return { written: false };
+            const conversation = storedConversation.parse(next);
+            const sealed = await sealSecret({
+                plaintext: JSON.stringify(conversation),
+                key: sealKey,
+                binding: [sessionId],
+                keyVersion: options.keyVersion,
+            });
+            return { written: true, ref: sealed, revision: sealed };
+        },
+    };
+}