@serfab/quereus-plugin-sereus 1.18.0 → 1.19.1

package/src/compose-strand.ts

@@ -1,11 +1,15 @@
 import debug from 'debug';
 import type { Database, VTablePluginInfo, FunctionPluginInfo, CollationPluginInfo } from '@quereus/quereus';
 import optimysticPlugin from '@optimystic/quereus-plugin-optimystic/plugin';
-import type { SqlCommitDurabilityListener, CommitFullyHeldListener } from '@optimystic/quereus-plugin-optimystic/plugin';
+import type { SqlCommitDurabilityListener, CommitFullyHeldListener, OfflineConfig, OfflineMode } from '@optimystic/quereus-plugin-optimystic/plugin';
 import type { Libp2p } from '@libp2p/interface';
 import type { IRepo } from '@optimystic/db-core';
-import type { IRawStorage, NodeOptions } from '@optimystic/db-p2p';
-import type { StrandConnectionOptions, SereusPluginResult, StrandTransactor, Libp2pNodeWithRepo } from './types.js';
+import type { IKVStore, IRawStorage, NodeOptions } from '@optimystic/db-p2p';
+import type {
+	StrandConnectionOptions, SereusPluginResult, StrandTransactor, Libp2pNodeWithRepo,
+	StrandOfflineOptions, StrandOfflineController,
+} from './types.js';
+import { applyAppSchemaAfterQueue, type AppSchemaApply } from './app-schema.js';
 import { STRAND_SCHEMA } from './strand-schema.js';
 import { resolveStrandClusterSize, STRAND_CLUSTER_POLICY } from './cluster-size.js';
 import { wrapStorageWithCache, disposeStorageCache } from './cached-storage.js';
@@ -17,6 +21,18 @@ const timing = debug('sereus:plugin:strand:timing');
 /** The schemas whose tables a strand founder gives a collection: strand membership, then the sApp's. */
 const FOUNDED_SCHEMAS = ['Strand', 'App'] as const;
 
+/** The offline controller of each live strand composition composed with `offline`, by its `Database`. */
+const offlineControllers = new WeakMap<Database, StrandOfflineController>();
+
+/**
+ * The offline controller of the live strand composition over `db`, or `undefined` when it was
+ * composed without `offline`, has shut down, or `db` is no strand composition. For Sereus's own
+ * writers, which are handed a bare `Database` and must see whether its queue holds transactions.
+ */
+export function offlineControllerOf(db: Database): StrandOfflineController | undefined {
+	return offlineControllers.get(db);
+}
+
 /**
  * Minimal interface for the CollectionFactory returned by the optimystic plugin.
  * We only need the methods this composition actually uses.
@@ -30,17 +46,22 @@ interface CollectionFactory {
 }
 
 /**
- * Release a composition's hold on the optimystic plugin. The transaction bridge goes first: its
- * durability follower subscribes to the node's `StorageRepo`, and cadre-core keeps a strand's node
- * across a database rebuild, so a bridge never disposed stays subscribed once per rebuild. Then the
- * collection factory: a node the composition created is stopped with it; an injected node is left
- * running, because it belongs to the caller — cadre-core keeps a strand's node up across a failed
- * database build and retries the build on it.
+ * Release a composition's hold on the optimystic plugin. The offline queue goes first: its drain
+ * keeps timers and may have a submission in flight, which reports its commit through the bridge's
+ * follower, so the bridge must outlive it (the plugin's own `dispose()` orders them the same way).
+ * A queue `hydrate` restored before a failed composition is stopped here too. Then the transaction
+ * bridge: its durability follower subscribes to the node's `StorageRepo`, and cadre-core keeps a
+ * strand's node across a database rebuild, so a bridge never disposed stays subscribed once per
+ * rebuild. Then the collection factory: a node the composition created is stopped with it; an
+ * injected node is left running, because it belongs to the caller — cadre-core keeps a strand's
+ * node up across a failed database build and retries the build on it.
  *
- * Disposes the bridge itself rather than calling the plugin's `dispose()`, which would release the
- * factory a second time on the created-node path (`shutdown()` ends with the same `dispose()`).
+ * Disposes the queue and bridge itself rather than calling the plugin's `dispose()`, which would
+ * release the factory a second time on the created-node path (`shutdown()` ends with the same
+ * `dispose()`).
  */
 async function releaseOptimysticPlugin(plugin: OptimysticPluginResult, createdNode: Libp2p | null): Promise<void> {
+	await plugin.offline.dispose();
 	// NOTE: the bridge's follower re-subscribes at the start of any transaction, so a write begun on
 	// this `Database` after release (before its owner closes it) subscribes again and nothing
 	// releases it. cadre-core stops its own writers before releasing; if an app write in flight at
@@ -84,6 +105,8 @@ interface OptimysticPluginResult {
 	 * {@link createEmptyCollections}).
 	 */
 	txnBridge: { dispose(): void } & CollectionRegistrySource;
+	/** The offline queue, constructed on every registration; idle until something is queued. */
+	offline: OfflineMode;
 	[key: string]: unknown;
 }
 
@@ -170,6 +193,13 @@ export interface StrandPlatform {
 	 * default to IndexedDB so a reload survives.
 	 */
 	resolveStorage?(ctx: ResolveStorageContext): Promise<IRawStorage | undefined> | IRawStorage | undefined;
+	/**
+	 * The store to journal offline transactions in when `options.offline` names no `journal`.
+	 * Called after {@link resolveStorage}, only when `options.offline` is given. Optional — when
+	 * omitted, or when it answers `undefined`, the queue lives in memory (Node). The browser answers
+	 * a store over the IndexedDB database it defaulted the strand's storage to.
+	 */
+	defaultOfflineJournal?(): IKVStore | undefined;
 	/**
 	 * Create a libp2p node. Called only when no node is injected and the
 	 * transactor needs one. Node creates a TCP node via `@optimystic/db-p2p`;
@@ -264,6 +294,7 @@ export async function composeStrand(
 			networkName,
 			enableCache,
 			storage,
+			offline: options.offline && strandOfflineConfig(strandId, options.offline, platform),
 		});
 	} catch (err) {
 		await releaseStorageCache();
@@ -271,6 +302,13 @@ export async function composeStrand(
 	}
 
 	const { collectionFactory } = pluginResult;
+	const offline: StrandOfflineController | undefined = options.offline && pluginResult.offline;
+	if (offline) {
+		offlineControllers.set(db, offline);
+	}
+	// Aborted by `shutdown`, so a deferred sApp schema apply still waiting settles `cancelled`.
+	const released = new AbortController();
+	let appSchemaApply: AppSchemaApply | undefined;
 
 	let createdNode: Libp2p | null = null;
 	let hydrated: { tables: number; indexes: number } | undefined;
@@ -346,6 +384,13 @@ export async function composeStrand(
 		// nothing here writes membership rows. Founder bootstrap (Header, founding
 		// Manager/Member, invite/peer flows) is owned by the lifecycle ticket
 		// `strand-membership-lifecycle-population`.
+		//
+		// NOTE: unlike step 7, this apply is not deferred behind the offline queue. Every `Strand`
+		// table is tagged `"optimystic.offline" = 'network'`, so the only queued transactions that
+		// write one are network-acknowledged commits waiting behind app transactions, and the only
+		// change this schema has made since is a tag, which the queue does not refuse. If a
+		// later strand schema changes how a table's rows are stored (an index, a column), this apply
+		// can be refused by `QueuedEntriesBlockSchemaChangeError` the same way and needs step 7's path.
 		log('Applying Strand membership schema for strand %s', strandId);
 		await db.exec(`
 			declare schema Strand {
@@ -371,13 +416,17 @@ export async function composeStrand(
 		// differ: once one has run, any later step that fails leaves the schema partially
 		// migrated instead of restored. No schema in this repo evolves that way, so this
 		// is a note for whoever first ships a migration that does.
+		//
+		// The one exception: an apply refused by queued offline transactions does not fail the
+		// connect. The strand comes up on the `App` schema it had, and the apply is retried as the
+		// queue drains (see `applyAppSchemaAfterQueue`).
 		if (schema) {
 			log('Applying sApp schema for strand %s', strandId);
-			await applyAppSchema(db, schema);
-			log('sApp schema applied');
+			appSchemaApply = await applyAppSchemaAfterQueue(db, schema, pluginResult.offline, released.signal);
 		}
 	} catch (err) {
 		// Clean up resources if setup fails after partial initialization.
+		offlineControllers.delete(db);
 		await releaseOptimysticPlugin(pluginResult, createdNode);
 		await releaseStorageCache();
 		throw err;
@@ -395,8 +444,15 @@ export async function composeStrand(
 		onCommitDurability: listener => pluginResult.onCommitDurability(listener),
 		onCommitFullyHeld: listener => pluginResult.onCommitFullyHeld(listener),
 		createEmptyCollections: except => createEmptyCollections(db, pluginResult.txnBridge, FOUNDED_SCHEMAS, except),
+		...(offline && { offline }),
+		...appSchemaApply,
 		async shutdown() {
 			log('Shutting down strand connection %s', strandId);
+			// NOTE: a deferred sApp schema apply already running is not awaited: it runs on against the
+			// released plugin, Quereus unwinds it when it fails, and `appSchema` settles `cancelled`. If
+			// that ever leaves a catalog write landing after close, await `appSchema` here first.
+			released.abort();
+			offlineControllers.delete(db);
 			await releaseOptimysticPlugin(pluginResult, createdNode);
 			await releaseStorageCache();
 			log('Strand connection %s shut down', strandId);
@@ -405,50 +461,23 @@ export async function composeStrand(
 }
 
 /**
- * Step 7 of {@link composeStrand}: declare the sApp's schema as `App` and apply it — a
- * declarative diff against the catalog, so re-applying a schema that is already in place
- * emits nothing. The one site that applies an `App` schema: `composeStrand` calls it at
- * bring-up, and cadre-core's `StrandDatabase.attachAppSchema` calls it on a live storage
- * replica when an app claims the strand. The database must already be composed (optimystic
- * set as the default vtab), or the tables land in memory instead of the strand.
- *
- * Refuses a schema holding an item the Quereus parser skipped: it keeps any item whose leading
- * keyword it does not model (`create unique index …`, a misspelled `tabel`, `domain`) as an
- * opaque placeholder that apply ignores, so the app would otherwise run without that item.
- *
- * Refuses a schema holding a `seed` item: the apply runs on every node of the strand at every
- * connect, so seed inserts would put a network write on each bring-up and two nodes inserting
- * the same key at once would collide. Rows an app needs at birth are the founding app's to write.
+ * The Optimystic plugin's `offline` block for this strand: the caller's options, the platform's
+ * journal when the caller named none, and the journal label, which the plugin refuses without one.
  */
-export async function applyAppSchema(db: Database, schema: string): Promise<void> {
-	await db.exec(`
-		declare schema App {
-			${schema}
-		}
-	`);
-	assertNoIgnoredItems(db);
-	assertNoSeedItems(db);
-	await db.exec('apply schema App;');
-}
-
-function declaredAppItems(db: Database) {
-	return db.declaredSchemaManager.getDeclaredSchema('App')?.items ?? [];
+function strandOfflineConfig(strandId: string, offline: StrandOfflineOptions, platform: StrandPlatform): OfflineConfig {
+	const journal = offline.journal ?? platform.defaultOfflineJournal?.();
+	return journal === undefined
+		? { ...offline }
+		: { ...offline, journal, journalLabel: strandJournalLabel(strandId) };
 }
 
-function assertNoIgnoredItems(db: Database): void {
-	const ignored = declaredAppItems(db).filter(item => item.type === 'declareIgnored').length;
-	if (ignored > 0) {
-		// Only a count: Quereus leaves an ignored item's source text empty.
-		throw new Error(`sApp schema has ${ignored} item(s) the parser does not recognize (a \`create …\` prefix or a misspelled item keyword such as \`tabel\`); items are \`table\`, \`index\`, \`unique index\`, \`view\`, \`materialized view\` and \`assertion\``);
-	}
-}
-
-function assertNoSeedItems(db: Database): void {
-	// Quereus refuses a second seed for one table at declare, so these names are distinct.
-	const tables = declaredAppItems(db).flatMap(item => item.type === 'declaredSeed' ? [item.tableName] : []);
-	if (tables.length > 0) {
-		throw new Error(`sApp schema has seed item(s) for table(s) ${tables.join(', ')}; Sereus does not apply seed rows to a strand — insert the rows an app needs at birth from the app when it founds the strand`);
-	}
+/**
+ * The offline journal label for a strand. A label is `[a-z0-9_-]` and a strand id `[a-z0-9._-]`, so
+ * `_` becomes `__` and `.` becomes `_d`: no two strand ids share a label, and two strands journaling
+ * into one store keep their records apart.
+ */
+function strandJournalLabel(strandId: string): string {
+	return `strand-${strandId.replaceAll('_', '__').replaceAll('.', '_d')}`;
 }
 
 /**
@@ -464,6 +493,7 @@ async function registerStrandPlugins(
 		networkName: string;
 		enableCache: boolean;
 		storage: IRawStorage | undefined;
+		offline: OfflineConfig | undefined;
 	},
 ): Promise<OptimysticPluginResult> {
 	await platform.registerCrypto(db);
@@ -481,9 +511,16 @@ async function registerStrandPlugins(
 		const storage = strand.storage;
 		pluginConfig.rawStorageFactory = () => storage;
 	}
+	// NOTE: `networkCommitTimeoutMs` is left at upstream's default (five minutes); nothing was
+	// measured to choose another. A network-acknowledged commit made while transactions are queued
+	// (any `Strand` write, all of them tagged 'network') waits that long behind them holding
+	// Quereus's execution lock. If that ever shows up as a frozen app, lower it for strands here.
+	if (strand.offline) {
+		pluginConfig.offline = strand.offline;
+	}
 	// The plugin's published signature is `Record<string, SqlValue>` but it also reads
-	// `rawStorageFactory` (a function reference) from the same map. Cast through unknown
-	// rather than widen the public type.
+	// `rawStorageFactory` (a function reference) and `offline` (an object) from the same
+	// map. Cast through unknown rather than widen the public type.
 	const pluginResult = optimysticPlugin(
 		db,
 		pluginConfig as unknown as Parameters<typeof optimysticPlugin>[1],

package/src/connect-browser.ts

@@ -3,7 +3,7 @@ import cryptoPlugin from '@optimystic/quereus-plugin-crypto/plugin';
 import { createLibp2pNode } from '@optimystic/db-p2p/rn';
 import { webSockets } from '@libp2p/websockets';
 import { circuitRelayTransport } from '@libp2p/circuit-relay-v2';
-import { IndexedDBRawStorage, openOptimysticWebDb } from '@optimystic/db-p2p-storage-web';
+import { IndexedDBKVStore, IndexedDBRawStorage, openOptimysticWebDb, type OptimysticWebDBHandle } from '@optimystic/db-p2p-storage-web';
 import type { Libp2p } from '@libp2p/interface';
 import type { StrandConnectionOptions, SereusPluginResult } from './types.js';
 import { composeStrand, applyRegistrations } from './compose-strand.js';
@@ -23,6 +23,8 @@ interface CryptoPluginResult {
  *  - crypto registered inline (no runtime `@quereus/quereus` import, so the
  *    bundle does not duplicate the host's instance),
  *  - storage defaulting to `IndexedDBRawStorage` keyed by `sereus-strand-<id>`,
+ *  - with `offline` given and no `journal`, the offline queue journaled into that same
+ *    IndexedDB database (its `kv` object store) when the storage was defaulted,
  *  - a node created via the TCP-free `@optimystic/db-p2p/rn` entry with explicit
  *    `webSockets()` + `circuitRelayTransport()` transports.
  */
@@ -30,6 +32,8 @@ export async function connectToStrandBrowser(
 	db: Database,
 	options: StrandConnectionOptions,
 ): Promise<SereusPluginResult> {
+	// The IndexedDB database the storage was defaulted to, if it was; the offline journal shares it.
+	let defaultedDb: OptimysticWebDBHandle | undefined;
 	return composeStrand(db, options, {
 		registerCrypto(database) {
 			applyRegistrations(database, cryptoPlugin(database, {}) as unknown as CryptoPluginResult);
@@ -39,8 +43,11 @@ export async function connectToStrandBrowser(
 			// Browsers always default to IndexedDB so a reload survives; the
 			// unit-test fake transactor needs no storage.
 			if (resolvedTransactor === 'test') return undefined;
-			const dbHandle = await openOptimysticWebDb(`sereus-strand-${strandId}`);
-			return new IndexedDBRawStorage(dbHandle);
+			defaultedDb = await openOptimysticWebDb(`sereus-strand-${strandId}`);
+			return new IndexedDBRawStorage(defaultedDb);
+		},
+		defaultOfflineJournal() {
+			return defaultedDb && new IndexedDBKVStore(defaultedDb);
 		},
 		async createNode({ networkName, bootstrapNodes, fretProfile, clusterSize, clusterPolicy, storage }) {
 			return createLibp2pNode({

package/src/index.ts

@@ -1,18 +1,30 @@
-export { connectToStrand } from './connect.js';
-export { applyAppSchema } from './compose-strand.js';
-export { createEmptyCollections, type CollectionRegistrySource } from './empty-collections.js';
-export {
-	MIN_CLUSTER_SIZE,
-	COHORT_READ_DEADLINE_MS,
-	CONTROL_REPLICATION_BREADTH,
-	CONTROL_CLUSTER_POLICY,
-	DEFAULT_STRAND_CLUSTER_SIZE,
-	STRAND_CLUSTER_POLICY,
-	resolveStrandClusterSize,
-	resolveRepairYardstick,
-	controlClusterPolicy,
-	strandClusterPolicy
-} from './cluster-size.js';
-export { wrapStorageWithCache, disposeStorageCache } from './cached-storage.js';
-export type { StrandConnectionOptions, SereusPluginResult, StrandTransactor } from './types.js';
-export type { SqlCommitDurability, CommitFullyHeld } from '@optimystic/quereus-plugin-optimystic/plugin';
+export { connectToStrand } from './connect.js';
+export { offlineControllerOf } from './compose-strand.js';
+export { applyAppSchema } from './app-schema.js';
+export { createEmptyCollections, type CollectionRegistrySource } from './empty-collections.js';
+export {
+	MIN_CLUSTER_SIZE,
+	COHORT_READ_DEADLINE_MS,
+	CONTROL_REPLICATION_BREADTH,
+	CONTROL_CLUSTER_POLICY,
+	DEFAULT_STRAND_CLUSTER_SIZE,
+	STRAND_CLUSTER_POLICY,
+	resolveStrandClusterSize,
+	resolveRepairYardstick,
+	controlClusterPolicy,
+	strandClusterPolicy
+} from './cluster-size.js';
+export { wrapStorageWithCache, disposeStorageCache } from './cached-storage.js';
+export type {
+	StrandConnectionOptions, SereusPluginResult, StrandTransactor, StrandOfflineOptions, StrandOfflineController, AppSchemaOutcome,
+} from './types.js';
+export type { SqlCommitDurability, CommitFullyHeld } from '@optimystic/quereus-plugin-optimystic/plugin';
+export {
+	OfflineCommitTimeoutError,
+	QueuedEntriesBlockSchemaChangeError,
+	EntryNotDiscardableError,
+	UnknownEntryError,
+	QueueDisposedError,
+	OfflineJournalError,
+} from '@optimystic/quereus-plugin-optimystic/plugin';
+export type { QueuedTransactionStatus, OfflineModeState, CommitOutlook } from '@optimystic/quereus-plugin-optimystic/plugin';

package/src/strand-schema.ts

@@ -56,7 +56,7 @@ export const STRAND_SCHEMA = `    table Header (
 
         primary key (/* empty - singleton */),
         constraint InsertOnly check on update, delete (false),  -- One-time insert only for now - TODO: revisit for versioning
-    );
+    ) with tags ("optimystic.offline" = 'network');
 
     -- An invitation to join a strand as a member
     table Invite (
@@ -77,7 +77,7 @@ export const STRAND_SCHEMA = `    table Header (
                 -- and must also prove invite private key held by issuing manager
                 and verify(digest(new.Key || '|' || coalesce(new.Expiration, '')), context.InviteSignature, new.Key, 'ed25519')
         )
-    ) with context (ManagerKey text null, ManagerSignature text null, InviteSignature text null);
+    ) with tags ("optimystic.offline" = 'network') with context (ManagerKey text null, ManagerSignature text null, InviteSignature text null);
 
     -- Invite [InviteKey] has been used to add [MemberKey] as a member
     -- No StampId here or on Invite: both tables are insert-only and their primary keys are
@@ -126,7 +126,7 @@ export const STRAND_SCHEMA = `    table Header (
         constraint NotSealed check on insert (
             exists (select 1 from Manager)
         )
-    ) with context (InviteSignature text null, Now datetime null);
+    ) with tags ("optimystic.offline" = 'network') with context (InviteSignature text null, Now datetime null);
 
     -- A manager has cancelled invitation [InviteKey]: it may never be consumed.
     --
@@ -175,7 +175,7 @@ export const STRAND_SCHEMA = `    table Header (
                     and verify(digest('Strand.CancelledInvite', 'cancel', new.InviteKey),
                                context.ManagerSignature, A.MemberKey, 'ed25519'))
         )
-    ) with context (ManagerKey text, ManagerSignature text);
+    ) with tags ("optimystic.offline" = 'network') with context (ManagerKey text, ManagerSignature text);
 
     -- A party in the closed strand network
     table Member (
@@ -292,7 +292,7 @@ export const STRAND_SCHEMA = `    table Header (
                 or (new.Key is null
                     and verify(digest('Strand.Member', 'leave', old.Key, old.StampId), context.MemberSignature, old.Key, 'ed25519'))
         ),
-    ) with context (ManagerKey text null, ManagerSignature text null, MemberSignature text null);
+    ) with tags ("optimystic.offline" = 'network') with context (ManagerKey text null, ManagerSignature text null, MemberSignature text null);
 
     -- A member-associated peer (node)
     --
@@ -356,7 +356,7 @@ export const STRAND_SCHEMA = `    table Header (
                             and verify(digest('Strand.MemberPeer', 'manager-remove', old.MemberKey, old.PeerId, old.StampId), context.ManagerSignature, A.MemberKey, 'ed25519')
                 ))
         ),
-    ) with context (Signature text null, ManagerKey text null, ManagerSignature text null);
+    ) with tags ("optimystic.offline" = 'network') with context (Signature text null, ManagerKey text null, ManagerSignature text null);
 
     -- A manager is a member that can issue invites, authorize members, and rotate managers
     table Manager (
@@ -518,7 +518,7 @@ export const STRAND_SCHEMA = `    table Header (
                             and A.MemberKey <> old.MemberKey
                             and verify(digest('Strand.Manager', 'remove', old.MemberKey, old.StampId), context.Signature, A.MemberKey, 'ed25519')))
         )
-    ) with context (ManagerKey text null, Signature text null);
+    ) with tags ("optimystic.offline" = 'network') with context (ManagerKey text null, Signature text null);
 
     -- Permanent tombstones for retired per-row authorization nonces (StampIds) — the
     -- delete half of the retired-stamp anti-replay idiom on Member / Manager /
@@ -580,5 +580,5 @@ export const STRAND_SCHEMA = `    table Header (
                 where M.Key = context.MemberKey
                     and verify(digest('Strand.Revocation', 'retire', new.TableName, new.StampId), context.Signature, M.Key, 'ed25519'))
         )
-    ) with context (MemberKey text, Signature text);
+    ) with tags ("optimystic.offline" = 'network') with context (MemberKey text, Signature text);
 `;

package/src/types.ts

@@ -1,7 +1,7 @@
 import type { Libp2p } from '@libp2p/interface';
 import type { IRepo } from '@optimystic/db-core';
 import type { IRawStorage } from '@optimystic/db-p2p';
-import type { SqlCommitDurabilityListener, CommitFullyHeldListener } from '@optimystic/quereus-plugin-optimystic/plugin';
+import type { SqlCommitDurabilityListener, CommitFullyHeldListener, OfflineConfig, OfflineMode } from '@optimystic/quereus-plugin-optimystic/plugin';
 
 /**
  * Which Optimystic transactor a strand connection commits through — a choice of
@@ -73,8 +73,44 @@ export interface StrandConnectionOptions {
 	 *    one is injected. Unit tests only.
 	 */
 	transactor?: StrandTransactor;
+	/**
+	 * Turn on Optimystic's offline queue for this connection (docs/strands.md → "Offline mode").
+	 * Absent: no offline configuration reaches the plugin, and the result carries no
+	 * {@link SereusPluginResult.offline}. Programmatic only — the SQL plugin config cannot carry it.
+	 */
+	offline?: StrandOfflineOptions;
 }
 
+/**
+ * The Optimystic plugin's `offline` registration block (its README § "Offline mode"), less
+ * `journalLabel`: the composition derives the label from the strand id (`strandJournalLabel`).
+ * Without a `journal` the queue lives in memory, except where a platform defaults one (the browser
+ * connect journals into the strand's IndexedDB database).
+ */
+export type StrandOfflineOptions = Omit<OfflineConfig, 'journalLabel'>;
+
+/**
+ * The application's handle on a strand connection's offline queue: the part of Optimystic's
+ * `OfflineMode` an app calls. The class's other public methods are the plugin's internals.
+ */
+export type StrandOfflineController = Pick<OfflineMode,
+	'enter' | 'exit' | 'isEntered' | 'whenDrained' | 'onStatus' | 'onQueueState' | 'queueState'
+	| 'entries' | 'status' | 'discard' | 'outcomes' | 'acknowledge'>;
+
+/**
+ * How a connection's sApp schema apply ended (see {@link SereusPluginResult.appSchema}):
+ *
+ *  - `applied` — the schema is in place. `deferred` when queued offline transactions refused the
+ *    first apply and a later one, once they had settled, landed.
+ *  - `failed` — a deferred retry failed for a reason other than the queue; the connection keeps the
+ *    schema it had before.
+ *  - `cancelled` — the connection shut down before a deferred retry landed.
+ */
+export type AppSchemaOutcome =
+	| { state: 'applied'; deferred?: true }
+	| { state: 'failed'; error: unknown }
+	| { state: 'cancelled' };
+
 export interface SereusPluginResult {
 	vtables: [];
 	functions: [];
@@ -122,6 +158,18 @@ export interface SereusPluginResult {
 	 * `sync()` commits whatever is staged in it, outside any SQL transaction.
 	 */
 	createEmptyCollections: (except?: readonly string[]) => Promise<number>;
+	/** The offline queue's controller. Present only when {@link StrandConnectionOptions.offline} was given. */
+	offline?: StrandOfflineController;
+	/**
+	 * Present when {@link StrandConnectionOptions.schema} was given; never rejects. Resolves
+	 * `{ state: 'applied' }` at once when the apply succeeded at connect. When queued offline
+	 * transactions refused it, the connection comes up on the `App` schema it already had and
+	 * retries each time the queue drains; this settles when a retry lands, fails otherwise, or
+	 * {@link shutdown} runs first.
+	 */
+	appSchema?: Promise<AppSchemaOutcome>;
+	/** The queued transaction ids that refused the connect-time apply. Present only when it was deferred. */
+	appSchemaDeferredBy?: readonly string[];
 	/** Shuts down the libp2p node and collection factory. Call when done. */
 	shutdown: () => Promise<void>;
 }