@docstack/client 0.1.5 → 0.1.8

package/lib/core/stack.d.ts

@@ -1,11 +1,15 @@
 import Class from "./class.js";
 import Domain from "./domain.js";
-import { Stack, StackOptions, AuthSessionProof, ClientCredentials, CachedClass, ClassModelPropagationStart, ClassModelPropagationComplete, CachedDomain, DomainModel } from "@docstack/shared";
+import { Stack, StackOptions, AuthSessionProof, ClientCredentials, CachedClass, ClassModelPropagationStart, ClassModelPropagationComplete, CachedDomain, DomainModel, ChangesSubscription } from "@docstack/shared";
 import { SystemDoc, Patch, ClassModel, Document, RelationDocument } from "@docstack/shared";
+import { StackSyncHandle } from "./sync/index.js";
+import type { StackSyncOptions, SyncStatus } from "./sync/index.js";
 import type { SelectAST, UnionAST } from "./query-engine/index.js";
 import { JobEngine } from "./job-engine/index.js";
+import { JobScheduler } from "./job-engine/scheduler.js";
 import { PolicyEngine } from "./policy-engine/index.js";
 import { CryptoEngine } from "./crypto-engine/index.js";
+import type { ContentExport, ContentExportOptions, ContentImportOptions, ContentImportReport } from "./content-transfer.js";
 export declare const BASE_SCHEMA: ClassModel["schema"];
 export declare const CLASS_SCHEMA: ClassModel["schema"];
 /**
@@ -45,6 +49,22 @@ declare class ClientStack extends Stack {
      * ```
      */
     db: PouchDB.Database<{}>;
+    /**
+     * The unguarded PouchDB instance. Only the sync layer reaches for it, through
+     * {@link getReplicationHandle}.
+     * @internal
+     */
+    private rawDb;
+    /**
+     * `bulkDocs`/`bulkGet` as PouchDB defines them, captured before {@link StackPlugin}
+     * replaces them.
+     * @internal
+     */
+    private pristineDbMethods;
+    /** Memoised {@link getReplicationHandle} result. @internal */
+    private replicationDb?;
+    /** The stack's replication, once {@link sync} has been called. @internal */
+    private syncHandle?;
     /** The unique name identifier for this stack instance, derived from the connection string. */
     name: string;
     lastDocId: number;
@@ -62,7 +82,57 @@ declare class ClientStack extends Stack {
         [className: string]: CachedClass | CachedDomain;
     };
     patchCount: number;
-    listeners: PouchDB.Core.Changes<{}>[];
+    /**
+     * Stored class models, keyed by whatever the caller looked them up with (name or id).
+     *
+     * `getClassModel` runs at least once per document on every read and write path (the
+     * policy engine resolves each document's class through it), and each miss is an
+     * unindexed find. Entries include `null` for names that resolved to nothing - the
+     * caches are cleared whenever a class document is written, so a class created later
+     * evicts its own negative entry.
+     *
+     * Invalidated as a pair with {@link classSnapshotCache}: synchronously by the write
+     * path (StackPlugin calls {@link invalidateWriteCaches} after every batch that
+     * touches a class model) and again by the shared changes feed for writes this stack
+     * did not make itself. Cleared wholesale rather than per-entry because a rename
+     * leaves the old name keyed to a model that no longer answers to it.
+     */
+    private classModelCache;
+    /**
+     * Built, non-subscribing Class instances, keyed by class name and pinned to the
+     * model revision they were built from.
+     *
+     * Building a Class rebuilds every Attribute and re-derives the Zod schema, per
+     * attribute - work `getClassSnapshot` used to repeat on every call. The `_rev` pin
+     * means a stale entry can never be served even if invalidation lags: the model is
+     * looked up first (through {@link classModelCache}) and the snapshot is reused only
+     * when its revision still matches.
+     */
+    private classSnapshotCache;
+    /**
+     * Every live changes subscription this stack has handed out; released on close.
+     */
+    listeners: ChangesSubscription[];
+    /**
+     * The one live feed behind every class-document subscription.
+     *
+     * PouchDB attaches a `destroyed` listener to the database for each
+     * `db.changes({ live: true })` and holds it until that feed is cancelled, so a feed
+     * per watched class crosses Node's ten-listener limit - and prints
+     * `MaxListenersExceededWarning` - on an app with a handful of classes on screen. It
+     * is also wasted work: the local adapter runs every filter over the same change
+     * stream, so N filtered feeds each see every change anyway.
+     */
+    private classDocFeed?;
+    /**
+     * Change handlers, keyed `"<metaKey>:<name>"`. Empty means {@link classDocFeed} can be
+     * cancelled.
+     *
+     * The meta key is part of the key because classes and domains are separate namespaces:
+     * a relation document is named by `~domain` and carries no `~class`, so routing both
+     * through one keyspace would let a class and a same-named domain hear each other.
+     */
+    private classDocSubscribers;
     modelWorker: Worker | null;
     /**
      * Engine for executing background jobs and scheduled tasks.
@@ -75,6 +145,19 @@ declare class ClientStack extends Stack {
      * ```
      */
     jobEngine: JobEngine;
+    /**
+     * Decides when approved jobs run, and dispatches them.
+     *
+     * Constructed with the stack but deliberately **not started by it**: `~Job.content`
+     * is JavaScript that replicates, so which jobs may run with nobody watching is the
+     * application's decision, named at {@link JobScheduler.start}.
+     *
+     * @example
+     * ```typescript
+     * stack.jobScheduler.start({ jobs: ['Job-review-campaign'] });
+     * ```
+     */
+    jobScheduler: JobScheduler;
     /**
      * Engine for enforcing read/write access control policies.
      * Policies are evaluated based on user session and document content.
@@ -92,13 +175,91 @@ declare class ClientStack extends Stack {
      */
     authSession?: AuthSessionProof;
     private cryptoEngineDisabled;
+    /**
+     * Application patches held back because they write encrypted attributes and the stack
+     * has no key yet. Replayed by {@link unlock}. Kept in memory on purpose - reopening
+     * the stack runs the same options through the same check.
+     */
+    private deferredPatches;
     private constructor();
     private initialize;
     /**
-     * Returns the underlying PouchDB database instance.
-     * @returns The PouchDB database
+     * Returns the stack's PouchDB database handle.
+     *
+     * The handle is guarded: reads and ordinary writes behave exactly as PouchDB
+     * documents them, and `put`/`post`/`remove`/`bulkDocs` all run the stack's
+     * authoring path. The two routes that would skip it - `bulkDocs` with
+     * `new_edits: false`, and the `_`-prefixed adapter methods - throw
+     * {@link StackWriteGuardError}; replicating into a stack goes through
+     * {@link sync} instead.
+     *
+     * @returns The guarded PouchDB database
      */
     getDb(): PouchDB.Database<{}>;
+    /**
+     * Returns the database with PouchDB's own `bulkDocs`/`bulkGet` restored, for the
+     * sync layer's exclusive use.
+     *
+     * Replication needs both halves of the plugin out of the way: it writes documents
+     * with revisions it already owns (`new_edits: false`), and it must read documents
+     * exactly as they are stored - the plugin's `bulkGet` decrypts on read, which would
+     * push plaintext to a remote that is meant to hold ciphertext.
+     *
+     * @returns A handle suitable for `PouchDB.replicate`/`PouchDB.sync`
+     * @internal
+     */
+    getReplicationHandle(): PouchDB.Database<{}>;
+    /**
+     * Starts replicating this stack against a remote.
+     *
+     * DocStack owns the lifecycle - the filter that keeps `~system`, the crypto marker,
+     * design documents, locks, sessions and the patch ledger on this device; the schema
+     * gate that refuses a remote written by a newer build; the convergence state a UI
+     * renders; and cancellation when the stack closes. It owns nothing about the
+     * transport: the remote is whatever PouchDB database the caller hands over, so
+     * credentials and adapter configuration stay in the application.
+     *
+     * Calling it again replaces the previous replication.
+     *
+     * @param options - See {@link StackSyncOptions}.
+     * @returns The handle, once replication is running.
+     * @throws {SyncSchemaMismatchError} When the remote was last written by a newer schema.
+     *
+     * @example
+     * ```typescript
+     * const sync = await stack.sync({
+     *     remote: () => new PouchDB("workspace", { adapter: "googledrive", accessToken }),
+     *     direction: "both",
+     *     live: true,
+     *     retry: true,
+     * });
+     *
+     * sync.addEventListener("status", (event) => {
+     *     console.log((event as CustomEvent).detail.state);
+     * });
+     * ```
+     */
+    sync(options: StackSyncOptions): Promise<StackSyncHandle>;
+    /**
+     * Returns this stack's replication handle, or `null` if {@link sync} was never called.
+     */
+    getSyncHandle(): StackSyncHandle | null;
+    /**
+     * Returns where this stack's replication stands, or `null` if it has none.
+     *
+     * @example
+     * ```typescript
+     * const status = stack.getSyncStatus();
+     * if (status?.lastConvergedAt) {
+     *     ui.setLabel(`Synced ${formatAgo(status.lastConvergedAt)}`);
+     * }
+     * ```
+     */
+    getSyncStatus(): SyncStatus | null;
+    /**
+     * Stops this stack's replication. Idempotent; called automatically by {@link close}.
+     */
+    cancelSync(): void;
     /**
      * Retrieves information about the database including document count and update sequence.
      * @returns Database information object
@@ -119,18 +280,207 @@ declare class ClientStack extends Stack {
      * Called automatically by {@link authenticate}, but can be set manually for custom auth flows.
      * @param proof - The authentication session proof containing session and encryption keys
      */
-    setAuthSession(proof: AuthSessionProof): void;
+    setAuthSession(proof: AuthSessionProof): Promise<void>;
     /**
      * Clears the current authentication session and removes the document encryption key.
      * Call this when a user logs out.
      */
     clearAuthSession(): void;
+    /**
+     * Whether the stack is operating without its document encryption key.
+     *
+     * A locked stack reads everything that needs no key and refuses writes to classes
+     * carrying encrypted attributes, rather than storing them in the clear. Patches that
+     * would write encrypted data are deferred until {@link unlock}. Stacks with the crypto
+     * engine disabled are never locked - there is no key to be missing.
+     *
+     * @returns `true` when encryption is enabled but no key is held.
+     */
+    isLocked(): boolean;
+    /**
+     * Supplies the document encryption key to a locked stack.
+     *
+     * The key is checked against the stack's canary before it is accepted, so passing the
+     * wrong one throws instead of quietly producing unreadable writes. On the first unlock
+     * of a stack that has none, the canary is minted from the key given - which is what
+     * makes every later open verifiable.
+     *
+     * Unlocking resumes any bootstrap deferred while locked, then emits `unlocked`.
+     *
+     * @param documentKey - The hex-encoded document key, from wherever the application
+     * provisions it.
+     * @throws If the stack has encryption disabled, or the key does not match the canary.
+     *
+     * @example
+     * ```typescript
+     * const stack = await ClientStack.create('db-app');   // opens locked
+     * await stack.unlock(await myServer.fetchDocumentKey());
+     * stack.isLocked(); // false
+     * ```
+     */
+    unlock(documentKey: string): Promise<this>;
+    /**
+     * Encrypts bootstrap documents that were seeded before this stack had a key.
+     *
+     * The seed system user is the one document DocStack must write before a key can
+     * exist: the first open of a database has no wrapped key to recover one from, and
+     * refusing to seed it would leave nothing to authenticate against. It is therefore
+     * written in the clear - its password is the published constant `"system"`, so
+     * nothing secret is exposed - and repaired here.
+     *
+     * Rewriting it through the authoring path encrypts its attributes and lets
+     * `auto-wrap-document-key` run for the first time, producing the
+     * `wrappedDocumentKey` that lets another device recover this same document key.
+     * Without this step a stack bootstrapped locked could never authenticate, because
+     * the trigger no-ops when no key is held. See ADR-0018.
+     */
+    private rekeyBootstrapDocuments;
     /**
      * Exports all documents from the database.
      * Useful for debugging or creating backups.
      * @returns All documents including their content
      */
     dump: () => Promise<PouchDB.Core.AllDocsResponse<{}>>;
+    /**
+     * Lists the content classes and domains this stack holds.
+     *
+     * "Content" means created by an application: DocStack's own classes are `~`-prefixed
+     * and its datamodel documents use the reserved names in `META_CLASSES`.
+     *
+     * @returns The class names and domain names an export would cover.
+     */
+    /**
+     * Every class name in this stack, DocStack's own included.
+     *
+     * The fail-open path for a live query: when the classes a query reads cannot be
+     * determined from its AST, watching all of them is wasteful but correct, and watching
+     * none is silently wrong. Cheap to act on - subscriptions share one database
+     * listener, so the cost is a set entry per class rather than a feed. See ADR-0025.
+     *
+     * For the application's classes alone, use {@link getContentClassNames}.
+     *
+     * @returns The class names, sorted.
+     */
+    /**
+     * The names of classes whose documents are local to one run.
+     *
+     * See {@link ClassModel.ephemeral}. Resolved from the stored models rather than a
+     * hardcoded list, so an application that declares its own ephemeral class - a cache,
+     * a derived view, anything a peer neither needs nor should receive - is covered
+     * without DocStack knowing about it.
+     *
+     * @returns The ephemeral class names, sorted.
+     */
+    /**
+     * Classes declared `simple`, held for synchronous lookup.
+     *
+     * {@link StackPlugin} needs the answer inside `bulkDocs`, before it decides whether to
+     * load the class at all - and loading the class to find out is the very cost the flag
+     * exists to avoid. Refreshed when the datamodel is in place and whenever a class model
+     * changes. See ADR-0028.
+     */
+    private simpleClassNames;
+    /**
+     * Whether a class stores its documents as given.
+     *
+     * See {@link ClassModel.simple}. Answers `false` for a class it has not heard of,
+     * which is the safe direction: an unknown class gets the full authoring path.
+     *
+     * @param className - The `~class` of a document.
+     */
+    isSimpleClass: (className: unknown) => boolean;
+    /**
+     * Re-reads which classes are `simple`.
+     *
+     * @returns The names, for callers that want them.
+     */
+    refreshSimpleClasses: () => Promise<string[]>;
+    getEphemeralClassNames: () => Promise<string[]>;
+    /**
+     * Empties the ephemeral classes.
+     *
+     * Called when the stack opens, which is what "one run" means: contents cover the
+     * session that is starting, a logout leaves them alone, and a crash is cleaned up by
+     * the next open rather than leaving documents on disk forever.
+     *
+     * Failures are logged and swallowed. A stack that cannot clear its scratch data should
+     * still open.
+     *
+     * @returns How many documents were removed.
+     */
+    private purgeEphemeralDocuments;
+    getClassNames: () => Promise<string[]>;
+    getContentClassNames: () => Promise<{
+        classes: string[];
+        domains: string[];
+    }>;
+    /**
+     * Exports this stack's application content, and nothing else.
+     *
+     * Deliberately narrower than {@link dump}, which returns the database verbatim -
+     * class models, patches, users, sessions, policies, design documents, and encrypted
+     * attributes as unreadable payloads. That is a backup of *this* database. This is the
+     * portable one: the documents an application put in, ready for
+     * {@link importContent} to place into a stack whose schema its own patches built and
+     * whose document key is its own.
+     *
+     * What it does **not** do:
+     *
+     * - **It does not bypass encryption.** Documents are read through the decrypting path,
+     *   so encrypted attributes come out as plaintext. That is what makes the export
+     *   portable across keys - and what makes the result as sensitive as the data itself.
+     *   A locked stack cannot decrypt, so the export is refused rather than silently
+     *   emitting `null` where values should be (see `allowLossyWhenLocked`).
+     * - **It does not bypass read policies.** Documents the current session may not read
+     *   are absent, exactly as they are absent from `findDocuments`.
+     * - **It carries no schema, no patches and no system documents.**
+     *
+     * @param options - Which classes and domains to cover; see {@link ContentExportOptions}.
+     * @returns The portable envelope.
+     * @throws Error when the stack is locked and an exported class has encrypted
+     * attributes, unless `allowLossyWhenLocked` is set.
+     *
+     * @example
+     * ```typescript
+     * const payload = await stack.exportContent({ classes: ["Task", "Project"] });
+     * download(new Blob([JSON.stringify(payload)], { type: "application/json" }));
+     * ```
+     */
+    exportContent: (options?: ContentExportOptions) => Promise<ContentExport>;
+    /**
+     * Imports content produced by {@link exportContent} into this stack.
+     *
+     * The counterpart, and it is not symmetric: an export is a read, an import is a
+     * reconciliation. The payload carries data and no schema, so this stack's datamodel
+     * decides what is allowed in.
+     *
+     * - **Reconciled against the datamodel.** Every document's class must already exist
+     *   here; a missing one is reported rather than invented, because the export carries
+     *   no schema to create it from. Attributes the target class does not define are
+     *   dropped by default.
+     * - **Written through the authoring path**, so schema validation, relation checks and
+     *   triggers all run - and so encrypted attributes are **encrypted under this stack's
+     *   document key**, not the one they were exported from.
+     * - **Documents before relations**, because a relation is rejected unless both ends
+     *   already exist.
+     *
+     * Not a transaction: a failure part way through leaves what was already written. The
+     * report says what landed.
+     *
+     * @param payload - An envelope from {@link exportContent}.
+     * @param options - How to reconcile; see {@link ContentImportOptions}.
+     * @returns What was written, skipped, and why.
+     * @throws Error when the payload is not a recognised export, or when a `"fail"` option
+     * is set and the condition it names occurs.
+     *
+     * @example
+     * ```typescript
+     * const report = await stack.importContent(JSON.parse(await file.text()));
+     * report.documents.written; // 128
+     * report.issues;            // [{ docId: "Task-9", kind: "missing-class", ... }]
+     * ```
+     */
+    importContent: (payload: ContentExport, options?: ContentImportOptions) => Promise<ContentImportReport>;
     private ensureDefaultPolicyForClass;
     /**
      * Creates and initializes a new ClientStack instance.
@@ -157,6 +507,34 @@ declare class ClientStack extends Stack {
      * ```
      */
     static create(conn: string, options?: StackOptions): Promise<ClientStack>;
+    /**
+     * Applies application-supplied patches, holding back any that need a document key.
+     *
+     * A locked stack must not write encrypted attributes in the clear, so a patch that
+     * would do so is kept for {@link unlock} instead. This is a barrier rather than a
+     * filter: patches apply in order and a later one may depend on the schema an earlier
+     * one installs, so the first deferral stops the run.
+     *
+     * The held-back patches live on the instance, not in the database - reopening the
+     * stack replays the same options through the same check, so there is no persisted
+     * state to drift.
+     *
+     * @param patches - Patches not yet present in this stack.
+     */
+    private applyConsumerPatches;
+    /**
+     * Decides whether applying a patch would write an encrypted attribute.
+     *
+     * The judgement is made immediately before the patch would be applied, against the
+     * schema as it stands then, plus any class model the patch carries itself - a patch
+     * can introduce an encrypted attribute and write a document using it in one go, as
+     * `~sys-0.0.8` does. Everything earlier has already landed, so nothing needs to
+     * simulate schema evolution ahead of time.
+     *
+     * @param patch - The patch about to be applied.
+     * @returns `true` if any document in it belongs to a class with encrypted attributes.
+     */
+    private patchNeedsDocumentKey;
     /**
      * Authenticates a user and establishes a session.
      *
@@ -180,6 +558,43 @@ declare class ClientStack extends Stack {
      * ```
      */
     authenticate(credentials: ClientCredentials): Promise<AuthSessionProof>;
+    /**
+     * Finishes the work that could not be done while the stack had no document key.
+     *
+     * Reached from both ways a key arrives - {@link unlock} and {@link authenticate} -
+     * because the consequences are the same either way: the canary has to exist for later
+     * opens to be verifiable, bootstrap documents seeded in the clear have to be
+     * encrypted, and patches held back have to be applied.
+     */
+    private onDocumentKeyAvailable;
+    /**
+     * Mints an identifier for a new document.
+     *
+     * Random, not sequential, and that is the whole point. Ids used to be
+     * `${type}-${lastDocId + 1}`, from a counter that only *local* writes advance: a
+     * document arriving by replication goes through {@link getReplicationHandle}, which
+     * bypasses that path by design, so the counter stood still while ids were consumed.
+     * The next local write then minted an id the database already held, PouchDB resolved
+     * the two as revisions of one document, and the new one was gone - with no error,
+     * because the conflict was swallowed. Two devices did it to each other from their
+     * very first document, both starting at `1`.
+     *
+     * No counter repair fixes that. Feeding replicated documents back into the counter
+     * still leaves two offline devices minting the same id, because a sequence derived
+     * from local state cannot be unique across devices that have not met. The identifier
+     * has to stop being derived from local state at all. See ADR-0023.
+     *
+     * The class prefix stays, so an id still says what it is.
+     *
+     * @param type - The class or domain name, used as the prefix.
+     * @returns An id of the form `Task-9f2c...`, 96 random bits wide.
+     *
+     * @example
+     * ```typescript
+     * stack.generateDocId("Task"); // "Task-3f9a2b7c1d4e5f60a1b2c3d4"
+     * ```
+     */
+    generateDocId(type: string): string;
     getLastDocId(): Promise<number>;
     getSystem(): Promise<SystemDoc>;
     private loadPatches;
@@ -210,10 +625,176 @@ declare class ClientStack extends Stack {
     onClassLock: (className: string) => PouchDB.Core.Changes<{}>;
     addClassLock: (className: string) => Promise<boolean>;
     clearClassLock: (className: string) => Promise<boolean>;
-    onClassDoc: (className: string) => PouchDB.Core.Changes<{}>;
+    /**
+     * Opens the shared class-document feed if it is not already running.
+     *
+     * Dispatch is keyed on the document's `~class`, which is what the per-class filters
+     * used to test. A change with no document therefore cannot be routed and is dropped,
+     * exactly as the filters dropped it: PouchDB hands a filter only `{_id, _rev,
+     * _deleted}` for a hard deletion, so `~class` was already absent. DocStack deletes
+     * are soft - the document arrives with `active: false` - so this is not the delete
+     * path.
+     */
+    /** The subscriber-map key for a name in one of the two namespaces. */
+    private static subscriberKey;
+    /**
+     * Resolves which subscribers a change belongs to.
+     *
+     * A document names its owner in exactly one of two fields - `~class` for a class's
+     * documents, `~domain` for a domain's relation documents - so the routing key comes
+     * from whichever is present. A change with neither cannot be routed and is dropped,
+     * exactly as the per-class filters dropped it: PouchDB hands a filter only
+     * `{_id, _rev, _deleted}` for a hard deletion, so no meta field was there either.
+     * DocStack deletes are soft - the document arrives with `active: false` - so this is
+     * not the delete path.
+     */
+    private static routingKeyFor;
+    private ensureClassDocFeed;
+    private addClassDocSubscriber;
+    private removeClassDocSubscriber;
+    /**
+     * Subscribes to changes on the documents of a class, or of a domain.
+     *
+     * Returns a handle onto {@link classDocFeed} rather than a feed of its own, so the
+     * database carries one `destroyed` listener no matter how many are watched.
+     * Cancelling releases only this subscriber; the feed stops once the last one goes.
+     *
+     * Prefer {@link subscribeClassDocs} / {@link subscribeDomainDocs}, which route changes
+     * through the decrypting preparation step (ADR-0020). Whichever is used, the handle
+     * must be handed to {@link releaseListener} when the watcher is done.
+     *
+     * @param className - The class or domain whose documents to watch.
+     * @param metaKey - Which field names the owner: `~class` (default) for a class's
+     * documents, `~domain` for a domain's relation documents. Separate namespaces.
+     * @returns A cancellable subscription handle.
+     */
+    onClassDoc: (className: string, metaKey?: "~class" | "~domain") => ChangesSubscription;
+    /**
+     * Prepares a document delivered by the changes feed for a listener.
+     *
+     * The changes feed is the one read path that does not pass through
+     * {@link StackPlugin}: decryption lives in the `bulkGet` wrapper, which is what makes
+     * `getCards` and `findDocuments` transparent, while `include_docs` hands back exactly
+     * what is stored. Every read decrypted except the one that pushed, so a live view
+     * received an `EncryptedPayload` object where it had just rendered a string.
+     *
+     * @param doc - The document from `change.doc`.
+     * @param classObj - The class, when known; without it encrypted values are still
+     * recognised by shape.
+     * @returns A copy safe to hand to a consumer. Never contains an `EncryptedPayload`.
+     *
+     * @example
+     * ```typescript
+     * const doc = await stack.prepareChangeDocument(change.doc, classObj);
+     * doc.ssn; // plaintext, or null when it cannot be opened
+     * ```
+     */
+    prepareChangeDocument: (doc: Document, classObj?: Class) => Promise<Document>;
+    /**
+     * Evicts derived caches after documents were written.
+     *
+     * Called synchronously by StackPlugin after every successful `bulkDocs` batch (which
+     * every local write funnels through, `put`/`post`/`remove` and replication included),
+     * and again by the shared changes feed for writes made outside this instance -
+     * another tab on the same database, most commonly. The write-path call is what makes
+     * a policy or schema write visible to the very next read: the changes feed delivers
+     * asynchronously, and a cache invalidated only by the feed would serve stale answers
+     * in that window.
+     *
+     * Class-model writes clear the model and snapshot caches wholesale rather than by
+     * key - a rename leaves the old name keyed to a model that no longer answers to it,
+     * and class writes are rare enough that precision buys nothing.
+     *
+     * @param docs - The documents just written; omit to invalidate everything.
+     */
+    invalidateWriteCaches: (docs?: unknown[]) => void;
+    /**
+     * Whether a database-level `limit` returns the same rows as limiting in memory.
+     *
+     * `findDocuments` filters per document *after* the query - policy checks drop
+     * unreadable documents, and a locked crypto engine drops documents whose visible
+     * fields are all encrypted. A limit applied before either would under-fill. The
+     * query engine asks this before pushing a SQL LIMIT into the fetch.
+     *
+     * @param className - The class being queried.
+     */
+    canApplyQueryLimitEarly: (className: string) => Promise<boolean>;
+    /**
+     * Creates the stack's standing Mango indexes.
+     *
+     * Every `findDocuments` selector carries `~class` and `active`, and without an index
+     * pouchdb-find answers each one with a full `allDocs` scan - linear in database
+     * size, per call. One fixed index serves them all. This replaces the old commented
+     * per-query `createIndex` inside `findDocuments`, which built a fresh index for
+     * every distinct selector shape and buried the database in design documents - the
+     * "breaks find and even db" the comment there warned about.
+     *
+     * Failure is deliberately non-fatal: an index is an optimization, and pouchdb-find
+     * falls back to scanning exactly as before.
+     */
+    private ensureMangoIndexes;
+    /** Registry of on-demand sort indexes; a `_local` doc, so per-device and unreplicated. */
+    private static readonly SORT_INDEX_REGISTRY_ID;
+    /** Prefix shared by every sort-index design document this stack creates. */
+    private static readonly SORT_INDEX_DDOC_PREFIX;
+    /** Most sort indexes a stack will maintain; past this, queries sort in memory. */
+    private static readonly MAX_SORT_INDEXES;
+    /** How stale a sort index may go before {@link cleanupSortIndexes} removes it. */
+    private static readonly SORT_INDEX_MAX_IDLE_MS;
+    /** Fields whose sort index exists this session; avoids re-running createIndex. */
+    private sortIndexSession;
+    private readSortIndexRegistry;
+    /**
+     * Creates (or confirms) a Mango index for sorting by `field`, and records the use.
+     *
+     * Indexes are made on demand by the query engine when an ORDER BY can ride the
+     * database, and every index is a standing cost: a view updated on every write from
+     * then on. Three things keep that bounded: a cap ({@link MAX_SORT_INDEXES}) past
+     * which this returns `false` and the caller sorts in memory; a usage registry (a
+     * `_local` document, per device) stamped on each use; and
+     * {@link cleanupSortIndexes}, run at init, dropping indexes idle past
+     * {@link SORT_INDEX_MAX_IDLE_MS}. A dropped index is not an error - the next sorted
+     * query recreates it.
+     *
+     * @param field - The document field to index for sorting (under `~class`).
+     * @returns `true` when the index exists and may be used for a sorted query.
+     */
+    ensureSortIndex: (field: string) => Promise<boolean>;
+    /**
+     * Drops sort indexes that have gone unused.
+     *
+     * Covers indexes this device created *and* ones that replicated in as design
+     * documents from a peer: every `_design/docstack-sort-*` doc is considered, and one
+     * with no registry entry is adopted with the current time as first-seen, so it gets
+     * a full idle period before removal. Runs automatically at init; callable directly
+     * for an immediate sweep.
+     *
+     * @param options.olderThanMs - Idle threshold; defaults to {@link SORT_INDEX_MAX_IDLE_MS}.
+     * @returns Which fields were removed and which kept.
+     */
+    cleanupSortIndexes: (options?: {
+        olderThanMs?: number;
+    }) => Promise<{
+        removed: string[];
+        kept: string[];
+    }>;
     initdb(): Promise<this>;
     private ensureCryptoConfigDocument;
     private ensureCryptoMarkerEncryption;
+    /**
+     * Checks a stack's stored crypto configuration against how it is being opened.
+     *
+     * The canary is the admission test for keys: `encryptedMarker` holds a value only the
+     * stack's own document key can decrypt, so a wrong key is caught here rather than
+     * becoming unreadable data later. Note what is *not* checked - whether the stack
+     * already holds encrypted documents. A key is admitted on proof, so a second device
+     * can open a stack the first one wrote, which is the whole point of the wrapped-key
+     * path. See ADR-0018.
+     *
+     * @param existing - The stored `~crypto-engine-config` document.
+     * @throws If the engine flag disagrees with the stored one, or a key is present but
+     * fails to decrypt the canary.
+     */
     private validateCryptoConfig;
     /**
      * Closes the stack and cleans up all resources.
@@ -245,6 +826,33 @@ declare class ClientStack extends Stack {
      * @param fresh - If `true`, bypasses the cache and fetches from database
      * @returns The Domain instance, or `null` if not found
      */
+    /**
+     * Reads a class's current stored model without subscribing or caching it.
+     *
+     * The counterpart to {@link getClass} for code that wants a schema rather than a live
+     * view: validation, encryption, and anything else that runs per write or per row.
+     * Two properties matter and pull in opposite directions in {@link getClass}:
+     *
+     * - It is always current. The cache is invalidated by a changes feed, which is
+     *   asynchronous, so during a burst of schema writes - patch application, most
+     *   obviously - the cached instance can still be the previous schema. Validating a
+     *   document against that fails.
+     * - It does not subscribe. A Class built by {@link Class.get} watches its documents
+     *   until closed, so building one per written document leaves live feeds behind and
+     *   PouchDB eventually warns about the `destroyed` listeners they hold.
+     *
+     * The returned instance emits no `doc` events and needs no `close()`.
+     *
+     * @param className - The name or ID of the class.
+     * @returns The class, or `null` if there is no model by that name.
+     *
+     * @example
+     * ```typescript
+     * const classObj = await stack.getClassSnapshot(doc["~class"]);
+     * classObj?.getEncryptedAttributes();
+     * ```
+     */
+    getClassSnapshot: (className: string) => Promise<Class | null>;
     getDomain: (domainName: string, fresh?: boolean) => Promise<Domain | null>;
     initIndex(): Promise<void>;
     /**
@@ -286,10 +894,46 @@ declare class ClientStack extends Stack {
      */
     findDocuments: <T extends Document | RelationDocument = Document>(selector: {
         [key: string]: any;
-    }, fields?: string[], skip?: number, limit?: number) => Promise<{
+    }, fields?: string[], skip?: number, limit?: number, sort?: {
+        [field: string]: "asc" | "desc";
+    }[]) => Promise<{
         [key: string]: any;
         docs: T[];
     }>;
+    /**
+     * Runs raw fetched documents through the read pipeline: per-document policy
+     * check, decryption, and field visibility. Shared by {@link findDocuments} and
+     * {@link findDocumentsIterator} so the two cannot drift.
+     */
+    private processFoundDocuments;
+    /**
+     * Reads documents matching a selector as an async stream, in `_id` order.
+     *
+     * Pages through the database with a keyset cursor on `_id` (which the primary
+     * index serves) instead of materializing the full result: peak memory is one
+     * batch, and total work across all pages is the same one scan a single big read
+     * would do. Each batch goes through the same policy/decryption pipeline as
+     * {@link findDocuments}. The cursor advances by the last *fetched* document, not
+     * the last *readable* one, so pages thinned out by policy filtering cannot stall
+     * the iteration.
+     *
+     * @param selector - A Mango selector; `active: true` is injected unless present.
+     * @param options.fields - Projection; `_id` is always included (the cursor needs it).
+     * @param options.batchSize - Documents fetched per page (default 100).
+     *
+     * @example
+     * ```typescript
+     * for await (const doc of stack.findDocumentsIterator({ "~class": "Task" })) {
+     *     render(doc);
+     * }
+     * ```
+     */
+    findDocumentsIterator: <T extends Document | RelationDocument = Document>(selector: {
+        [key: string]: any;
+    }, options?: {
+        fields?: string[];
+        batchSize?: number;
+    }) => AsyncGenerator<T, void, void>;
     private processReadableDocument;
     /**
      * Finds a single document matching a selector.
@@ -336,6 +980,13 @@ declare class ClientStack extends Stack {
         search?: string;
     }) => Promise<Domain[]>;
     incrementLastDocId(): Promise<number>;
+    /**
+     * Advances the document-id counter by `count` in one database write.
+     *
+     * Batch creation hands out `count` ids from the in-memory counter and commits them
+     * here once, instead of a get+put round-trip per document.
+     */
+    advanceLastDocId(count: number): Promise<number>;
     reset(): Promise<this>;
     destroyDb(): Promise<boolean>;
     static clear(conn: string): Promise<unknown>;
@@ -489,9 +1140,41 @@ declare class ClientStack extends Stack {
      * const { rows } = await stack.query('SELECT * FROM Task WHERE priority = ?', 'high');
      * ```
      */
+    /**
+     * Replaces `?` placeholder nodes in a parsed AST with the caller's parameter values.
+     *
+     * Values are restricted to plain scalars: an object here could carry Mango
+     * operators of its own and reach the database as part of a pushed-down selector,
+     * changing what the query matches. Structured values belong in the document
+     * model, not in a comparison.
+     */
+    private static bindQueryParams;
     query: (sql: string, ...params: any[]) => Promise<{
         rows: any;
         ast: (SelectAST | UnionAST)[];
     }>;
+    /**
+     * Executes a SQL query as an async stream of rows.
+     *
+     * The streaming counterpart to {@link query}: single-table plans without
+     * aggregation, DISTINCT, ORDER BY, or subqueries stream row by row on top of
+     * {@link findDocumentsIterator} - peak memory is one page regardless of result
+     * size, and a LIMIT stops the underlying scan early. More complex plans execute
+     * normally and yield from the materialized result, so the API is uniform.
+     * Row order on the streaming path is `_id` order.
+     *
+     * @param sql - The SQL SELECT statement.
+     * @param params - Values for `?` placeholders.
+     *
+     * @example
+     * ```typescript
+     * for await (const row of stack.queryStream("SELECT t.title FROM Task AS t WHERE t.done = FALSE;")) {
+     *     render(row);
+     * }
+     * ```
+     */
+    queryStream: (sql: string, ...params: any[]) => AsyncGenerator<{
+        [column: string]: any;
+    }, void, void>;
 }
 export default ClientStack;