@docstack/client 0.1.5 → 0.1.8

package/lib/core/sync/class-filter.d.ts

@@ -0,0 +1,106 @@
+/**
+ * Class-level replication filtering.
+ *
+ * The obvious way for an application to filter a DocStack stack is by class - "sync
+ * Tasks and Projects, leave Drafts on this device". Doing that correctly needs two
+ * pieces of knowledge an application author has no reason to have, which is why it
+ * lives here rather than in a hand-written predicate:
+ *
+ * 1. **An allow-list has to keep the data model.** Class models, domains, policies,
+ *    users and groups are not "documents of a class the user picked" - they are what
+ *    makes the replica readable at all. An `include: ["Task"]` that took the phrase
+ *    literally would produce a remote holding Task documents and no Task class, which
+ *    the next device could not open.
+ * 2. **Relations are not classified by `~class`.** A relation document carries
+ *    `~domain` plus `sourceClass`/`targetClass`, so a filter that only looks at
+ *    `~class` lets every relation through - including relations pointing at documents
+ *    that were filtered out, which arrive on the peer as dangling references.
+ *
+ * @module
+ */
+/**
+ * Classes that describe the stack itself rather than its subject matter.
+ *
+ * Kept by an allow-list unless {@link ClassFilterOptions.includeDataModel} turns that
+ * off. `~self` is the bootstrap class model; `patch` is here for completeness even
+ * though the internal-document filter already keeps it local.
+ */
+export declare const DATA_MODEL_CLASSES: readonly string[];
+/**
+ * Which classes replicate.
+ *
+ * `include` and `exclude` may be combined; `exclude` wins where they overlap. Entries
+ * are matched against a document's `~class` and against a relation's
+ * `sourceClass`/`targetClass`, which hold class ids - the same string for any class
+ * created through `Class.create`, where the id is the name.
+ *
+ * @example
+ * ```typescript
+ * // Everything except one class.
+ * { exclude: ["Draft"] }
+ *
+ * // Only these classes, plus the data model that makes them readable.
+ * { include: ["Task", "Project"] }
+ * ```
+ */
+export interface ClassFilterOptions {
+    /** Replicate only these classes. Omit to replicate all but `exclude`. */
+    include?: string[];
+    /**
+     * Never replicate these classes. Applied after `include`.
+     *
+     * This drops documents *of* those classes. The class models themselves still
+     * replicate, so the remote stays a readable replica - a class model is
+     * `~class: "class"`, not `~class: "<the class>"`. To keep a class model on the
+     * device too, add its id to `internalDocs.extraDocIds`; a class created through
+     * `Class.create` has its name as its id.
+     */
+    exclude?: string[];
+    /**
+     * Keep {@link DATA_MODEL_CLASSES} when `include` is set. Defaults to `true`; turn
+     * it off only when the remote is not meant to be a readable replica.
+     */
+    includeDataModel?: boolean;
+}
+type MaybeClassedDoc = {
+    _id?: string;
+    "~class"?: unknown;
+    "~domain"?: unknown;
+    sourceClass?: unknown;
+    targetClass?: unknown;
+    [key: string]: unknown;
+};
+/**
+ * Reports whether a set of options would filter anything at all.
+ *
+ * @param options - The class filter options.
+ * @returns `true` when at least one rule is present.
+ */
+export declare const hasClassRules: (options?: ClassFilterOptions) => boolean;
+/**
+ * Builds a class-level replication filter.
+ *
+ * PouchDB filter functions use include-semantics: `true` replicates the document. The
+ * returned function is pure and carries a configuration-derived identity so that
+ * changing which classes replicate also changes the replication checkpoint - see
+ * {@link withFilterIdentity}.
+ *
+ * Documents that carry no `~class` and no `~domain` pass through untouched. That
+ * matters for deletions: a tombstone is `{ _id, _rev, _deleted }` with no class on it,
+ * and dropping those would mean a deletion never reaches the peer.
+ *
+ * @param options - Which classes to replicate.
+ * @returns A predicate suitable for `replicate`'s `filter` option.
+ *
+ * @example
+ * ```typescript
+ * const filter = createClassFilter({ include: ["Task"] });
+ * filter({ _id: "Task-1", "~class": "Task" });                  // true
+ * filter({ _id: "Draft-1", "~class": "Draft" });                // false
+ * filter({ _id: "Task", "~class": "class" });                   // true - the data model
+ * filter({ _id: "r1", "~domain": "TaskDraft",
+ *          sourceClass: "Task", targetClass: "Draft" });        // false - dangling end
+ * ```
+ */
+export declare const createClassFilter: (options?: ClassFilterOptions) => ((doc: MaybeClassedDoc) => boolean);
+export {};

package/lib/core/sync/filter-identity.d.ts

@@ -0,0 +1,53 @@
+/**
+ * Filter identity, and why a replication filter needs one.
+ *
+ * PouchDB derives a replication's checkpoint id from the source id, the target id and
+ * `opts.filter.toString()` (`generateReplicationId` in `pouchdb-replication`). The
+ * checkpoint is what "resume where we left off" means, so two replications that share
+ * an id share a resume point.
+ *
+ * That is a problem for filters built by a factory. Every filter DocStack produces is
+ * the *same closure source text* whatever options went into it, so without help they
+ * would all hash to one checkpoint: switching a stack from `exclude: ["Draft"]` to
+ * `exclude: ["Archive"]` would resume from the old checkpoint and never re-scan history
+ * for the documents the new filter admits. They would simply be missing on the remote,
+ * with no error anywhere.
+ *
+ * Stamping the function with a `toString` derived from its configuration makes the
+ * checkpoint follow the configuration: change what you filter, and replication starts
+ * again from the beginning and backfills. Keep the configuration, and it resumes.
+ *
+ * @module
+ */
+/**
+ * Replaces a filter's `toString` with a stable, configuration-derived identity.
+ *
+ * @param filter - The filter function to stamp.
+ * @param identity - A string that changes if and only if the filter's behaviour does.
+ * @returns The same function, stamped.
+ *
+ * @example
+ * ```typescript
+ * const filter = withFilterIdentity(
+ *     (doc) => doc["~class"] !== "Draft",
+ *     describeFilter("app", { exclude: ["Draft"] })
+ * );
+ * String(filter); // "docstack-filter/1:app:{\"exclude\":[\"Draft\"]}"
+ * ```
+ */
+export declare const withFilterIdentity: <T extends (...args: any[]) => any>(filter: T, identity: string) => T;
+/**
+ * Builds the identity string for a filter of a given kind and configuration.
+ *
+ * @param kind - What sort of filter this is, e.g. `"internal"` or `"class"`.
+ * @param config - The options the filter was built from.
+ * @returns A string suitable for {@link withFilterIdentity}.
+ */
+export declare const describeFilter: (kind: string, config: unknown) => string;
+/**
+ * Combines identities for a composed filter.
+ *
+ * @param parts - The identities of the filters being composed, in order.
+ * @returns One identity covering all of them.
+ */
+export declare const composeFilterIdentity: (parts: string[]) => string;

package/lib/core/sync/index.d.ts

@@ -0,0 +1,352 @@
+import { type InternalDocFilterOptions } from "./internal-docs.js";
+import { type ClassFilterOptions } from "./class-filter.js";
+import type ClientStack from "../stack.js";
+/**
+ * Which way documents move.
+ *
+ * `"both"` runs a single bidirectional `PouchDB.sync`; the one-way values run
+ * `PouchDB.replicate` in the named direction.
+ */
+export type SyncDirection = "push" | "pull" | "both";
+/**
+ * Where a stack's replication currently stands.
+ *
+ * - `"stopped"` - never started, or cancelled.
+ * - `"starting"` - resolving the remote and running the schema gate.
+ * - `"active"` - documents are moving.
+ * - `"idle"` - a replication cycle finished with nothing left to send; this is the
+ *   state that carries a meaningful `lastConvergedAt`.
+ * - `"error"` - the last cycle failed. With `retry: true` replication keeps trying and
+ *   will return to `"active"` on its own.
+ * - `"denied"` - the remote refused a write (permissions), which retrying will not fix.
+ */
+export type SyncState = "stopped" | "starting" | "active" | "idle" | "error" | "denied";
+/**
+ * How a stack finds its remote.
+ *
+ * A function is the useful form for transports that need per-stack configuration or a
+ * credential that expires - DocStack calls it again on every {@link StackSyncHandle.restart},
+ * so a refreshed token reaches the new replication without the caller reaching into
+ * DocStack. DocStack never learns anything about the transport itself.
+ *
+ * @example
+ * ```typescript
+ * // Google Drive, one folder per stack, token owned by the application.
+ * const remote = (stack) => new PouchDB(stack.getDbName(), {
+ *     adapter: "googledrive",
+ *     accessToken: async () => auth.getAccessToken(),
+ *     folderName: `tokido/${stack.name}`,
+ * });
+ * ```
+ */
+export type RemoteResolver = string | PouchDB.Database | ((stack: ClientStack) => string | PouchDB.Database | Promise<string | PouchDB.Database>);
+/**
+ * Options for {@link ClientStack.sync}.
+ *
+ * Everything except `remote` has a working default; the defaults describe a
+ * continuous, self-healing, internal-documents-excluded sync.
+ */
+export interface StackSyncOptions {
+    /** The remote to replicate against. See {@link RemoteResolver}. */
+    remote: RemoteResolver;
+    /** Direction of travel. Defaults to `"both"`. */
+    direction?: SyncDirection;
+    /** Keep replicating as changes happen. Defaults to `true`. */
+    live?: boolean;
+    /** Retry on transient failure with PouchDB's backoff. Defaults to `true`. */
+    retry?: boolean;
+    /** Documents per batch. Passed to PouchDB as `batch_size`. */
+    batchSize?: number;
+    /** Concurrent batches. Passed to PouchDB as `batches_limit`. */
+    batchesLimit?: number;
+    /** Changes-feed heartbeat, in milliseconds, or `false` to disable. */
+    heartbeat?: number | false;
+    /** Changes-feed timeout, in milliseconds, or `false` to disable. */
+    timeout?: number | false;
+    /**
+     * Which classes replicate. See {@link ClassFilterOptions} - an allow-list keeps the
+     * data model automatically, and relations are judged by their endpoints.
+     *
+     * @example
+     * ```typescript
+     * stack.sync({ remote, classes: { exclude: ["Draft"] } });
+     * ```
+     */
+    classes?: ClassFilterOptions;
+    /**
+     * An extra predicate, ANDed with the filters above. Return `true` to replicate the
+     * document. Must be pure - PouchDB calls it once per change.
+     *
+     * Prefer `classes` where it fits: a bare function has no configuration DocStack can
+     * see, so its identity for checkpointing purposes is its own source text. Two
+     * closures over different data with the same source read as the same filter, and
+     * replication resumes where the other one left off. Build a fresh function whose
+     * source differs, or use `classes`.
+     */
+    filter?: (doc: any) => boolean;
+    /**
+     * Which of DocStack's own documents to keep on this device, or `false` to replicate
+     * everything including `~system`. `false` is for stack-to-stack mirroring of a whole
+     * database and is otherwise a bad idea. Defaults to {@link InternalDocFilterOptions}'
+     * own defaults.
+     */
+    internalDocs?: InternalDocFilterOptions | false;
+    /**
+     * Refuse to start when the remote was last written by a newer schema. Defaults to
+     * `true`. See {@link SyncSchemaMismatchError}.
+     */
+    checkSchemaVersion?: boolean;
+}
+/** A point-in-time reading of one stack's replication. */
+export interface SyncStatus {
+    /** The stack this status belongs to. */
+    stack: string;
+    /** See {@link SyncState}. */
+    state: SyncState;
+    /** Direction this handle was started with. */
+    direction: SyncDirection;
+    /** Whether the handle is following changes or ran once. */
+    live: boolean;
+    /**
+     * When the replica last converged - a cycle completed with nothing left to send.
+     * `null` until the first one. This is the value a UI should render as
+     * "last synced", not `lastActiveAt`.
+     */
+    lastConvergedAt: number | null;
+    /** When documents last moved, in either direction. */
+    lastActiveAt: number | null;
+    /** The last failure seen, kept even after replication recovers. */
+    lastError: {
+        name?: string;
+        message: string;
+        status?: number;
+    } | null;
+    /** Documents written to the remote since this handle started. */
+    pushed: number;
+    /** Documents written locally since this handle started. */
+    pulled: number;
+}
+/**
+ * Raised when a remote is ahead of this device's data model.
+ *
+ * Pulling from it would deliver documents shaped by patches this device has not
+ * applied; they would be stored verbatim (replication writes bypass validation, by
+ * design) and then fail to read back. Refusing early leaves the local stack intact and
+ * tells the application to ship the newer build.
+ */
+export declare class SyncSchemaMismatchError extends Error {
+    name: string;
+    /** The stack that refused to sync. */
+    readonly stack: string;
+    /** The schema version this device has applied, if any. */
+    readonly localVersion: string | undefined;
+    /** The schema version the remote was last written with. */
+    readonly remoteVersion: string;
+    constructor(stack: string, localVersion: string | undefined, remoteVersion: string);
+}
+/**
+ * The document DocStack keeps on a remote to record which schema wrote it.
+ *
+ * A `_local/` document on purpose: it is shared by every device talking to that remote
+ * (they all open the same database) but never replicates into anybody's stack, so it
+ * cannot be confused with the local `~system` record.
+ */
+export declare const SYNC_META_DOC_ID = "_local/docstack-sync";
+/** The contents of {@link SYNC_META_DOC_ID}. */
+export interface SyncMetaDoc {
+    _id: string;
+    _rev?: string;
+    /** Highest schema version any device has pushed to this remote. */
+    schemaVersion?: string;
+    /** Application version of the device that last wrote it, for diagnostics. */
+    appVersion?: string;
+    /** When it was last written. */
+    updatedAt: number;
+}
+/**
+ * Reads the schema version a remote was last written with.
+ *
+ * Prefers DocStack's own marker and falls back to a `~system` document, which is only
+ * present when the remote is itself a DocStack stack replicated wholesale.
+ *
+ * @param remote - The remote database.
+ * @returns The recorded version, or `null` for a remote nobody has written yet.
+ */
+export declare const readRemoteSchemaVersion: (remote: PouchDB.Database) => Promise<string | null>;
+/**
+ * Records this device's schema version on a remote, if it is the newest seen.
+ *
+ * @param remote - The remote database.
+ * @param schemaVersion - The local schema version; a missing value writes nothing.
+ * @param appVersion - The local application version, stored for diagnostics.
+ */
+export declare const publishSchemaVersion: (remote: PouchDB.Database, schemaVersion: string | undefined, appVersion?: string) => Promise<void>;
+/**
+ * One stack's replication: its lifecycle, its filter, and its convergence state.
+ *
+ * Created by {@link ClientStack.sync} - construct it through the stack rather than
+ * directly, so the stack can cancel it when it closes.
+ *
+ * Dispatches DOM events, matching the rest of DocStack: `"status"` on every state
+ * change (`detail` is a {@link SyncStatus}), plus `"change"`, `"active"`, `"idle"`,
+ * `"denied"`, `"error"` and `"complete"`.
+ *
+ * @example
+ * ```typescript
+ * const sync = await stack.sync({ remote: () => driveDb });
+ *
+ * sync.addEventListener("status", (event) => {
+ *     const status = (event as CustomEvent<SyncStatus>).detail;
+ *     ui.setSyncBadge(status.state, status.lastConvergedAt);
+ * });
+ *
+ * await sync.waitForConvergence();
+ * ```
+ */
+export declare class StackSyncHandle extends EventTarget {
+    private readonly stack;
+    private readonly options;
+    private readonly direction;
+    private readonly live;
+    private replication;
+    private remote;
+    private status;
+    private cancelled;
+    /** @internal - use {@link ClientStack.sync}. */
+    constructor(stack: ClientStack, options: StackSyncOptions);
+    /** The current reading. Safe to call at any time; returns a copy. */
+    getStatus(): SyncStatus;
+    /** The resolved remote, once {@link start} has run. */
+    getRemote(): PouchDB.Database | null;
+    /**
+     * Resolves the remote, runs the schema gate and starts replicating.
+     *
+     * @returns This handle, once replication is running. Rejects if the remote cannot
+     * be resolved or the gate refuses; the handle is left `"error"` in that case.
+     * @throws {SyncSchemaMismatchError} When the remote is ahead of this device.
+     */
+    start(): Promise<this>;
+    /**
+     * Stops replicating and releases the changes-feed listeners.
+     *
+     * Idempotent. Called for every live handle when the stack closes.
+     */
+    cancel(): void;
+    /**
+     * Cancels and starts again, re-resolving the remote.
+     *
+     * This is the call to make when a credential is refreshed: a {@link RemoteResolver}
+     * function runs again, so the new replication is built on the new token while the
+     * counters and `lastConvergedAt` this handle has accumulated stay put.
+     *
+     * @returns This handle, once replication is running again.
+     */
+    restart(): Promise<this>;
+    /**
+     * Resolves the next time the replica converges.
+     *
+     * @param timeoutMs - How long to wait before rejecting. Defaults to 30 seconds;
+     * pass `0` to wait indefinitely.
+     * @returns The status at the moment of convergence.
+     */
+    waitForConvergence(timeoutMs?: number): Promise<SyncStatus>;
+    private resolveRemote;
+    private checkSchema;
+    /**
+     * Composes the filter chain: DocStack's internal-document rules, then the caller's
+     * class rules, then their own predicate. All three use include-semantics, so the
+     * chain is a conjunction - a document replicates only if every stage admits it.
+     *
+     * The composed function carries an identity derived from every stage's
+     * configuration. PouchDB hashes `filter.toString()` into the replication checkpoint,
+     * and without that these closures would all render as the same source text: changing
+     * which classes replicate would silently resume from the previous configuration's
+     * checkpoint and never backfill the newly-admitted documents.
+     */
+    /**
+     * The document ids this stack's configured patches seed.
+     *
+     * Empty when the stack was opened without patches, which is the common case.
+     */
+    /**
+     * Class names declared ephemeral, resolved once when replication starts.
+     *
+     * See {@link ClassModel.ephemeral}.
+     */
+    private ephemeralClasses;
+    private seededDocIdsFromPatches;
+    private buildFilter;
+    private buildReplicationOptions;
+    private startReplication;
+    private wireCommonEvents;
+    private onChange;
+    private markConverged;
+    private recordError;
+    private describeError;
+    private setState;
+}
+/** Options for {@link DocStack.sync}, which starts one handle per stack. */
+export interface DocStackSyncOptions extends Omit<StackSyncOptions, "remote"> {
+    /**
+     * The remote for a given stack. Called once per stack, so an application with a
+     * database per workspace answers with a folder per workspace.
+     */
+    remote: RemoteResolver;
+    /**
+     * Which stacks to sync. Defaults to all of them.
+     */
+    stacks?: string[];
+    /**
+     * The tenant entitlement this replication serves, compiled into per-stack
+     * configuration by {@link deriveTenantScope}: stacks outside the scope are not
+     * synced at all - withheld structurally, not filtered - and stacks holding a mix of
+     * declarations get a class filter. Combines with `stacks` (which pre-narrows the
+     * candidates) but not with `classes`, whose slot the compiled rules occupy; narrow
+     * further with `filter`. See ADR-0030.
+     */
+    tenants?: string[];
+}
+/**
+ * Every stack's replication under one object.
+ *
+ * Returned by {@link DocStack.sync}. Holds one {@link StackSyncHandle} per stack and
+ * re-dispatches their `"status"` events, so an application renders one badge from one
+ * listener however many databases it has open.
+ *
+ * @example
+ * ```typescript
+ * const sync = await docstack.sync({ remote: (stack) => driveFor(stack.name) });
+ * sync.addEventListener("status", () => render(sync.getStatus()));
+ * ```
+ */
+export declare class DocStackSyncHandle extends EventTarget {
+    /** One handle per stack, keyed by stack name. */
+    readonly handles: Map<string, StackSyncHandle>;
+    /** @internal - use {@link DocStack.sync}. */
+    add(name: string, handle: StackSyncHandle): void;
+    /** The stacks this handle covers. What is missing from this list is not
+     *  replicating - compare against `DocStack.getStacks()`, or use
+     *  `DocStack.getSyncCoverage()` which does exactly that. */
+    get names(): string[];
+    /** @internal - use {@link DocStack.removeStack}. Cancels and drops one stack's
+     *  replication; the rest are untouched. */
+    remove(name: string): boolean;
+    /** Every stack's status, keyed by stack name. */
+    getStatus(): Record<string, SyncStatus>;
+    /**
+     * The oldest convergence across all stacks - the honest answer to "when was
+     * everything last up to date". `null` while any stack has never converged.
+     */
+    getLastConvergedAt(): number | null;
+    /** Cancels every stack's replication. */
+    cancel(): void;
+    /** Restarts every stack's replication, re-resolving each remote. */
+    restart(): Promise<void>;
+}
+export { createReplicationFilter, isInternalDoc, resolveInternalClasses, INTERNAL_DOC_IDS, INTERNAL_DOC_ID_PREFIXES, INTERNAL_DOC_CLASSES, OPTIONAL_INTERNAL_DOC_CLASSES, } from "./internal-docs.js";
+export type { InternalDocFilterOptions } from "./internal-docs.js";
+export { createClassFilter, hasClassRules, DATA_MODEL_CLASSES } from "./class-filter.js";
+export type { ClassFilterOptions } from "./class-filter.js";
+export { deriveTenantScope, classTenants } from "./tenants.js";
+export type { TenantScope } from "./tenants.js";
+export { withFilterIdentity, describeFilter, composeFilterIdentity } from "./filter-identity.js";

package/lib/core/sync/internal-docs.d.ts

@@ -0,0 +1,159 @@
+/**
+ * The taxonomy of documents a DocStack stack keeps for itself.
+ *
+ * Every stack writes a handful of documents that describe *this device's copy* of the
+ * database rather than its contents: the system record, the crypto marker, the local
+ * patch ledger, class-propagation locks, Mango design documents. Replicating those is
+ * never right - two devices each write their own, so they collide on identical ids
+ * with unrelated revisions, and pulling a peer's `~system` document would hand
+ * `checkSystem` a schema version the local patches have not reached.
+ *
+ * The list lives here, in the client, because only DocStack knows it - an application
+ * author cannot guess it and the set grows as DocStack does.
+ *
+ * @module
+ */
+/**
+ * Document identifiers that are device-local in full.
+ *
+ * - `~system` carries this database's `dbInfo`, `startupTime` and, critically, the
+ *   `schemaVersion` that {@link ClientStack.checkSystem} reads on every mount.
+ * - `~crypto-engine-config` is the marker that pins a database to its encryption
+ *   setting; a peer's copy says nothing about this one.
+ * - `lastDocId` is a local id counter.
+ */
+export declare const INTERNAL_DOC_IDS: readonly string[];
+/**
+ * Identifier prefixes that mark a document as device-local.
+ *
+ * - `_local/` never replicates in PouchDB anyway; listed so the predicate is usable
+ *   outside a replication filter too.
+ * - `_design/` documents are Mango indexes built on demand by
+ *   {@link ClientStack.addDesignDocumentPKs}, including the `-temp` variants.
+ * - `~lock-` guards an in-flight class-model propagation on *this* device.
+ * - `~log-` is this client's own diagnostic record. Replicating diagnostics costs quota,
+ *   bandwidth and remote storage on every sync, in both directions, and tells a peer
+ *   nothing it can use - `logLevel: 'info'` should not be a network cost. They used to
+ *   carry neither a `~class` nor a recognisable id, so all of them replicated: 111 of
+ *   134 documents on one measured remote. See ADR-0023.
+ */
+export declare const INTERNAL_DOC_ID_PREFIXES: readonly string[];
+/**
+ * `~class` values whose documents describe device-local state.
+ *
+ * - `~lock` guards an in-flight class-model propagation on *this* device.
+ * - `~JobRun` records that *this* client ran a job. A peer's execution history is not
+ *   something this one can act on, and both write their own.
+ */
+export declare const INTERNAL_DOC_CLASSES: readonly string[];
+/**
+ * `~class` values that are device-local by default but that a caller may choose to
+ * replicate. Sessions belong to the device that authenticated; the patch ledger is
+ * written by whichever device applied the patch, and patches themselves ship with the
+ * application code rather than through the database.
+ */
+export declare const OPTIONAL_INTERNAL_DOC_CLASSES: {
+    /** `~UserSession` - one per device, per login. */
+    readonly sessions: "~UserSession";
+    /** `patch` - the local record of which patches this device has applied. */
+    readonly patchLedger: "patch";
+};
+/**
+ * Options controlling which of DocStack's own documents stay on this device.
+ *
+ * @example
+ * ```typescript
+ * // Replicate the patch ledger too, and keep an app-specific draft class local.
+ * const filter = createReplicationFilter({
+ *     replicatePatchLedger: true,
+ *     extraClasses: ["Draft"],
+ * });
+ * ```
+ */
+export interface InternalDocFilterOptions {
+    /** Replicate `~UserSession` documents. Defaults to `false`. */
+    replicateSessions?: boolean;
+    /**
+     * Replicate the documents the system patches seed - the `~*` class models,
+     * `Group-Admin`, `Policy-Admin`, `AuthMod-Classic`, the bootstrap `class` and
+     * `domain`, the `system` user. Defaults to `false`, because every client applies
+     * those patches for itself and so already holds them.
+     *
+     * This does *not* govern documents of DocStack's classes that an application created
+     * - an account, a group, a policy written at runtime. Those bind the synchronised
+     * group together and always replicate.
+     */
+    replicateSystemDocuments?: boolean;
+    /**
+     * Class names declared `ephemeral`, whose documents describe one run of one client.
+     *
+     * See {@link ClassModel.ephemeral}. {@link ClientStack.sync} fills this in from the
+     * stack's own class models, so a class declared ephemeral is excluded structurally
+     * rather than by the filter recognising a payload shape.
+     */
+    ephemeralClasses?: string[];
+    /**
+     * Document ids an application's own patches seed, treated like the system-seeded ones.
+     *
+     * Consumer patches are applied on every client too, so the documents they seed are
+     * reconstructible everywhere and need not travel. {@link ClientStack.sync} fills this
+     * in from the stack's configured patches.
+     */
+    extraSeededDocIds?: string[];
+    /** Replicate the local `patch` ledger. Defaults to `false`. */
+    replicatePatchLedger?: boolean;
+    /** Additional exact document ids to keep device-local. */
+    extraDocIds?: string[];
+    /** Additional id prefixes to keep device-local. */
+    extraIdPrefixes?: string[];
+    /** Additional `~class` values to keep device-local. */
+    extraClasses?: string[];
+}
+/** The shape the predicates need: anything with an id and possibly a `~class`. */
+type MaybeInternalDoc = {
+    _id?: string;
+    "~class"?: unknown;
+    [key: string]: unknown;
+};
+/**
+ * Resolves the full set of device-local classes for a given set of options.
+ *
+ * @param options - Filter options; defaults keep sessions and the patch ledger local.
+ * @returns The `~class` values that should not leave this device.
+ */
+export declare const resolveInternalClasses: (options?: InternalDocFilterOptions) => string[];
+/**
+ * Reports whether a document describes device-local state rather than stack data.
+ *
+ * @param doc - The document to classify. A missing or id-less value counts as internal,
+ * so a malformed change never escapes to a remote.
+ * @param options - Which of the optional categories to treat as replicable.
+ * @returns `true` when the document should stay on this device.
+ *
+ * @example
+ * ```typescript
+ * isInternalDoc({ _id: "~system" });                       // true
+ * isInternalDoc({ _id: "Task-1", "~class": "Task" });       // false
+ * isInternalDoc({ _id: "sess-a", "~class": "~UserSession" }); // true
+ * isInternalDoc({ _id: "sess-a", "~class": "~UserSession" }, { replicateSessions: true }); // false
+ * ```
+ */
+export declare const isInternalDoc: (doc: MaybeInternalDoc | null | undefined, options?: InternalDocFilterOptions) => boolean;
+/**
+ * Builds the replication filter DocStack passes to PouchDB.
+ *
+ * PouchDB filter functions use include-semantics: returning `true` replicates the
+ * document. The returned function is pure and closes over nothing but the resolved
+ * option lists, so it is safe to hand to `PouchDB.replicate`/`PouchDB.sync`, which
+ * call it once per change on the source's changes feed.
+ *
+ * @param options - Which of the optional categories to treat as replicable.
+ * @returns A predicate suitable for `replicate`'s `filter` option.
+ *
+ * @example
+ * ```typescript
+ * PouchDB.sync(local, remote, { live: true, retry: true, filter: createReplicationFilter() });
+ * ```
+ */
+export declare const createReplicationFilter: (options?: InternalDocFilterOptions) => ((doc: MaybeInternalDoc) => boolean);
+export {};