mindoodb 0.0.2 → 0.0.4

package/dist/core/types.d.ts

@@ -1,4 +1,5 @@
 import type { KeyBag } from "./keys/KeyBag";
+import type { KeyType } from "./keys/KeyContext";
 import type { PublicUserId, PrivateUserId } from "./userid";
 import type { ContentAddressedStore, OpenStoreOptions } from "./appendonlystores/types";
 import type { CryptoAdapter } from "./crypto/CryptoAdapter";
@@ -7,8 +8,27 @@ import { MindooDocSigner } from "./crypto/MindooDocSigner";
  * Well-known key ID for access control documents (grantaccess, revokeaccess, groups).
  * All servers and clients MUST have this key in their KeyBag to verify user access.
  * This enables servers to validate users without having full tenant data access.
+ *
+ * KeyBag location: type "doc", id PUBLIC_INFOS_KEY_ID.
  */
 export declare const PUBLIC_INFOS_KEY_ID = "$publicinfos";
+/**
+ * Well-known key ID for the tenant-wide default document encryption key.
+ *
+ * KeyBag location: type "doc", id DEFAULT_TENANT_KEY_ID.
+ */
+export declare const DEFAULT_TENANT_KEY_ID = "default";
+/**
+ * JSON payload returned by `GET /.well-known/mindoodb-server-info`.
+ */
+export interface MindooDBServerInfo {
+    /** Canonical server name, typically a Notes/Domino-style DN. */
+    name: string;
+    /** Ed25519 public key in PEM format used for signing/auth verification. */
+    signingPublicKey: string;
+    /** RSA-OAEP public key in PEM format used for encryption. */
+    encryptionPublicKey: string;
+}
 /**
  * An EncryptedPrivateKey is a private key that is encrypted with a password.
  * Used for both asymmetric keys (RSA, Ed25519, ECDH) and symmetric keys (AES-256).
@@ -59,48 +79,169 @@ export interface EncryptionKeyPair {
     privateKey: EncryptedPrivateKey;
 }
 export type { PublicUserId, PrivateUserId };
+export type { KeyType };
 /**
- * A TenantFactory is a factory for creating and managing tenants.
+ * Options for opening a tenant.
  */
-export interface MindooTenantFactory {
+export interface OpenTenantOptions {
     /**
-     * Create a new tenant with a new tenant encryption key.
+     * Optional map of additional trusted signing public keys.
+     * Keys in this map are checked BEFORE the MindooTenantDirectory when
+     * validating public signing keys during signature verification.
      *
-     * The tenant encryption key is used as the default document encryption key
-     * (so that all data within the tenant is secure by default).
+     * Use case: server-to-server sync where trusted server identities are
+     * configured out-of-band (e.g. server-env.json) rather than registered
+     * in the directory database.
      *
-     * The administration public key must be created beforehand using createSigningKeyPair()
-     * and passed to this method. The administration key is used for administrative operations
-     * within the tenant, such as adding new users to the tenant.
-     *
-     * The administration encryption public key must be created using createEncryptionKeyPair()
-     * and is used to encrypt sensitive data in the directory that only admins can decrypt
-     * (e.g., usernames in access control documents).
-     *
-     * @param tenantId The ID of the tenant
-     * @param administrationPublicKey The administration public key (Ed25519, PEM format) created using createSigningKeyPair()
-     * @param administrationEncryptionPublicKey The administration encryption public key (RSA-OAEP, PEM format) created using createEncryptionKeyPair()
-     * @param tenantEncryptionKeyPassword The password to be set to decrypt the tenant encryption private key
-     * @param currentUser The current user's private user ID (required for tenant operations)
-     * @param currentUserPassword The password to decrypt the current user's private keys
-     * @param keyBag The KeyBag instance for storing and loading named encrypted keys
-     * @return The new tenant
+     * Map key: signing public key (Ed25519, PEM format)
+     * Map value: true if trusted, false if explicitly revoked
      */
-    createTenant(tenantId: string, administrationPublicKey: string, administrationEncryptionPublicKey: string, tenantEncryptionKeyPassword: string, currentUser: PrivateUserId, currentUserPassword: string, keyBag: KeyBag): Promise<MindooTenant>;
+    additionalTrustedKeys?: ReadonlyMap<string, boolean>;
+}
+interface CreateTenantPasswords {
+    /** Password for the admin user's private keys */
+    adminPassword: string;
+    /** Password for the regular user's private keys */
+    userPassword: string;
+}
+/**
+ * Options for creating a new tenant with a single convenience call.
+ */
+export type CreateTenantOptions = ({
+    /** Tenant identifier (e.g. "acme") */
+    tenantId: string;
+    /** Distinguished name for the admin user (e.g. "cn=admin/o=acme") */
+    adminName: string;
+    /** Distinguished name for the regular app user (e.g. "cn=alice/o=acme") */
+    userName: string;
+} & CreateTenantPasswords) | ({
+    /** Tenant identifier (e.g. "acme") */
+    tenantId: string;
+    /** Existing admin private identity */
+    adminUser: PrivateUserId;
+    /** Existing regular app user private identity */
+    appUser: PrivateUserId;
+} & CreateTenantPasswords);
+/**
+ * Result of creating a new tenant via createTenant().
+ */
+export interface CreateTenantResult {
+    /** The opened tenant, ready to use */
+    tenant: MindooTenant;
+    /** The admin user's private identity (contains signing + encryption key pairs) */
+    adminUser: PrivateUserId;
+    /** The regular app user's private identity */
+    appUser: PrivateUserId;
+    /** The KeyBag containing the tenant key and tenant-scoped doc keys */
+    keyBag: KeyBag;
+}
+/**
+ * A join request is created by a new user who wants to join a tenant.
+ * It contains only public information and is safe to share via any channel.
+ *
+ * Can be serialized to a mdb://join-request/... URI for out-of-band exchange.
+ */
+export interface JoinRequest {
+    /** Protocol version (always 1 for now) */
+    v: 1;
+    /** The username the user wants to be registered as (e.g. "cn=user2/o=acme") */
+    username: string;
+    /** Ed25519 public signing key (PEM format) */
+    signingPublicKey: string;
+    /** RSA-OAEP public encryption key (PEM format) */
+    encryptionPublicKey: string;
+}
+/**
+ * Options for approving a join request.
+ */
+export interface ApproveJoinRequestOptions {
+    /** The admin's encrypted private signing key */
+    adminSigningKey: EncryptedPrivateKey;
+    /** The password to decrypt the admin signing key */
+    adminPassword: string;
+    /** A shared password for encrypting the exported keys. Must be communicated out-of-band (e.g. phone). */
+    sharePassword: string;
+    /** Optional server URL to include in the response so the joining user knows where to sync */
+    serverUrl?: string;
+    /** If "uri", approveJoinRequest returns a mdb://join-response/... URI string instead of an object */
+    format?: "object" | "uri";
+}
+/**
+ * A join response is created by the admin after approving a join request.
+ * It contains encrypted symmetric keys and tenant metadata needed to join.
+ *
+ * Can be serialized to a mdb://join-response/... URI for out-of-band exchange.
+ * The encrypted keys can only be unlocked with the sharePassword communicated separately.
+ */
+export interface JoinResponse {
+    /** Protocol version (always 1 for now) */
+    v: 1;
+    /** Tenant identifier */
+    tenantId: string;
+    /** Admin's public signing key (Ed25519, PEM) — needed to open the tenant */
+    adminSigningPublicKey: string;
+    /** Admin's public encryption key (RSA-OAEP, PEM) — needed to open the tenant */
+    adminEncryptionPublicKey: string;
+    /** Optional server URL for sync */
+    serverUrl?: string;
+    /** Tenant symmetric key, encrypted with the sharePassword */
+    encryptedTenantKey: EncryptedPrivateKey;
+    /** $publicinfos symmetric key, encrypted with the sharePassword */
+    encryptedPublicInfosKey: EncryptedPrivateKey;
+}
+/**
+ * Options for joining a tenant with a join response.
+ */
+export interface JoinTenantOptions {
+    /** The user's locally-generated private identity (keys never leave this device) */
+    user: PrivateUserId;
+    /** The password for the user's private keys */
+    password: string;
+    /** The shared password used to decrypt the keys in the join response */
+    sharePassword: string;
+}
+/**
+ * Result of joining a tenant via joinTenant().
+ */
+export interface JoinTenantResult {
+    /** The opened tenant, ready to use */
+    tenant: MindooTenant;
+    /** The KeyBag containing the imported tenant and $publicinfos keys */
+    keyBag: KeyBag;
+}
+/**
+ * Options for publishing a tenant to a server.
+ */
+export interface PublishToServerOptions {
+    /** System admin identity (PrivateUserId) for challenge/response auth. */
+    systemAdminUser?: PrivateUserId;
+    /** Password to decrypt systemAdminUser's private keys. */
+    systemAdminPassword?: string;
+    /** Optional admin username for bootstrap handshake on the server */
+    adminUsername?: string;
+    /** Optional users to register on the server at the same time */
+    registerUsers?: PublicUserId[];
+}
+/**
+ * A TenantFactory is a factory for creating and managing tenants.
+ */
+export interface MindooTenantFactory {
     /**
-     * Opens an existing tenant with previously created keys.
+     * Opens an existing tenant.
      *
      * @param tenantId The ID of the tenant
-     * @param tenantEncryptionPrivateKey The tenant encryption key (AES-256, encrypted)
-     * @param tenantEncryptionKeyPassword The password to decrypt the tenant encryption key
      * @param administrationPublicKey The administration public key (Ed25519, PEM format)
      * @param administrationEncryptionPublicKey The administration encryption public key (RSA-OAEP, PEM format)
      * @param currentUser The current user's private user ID (required for tenant operations)
      * @param currentUserPassword The password to decrypt the current user's private keys
-     * @param keyBag The KeyBag instance for storing and loading named encrypted keys
+     * @param keyBag The KeyBag instance for storing and loading tenant/doc keys.
+     *               Must contain:
+     *               - $publicinfos key under type "doc", tenant id tenantId, and id PUBLIC_INFOS_KEY_ID
+     *               Optionally (required for decrypting regular database payloads):
+     *               - tenant key under type "tenant" and id tenantId
      * @return The tenant
      */
-    openTenantWithKeys(tenantId: string, tenantEncryptionPrivateKey: EncryptedPrivateKey, tenantEncryptionKeyPassword: string, administrationPublicKey: string, administrationEncryptionPublicKey: string, currentUser: PrivateUserId, currentUserPassword: string, keyBag: KeyBag): Promise<MindooTenant>;
+    openTenant(tenantId: string, administrationPublicKey: string, administrationEncryptionPublicKey: string, currentUser: PrivateUserId, currentUserPassword: string, keyBag: KeyBag, options?: OpenTenantOptions): Promise<MindooTenant>;
     /**
      * Creates a new user with separate signing and encryption key pairs.
      *
@@ -116,6 +257,15 @@ export interface MindooTenantFactory {
      * @return The public user ID
      */
     toPublicUserId(privateUserId: PrivateUserId): PublicUserId;
+    /**
+     * Re-encrypts an identity's private keys with a new password.
+     *
+     * @param identity The private identity to update
+     * @param oldPassword The current password
+     * @param newPassword The new password to protect both private keys
+     * @return A new PrivateUserId with unchanged public keys and re-encrypted private keys
+     */
+    changeIdentityPassword(identity: PrivateUserId, oldPassword: string, newPassword: string): Promise<PrivateUserId>;
     /**
      * Creates a new signing key pair for the tenant.
      * Returns both the public and encrypted private key, as the public key is needed
@@ -125,18 +275,6 @@ export interface MindooTenantFactory {
      * @return The signing key pair containing both public key (PEM format) and encrypted private key (Ed25519)
      */
     createSigningKeyPair(password: string): Promise<SigningKeyPair>;
-    /**
-     * Creates a new encrypted symmetric key (AES-256) for document encryption.
-     * The key is encrypted with the provided password and can be distributed to authorized users.
-     * Use KeyBag.decryptAndImportKey() to store the returned key in the user's KeyBag.
-     *
-     * Symmetric keys are shared secrets - anyone with the key can both encrypt and decrypt.
-     * For user-to-user encryption where only the recipient can decrypt, use createEncryptionKeyPair() instead.
-     *
-     * @param password The password to encrypt the symmetric key with (mandatory)
-     * @return The encrypted symmetric key that can be distributed to authorized users
-     */
-    createSymmetricEncryptedPrivateKey(password: string): Promise<EncryptedPrivateKey>;
     /**
      * Creates a new asymmetric encryption key pair (RSA-OAEP) for user-to-user encryption.
      * Returns both the public and encrypted private key.
@@ -149,6 +287,47 @@ export interface MindooTenantFactory {
      * @return The encryption key pair containing both public key (PEM format) and encrypted private key (RSA-OAEP)
      */
     createEncryptionKeyPair(password: string): Promise<EncryptionKeyPair>;
+    /**
+     * Create a new tenant with a single call. This orchestrates:
+     * 1. Creating the admin user identity
+     * 2. Creating the regular app user identity
+     * 3. Creating a KeyBag with tenant key and $publicinfos key
+     * 4. Opening the tenant
+     * 5. Registering the app user in the directory
+     *
+     * @param options Tenant creation options
+     * @return The created tenant, admin user, app user, and KeyBag
+     */
+    createTenant(options: CreateTenantOptions): Promise<CreateTenantResult>;
+    /**
+     * Create a join request from a user's private identity.
+     * The join request contains only public keys and is safe to share via any channel.
+     *
+     * @param user The user's private identity (only public keys are extracted)
+     * @param options Optional. Set format to "uri" to get a mdb://join-request/... URI string.
+     * @return A JoinRequest object or a mdb://join-request/... URI string
+     */
+    createJoinRequest(user: PrivateUserId, options?: {
+        format?: "object";
+    }): JoinRequest;
+    createJoinRequest(user: PrivateUserId, options: {
+        format: "uri";
+    }): string;
+    createJoinRequest(user: PrivateUserId, options?: {
+        format?: "object" | "uri";
+    }): JoinRequest | string;
+    /**
+     * Join a tenant using a join response from an admin.
+     * This orchestrates:
+     * 1. Parsing the join response (object or mdb:// URI string)
+     * 2. Creating a new KeyBag and importing the encrypted keys
+     * 3. Opening the tenant with the admin public keys from the response
+     *
+     * @param joinResponse A JoinResponse object or a mdb://join-response/... URI string
+     * @param options Options including the user's identity, password, and the shared password
+     * @return The opened tenant and KeyBag
+     */
+    joinTenant(joinResponse: JoinResponse | string, options: JoinTenantOptions): Promise<JoinTenantResult>;
 }
 /**
  * A MindooTenant contains multiple MindooDB in an organization. One MindooDB is a mandatory part
@@ -188,15 +367,6 @@ export interface MindooTenant {
      * @return The administration encryption public key (RSA-OAEP, PEM format)
      */
     getAdministrationEncryptionPublicKey(): string;
-    /**
-     * Returns the encryption key used to encrypt all communication in this tenant
-     * (e.g. the document changesets).
-     *
-     * Note: This is a symmetric key (AES-256) used ONLY for encryption/decryption, not for signing.
-     *
-     * @return The tenant encryption key (AES-256, encrypted)
-     */
-    getTenantEncryptionKey(): EncryptedPrivateKey;
     /**
      * Encrypt a payload using the symmetric key identified by decryptionKeyId.
      * For "default", uses the tenant encryption key.
@@ -294,8 +464,45 @@ export interface MindooTenant {
      * @return The crypto adapter
      */
     getCryptoAdapter(): CryptoAdapter;
+    /**
+     * Approve a join request and produce a join response.
+     * This orchestrates:
+     * 1. Parsing the join request (object or mdb:// URI string)
+     * 2. Registering the user in the tenant directory
+     * 3. Exporting the tenant key and $publicinfos key, encrypted with the sharePassword
+     * 4. Packaging everything into a JoinResponse
+     *
+     * @param joinRequest A JoinRequest object or a mdb://join-request/... URI string
+     * @param options Options including admin key, share password, and optional server URL
+     * @return A JoinResponse object, or a mdb://join-response/... URI string if format is "uri"
+     */
+    approveJoinRequest(joinRequest: JoinRequest | string, options: ApproveJoinRequestOptions & {
+        format: "uri";
+    }): Promise<string>;
+    approveJoinRequest(joinRequest: JoinRequest | string, options: ApproveJoinRequestOptions): Promise<JoinResponse>;
+    /**
+     * Publish (register) this tenant on a MindooDB server.
+     * Sends an HTTP POST to the server's /admin/register-tenant endpoint
+     * with the admin public keys and optional initial users.
+     *
+     * @param serverUrl The base URL of the MindooDB server (e.g. "http://localhost:3000")
+     * @param options Optional API key and users to register
+     */
+    publishToServer(serverUrl: string, options?: PublishToServerOptions): Promise<void>;
+    /**
+     * Create a remote store connected to a MindooDB server, ready for sync.
+     * This orchestrates:
+     * 1. Creating an HttpTransport pointed at the server
+     * 2. Creating a ClientNetworkContentAddressedStore with the current user's keys
+     * 3. Returning the store for use with pullChangesFrom/pushChangesTo
+     *
+     * @param serverUrl The base URL of the MindooDB server (e.g. "http://localhost:3000")
+     * @param dbId The database ID to connect to (e.g. "todos")
+     * @return A ContentAddressedStore connected to the remote server
+     */
+    connectToServer(serverUrl: string, dbId: string): Promise<ContentAddressedStore>;
 }
-export type { ContentAddressedStore, ContentAddressedStoreFactory, CreateStoreResult, OpenStoreOptions } from "./appendonlystores/types";
+export type { ContentAddressedStore, ContentAddressedStoreFactory, CreateStoreResult, OpenStoreOptions, StoreCompactionStatus, StoreScanCursor, StoreScanFilters, StoreScanResult, StoreIdBloomSummary, MaterializationPlanOptions, MaterializationPlanDiagnostics, DocumentMaterializationPlan, DocumentMaterializationBatchPlan, } from "./appendonlystores/types";
 /**
  * The type of entry stored in the ContentAddressedStore.
  * Entry types are prefixed to indicate their domain:
@@ -341,6 +548,18 @@ export interface StoreEntryMetadata {
      * - For attachment_chunk: Previous chunk's entry ID (enables append-only file growth)
      */
     dependencyIds: string[];
+    /**
+     * Optional causal coverage heads for snapshot entries.
+     * For `doc_snapshot`, this lists the Automerge head hashes represented by the snapshot.
+     * For other entry types this should be undefined.
+     */
+    snapshotHeadHashes?: string[];
+    /**
+     * Optional entry IDs corresponding to the snapshot heads.
+     * This allows stores to plan replay using metadata only, without decrypting payloads.
+     * For non-snapshot entries this should be undefined.
+     */
+    snapshotHeadEntryIds?: string[];
     /**
      * The timestamp when this entry was created (milliseconds since Unix epoch).
      */
@@ -441,6 +660,46 @@ export interface AttachmentConfig {
      */
     chunkSizeBytes?: number;
 }
+/**
+ * Configuration for the in-memory document cache.
+ */
+export interface DocumentCacheConfig {
+    /**
+     * Maximum number of fully materialized documents kept in memory at once.
+     * Dirty documents remain pinned until cache state has been flushed.
+     * Default: 128
+     */
+    maxEntries?: number;
+    /**
+     * Number of upcoming documents to prefetch during changefeed iteration.
+     * Set to 0 to disable eager iteration prefetch.
+     * Default: 0
+     */
+    iteratePrefetchWindowDocs?: number;
+    /**
+     * Maximum number of documents restored from the local cache store during
+     * startup.  Prevents large cache checkpoints from rehydrating every
+     * document into memory immediately.
+     * Default: same as `maxEntries`
+     */
+    restoreLimit?: number;
+}
+/**
+ * Configuration for automatic snapshot creation.
+ */
+export interface SnapshotConfig {
+    /**
+     * Minimum number of replay entries since the latest snapshot before a new
+     * snapshot is considered.
+     * Default: 100
+     */
+    minChanges?: number;
+    /**
+     * Minimum time between snapshot writes for the same document.
+     * Default: 10 minutes
+     */
+    cooldownMs?: number;
+}
 /**
  * A MindooDoc is a document that is stored in the MindooDB.
  * It's a wrapper around the Automerge document.
@@ -579,6 +838,15 @@ export interface MindooDoc {
 export interface MindooDocPayload {
     [key: string]: unknown;
 }
+export interface DirectoryUserDetails {
+    [key: string]: string;
+}
+export interface DirectoryUserLookup {
+    username: string;
+    signingPublicKey: string;
+    encryptionPublicKey: string;
+    details: DirectoryUserDetails | null;
+}
 export interface MindooTenantDirectory {
     /**
      * Adds a new user to the tenant. The user is identified by its user ID.
@@ -589,7 +857,7 @@ export interface MindooTenantDirectory {
      * @param administrationPrivateKeyPassword The password to decrypt the administration private key
      * @return A promise that resolves when the user is registered
      */
-    registerUser(userId: PublicUserId, administrationPrivateKey: EncryptedPrivateKey, administrationPrivateKeyPassword: string): Promise<void>;
+    registerUser(userId: PublicUserId, administrationPrivateKey: EncryptedPrivateKey, administrationPrivateKeyPassword: string, userDetails?: DirectoryUserDetails): Promise<void>;
     /**
      * Revokes a user's access to the tenant by adding a revocation record to the directory.
      * This prevents the user from decrypting future changes, but they retain access to previously
@@ -620,7 +888,16 @@ export interface MindooTenantDirectory {
     getUserPublicKeys(username: string): Promise<{
         signingPublicKey: string;
         encryptionPublicKey: string;
+        details?: DirectoryUserDetails | null;
     } | null>;
+    /**
+     * Look up a user by their public signing key.
+     * This is useful for reverse-resolving historical change authors to friendly labels.
+     *
+     * @param publicKey The public signing key to look up (Ed25519, PEM format)
+     * @return The matching user record, or null if no registration is known
+     */
+    getUserBySigningPublicKey(publicKey: string): Promise<DirectoryUserLookup | null>;
     /**
      * Check if a user has been revoked.
      *
@@ -691,6 +968,14 @@ export interface MindooTenantDirectory {
      * @return The latest DB settings document, or null if none exists
      */
     getDBSettings(dbId: string): Promise<MindooDoc | null>;
+    /**
+     * Returns the database IDs currently known to the directory.
+     *
+     * This is intended for admin tooling and overview UIs. The result always includes
+     * `"directory"` and will also include `"main"` as the conventional default app DB.
+     * Additional DBs are discovered from `dbsettings` documents stored in the directory.
+     */
+    listKnownDBIds(): Promise<string[]>;
     /**
      * Create or update database-specific settings.
      * Automatically uses the cached settings document for the given dbId if it exists, or creates a new one.
@@ -717,6 +1002,11 @@ export interface MindooTenantDirectory {
      * @param groupName The name of the group to look up (case-insensitive, converted to lowercase)
      * @return The members of the group
      */
+    /**
+     * Get the decrypted member names for a group.
+     * Entries that cannot be decrypted are skipped so callers can still work with
+     * the readable subset of the group.
+     */
     getGroupMembers(groupName: string): Promise<string[]>;
     /**
      * Deletes a group. Does nothing if the group does not exist.
@@ -766,13 +1056,20 @@ export interface MindooTenantDirectory {
  * and prevent duplicate processing when multiple documents have the same timestamp.
  */
 export interface ProcessChangesCursor {
+    /**
+     * Monotonic changefeed sequence number assigned by BaseMindooDB.
+     * This is the primary cursor field for deterministic, gap-free iteration.
+     */
+    changeSeq?: number;
     /**
      * The timestamp of the last processed change (milliseconds since Unix epoch)
+     * Legacy compatibility field. New code should use `changeSeq`.
      */
     lastModified: number;
     /**
      * The document ID of the last processed change.
      * Used to break ties when multiple documents have the same timestamp.
+     * Legacy compatibility field. New code should use `changeSeq`.
      */
     docId: string;
 }
@@ -790,6 +1087,28 @@ export interface ProcessChangesResult {
      */
     cursor: ProcessChangesCursor;
 }
+/**
+ * Result yielded by the metadata-only latest-state iterator.
+ * Contains the latest known index metadata without materializing the document.
+ */
+export interface ProcessChangeSummaryResult {
+    /**
+     * The document ID that changed.
+     */
+    docId: string;
+    /**
+     * Latest user-visible modification timestamp for the document.
+     */
+    lastModified: number;
+    /**
+     * Whether the latest known state is deleted.
+     */
+    isDeleted: boolean;
+    /**
+     * The cursor position of this document in the deterministic changefeed.
+     */
+    cursor: ProcessChangesCursor;
+}
 /**
  * Result yielded by the iterateDocumentHistory generator.
  */
@@ -823,6 +1142,18 @@ export interface OpenDBOptions extends OpenStoreOptions {
      * If not provided, defaults are used.
      */
     attachmentConfig?: AttachmentConfig;
+    /**
+     * Configuration for the in-memory materialized document cache.
+     */
+    documentCacheConfig?: DocumentCacheConfig;
+    /**
+     * Configuration for automatic snapshot creation.
+     */
+    snapshotConfig?: SnapshotConfig;
+    /**
+     * Optional performance callback for profiling hot paths.
+     */
+    performanceCallback?: PerformanceCallback;
 }
 /**
  * Optional performance callback interface for tracking operation timing.
@@ -835,6 +1166,9 @@ export interface PerformanceCallback {
     onDocumentLoad?: (metrics: {
         docId: string;
         cacheHit: boolean;
+        metadataEntriesScanned: number;
+        replayEntriesLoaded: number;
+        snapshotUsed: boolean;
         cacheCheckTime: number;
         storeQueryTime: number;
         entryLoadTime: number;
@@ -855,10 +1189,107 @@ export interface PerformanceCallback {
      * Called during sync operations.
      */
     onSyncOperation?: (metrics: {
-        operation: 'findNewEntries' | 'processDocument' | 'updateIndex';
+        operation: 'findNewEntries' | 'processDocument' | 'updateIndex' | 'iterateChangesSince' | 'iterateChangeMetadataSince' | 'planDocumentMaterialization' | 'planDocumentMaterializationBatch' | 'bloomRebuild';
         time: number;
         details?: Record<string, any>;
     }) => void;
+    /**
+     * Called for bounded history/time-travel workflows.
+     */
+    onHistoryOperation?: (metrics: {
+        operation: 'getDocumentAtTimestamp' | 'getDocumentHistoryPage';
+        docId: string;
+        time: number;
+        scannedEntries: number;
+        returnedEntries?: number;
+        bounded?: boolean;
+    }) => void;
+}
+/**
+ * Cursor for paged history metadata access.
+ */
+export interface DocumentHistoryPageCursor {
+    offset: number;
+}
+/**
+ * One history entry in a bounded history page.
+ */
+export interface DocumentHistoryPageEntry {
+    entryId: string;
+    entryType: StoreEntryType;
+    changeCreatedAt: number;
+    changeCreatedByPublicKey: string;
+    dependencyIds: string[];
+    isDeleted: boolean;
+}
+/**
+ * Options for bounded history metadata access.
+ */
+export interface DocumentHistoryPageOptions {
+    cursor?: DocumentHistoryPageCursor | null;
+    limit?: number;
+}
+/**
+ * Page result for bounded history metadata access.
+ */
+export interface DocumentHistoryPageResult {
+    entries: DocumentHistoryPageEntry[];
+    nextCursor: DocumentHistoryPageCursor | null;
+    hasMore: boolean;
+}
+/**
+ * Progress information emitted during pull/push sync operations.
+ */
+export interface SyncProgress {
+    phase: 'preparing' | 'planning' | 'transferring' | 'processing' | 'complete';
+    message: string;
+    transferredEntries: number;
+    scannedEntries: number;
+    totalSourceEntries?: number;
+    currentPage?: number;
+}
+/**
+ * Sync mode controls how much data is transferred between stores.
+ *
+ * - `"full"` (default) transfers every entry the target is missing.
+ * - `"dense"` uses the batch materialization planner to transfer only the
+ *   entries needed to reconstruct the latest state of each document (best
+ *   snapshot + uncovered changes + lifecycle bookkeeping).  Historical
+ *   entries superseded by a snapshot are skipped, and attachment chunks are
+ *   deferred.
+ */
+export type SyncMode = "full" | "dense";
+/**
+ * Options for pull/push sync operations.
+ */
+export interface SyncOptions {
+    onProgress?: (progress: SyncProgress) => void;
+    pageSize?: number;
+    signal?: AbortSignal;
+    /**
+     * Optional network auth override for this sync call.
+     *
+     * Useful for bootstrap scenarios where a specific user identity (for example
+     * an admin identity) must be used for the challenge/response handshake.
+     */
+    networkAuthOverride?: {
+        user: PrivateUserId;
+        password: string;
+    };
+    /**
+     * Transfer strategy.  Defaults to `"full"`.
+     *
+     * Use `"dense"` for bandwidth-constrained scenarios (initial mobile setup,
+     * metered connections) where only the current document state is needed.
+     */
+    mode?: SyncMode;
+}
+/**
+ * Result returned by pull/push sync operations.
+ */
+export interface SyncResult {
+    transferredEntries: number;
+    cancelled: boolean;
 }
 export interface MindooDB {
     /**
@@ -952,6 +1383,14 @@ export interface MindooDB {
      * @return An async generator that yields DocumentHistoryResult objects containing the document state and change metadata, in chronological order from oldest to newest
      */
     iterateDocumentHistory(docId: string): AsyncGenerator<DocumentHistoryResult, void, unknown>;
+    /**
+     * Return bounded history metadata for a document without materializing every
+     * historical document state.
+     *
+     * This is intended for scalable history UIs where the caller wants a paged
+     * timeline first, and only materializes specific snapshots on demand.
+     */
+    getDocumentHistoryPage(docId: string, options?: DocumentHistoryPageOptions): Promise<DocumentHistoryPageResult>;
     /**
      * Get all document IDs in this database.
      *
@@ -964,7 +1403,7 @@ export interface MindooDB {
      * This method efficiently queries the content-addressed store to find
      * documents that existed at the given point in time. A document is considered
      * to exist at a timestamp if:
-     * - It has a doc_create entry with createdAt < timestamp
+     * - It has a doc_create entry with createdAt <= timestamp
      * - Either it has no doc_delete entry, or its doc_delete entry has createdAt > timestamp
      *
      * @param timestamp The timestamp to query (milliseconds since Unix epoch)
@@ -1041,6 +1480,17 @@ export interface MindooDB {
      * @return An async generator that yields ProcessChangesResult objects containing the document and its cursor. Each document is yielded immediately after loading, enabling early termination.
      */
     iterateChangesSince(cursor: ProcessChangesCursor | null): AsyncGenerator<ProcessChangesResult, void, unknown>;
+    /**
+     * Iterate over latest-state change metadata since a given cursor without
+     * loading, verifying, or decrypting the full document body.
+     *
+     * This is intended for external indexes, sync checkpoints, and overview UIs
+     * that only need document IDs, deletion flags, and cursors.
+     *
+     * @param cursor The cursor to start processing changes from. Use `null` to start from the beginning.
+     * @return An async generator that yields metadata-only change summaries.
+     */
+    iterateChangeMetadataSince(cursor: ProcessChangesCursor | null): AsyncGenerator<ProcessChangeSummaryResult, void, unknown>;
     /**
      * Sync changes from the append-only store by finding new changes and processing them.
      * This method can be called multiple times to incrementally sync new changes.
@@ -1055,18 +1505,20 @@ export interface MindooDB {
      */
     syncStoreChanges(): Promise<void>;
     /**
-     * Pull changes from a remote content-addressed store.
+     * Pull changes from a remote content-addressed store or another MindooDB instance.
      *
-     * @param remoteStore The remote store to pull changes from
-     * @return A promise that resolves when the pull is complete
+     * @param remote The remote store or MindooDB instance to pull changes from
+     * @param options Optional sync options for progress tracking, paging, and cancellation
+     * @return A promise that resolves with the sync result
      */
-    pullChangesFrom(remoteStore: ContentAddressedStore): Promise<void>;
+    pullChangesFrom(remote: ContentAddressedStore | MindooDB, options?: SyncOptions): Promise<SyncResult>;
     /**
-     * Push changes to a remote content-addressed store.
+     * Push changes to a remote content-addressed store or another MindooDB instance.
      *
-     * @param remoteStore The remote store to push changes to
-     * @return A promise that resolves when the push is complete
+     * @param remote The remote store or MindooDB instance to push changes to
+     * @param options Optional sync options for progress tracking, paging, and cancellation
+     * @return A promise that resolves with the sync result
      */
-    pushChangesTo(remoteStore: ContentAddressedStore): Promise<void>;
+    pushChangesTo(remote: ContentAddressedStore | MindooDB, options?: SyncOptions): Promise<SyncResult>;
 }
 //# sourceMappingURL=types.d.ts.map