mindoodb 0.0.23 → 0.0.32

package/dist/core/BaseMindooDB.d.ts

@@ -1,9 +1,20 @@
-import { MindooDB, CreateOptions, DeleteOptions, UndeleteOptions, ChangeOptions, DocumentDagAnalysisTimestamp, DocumentDagAnalysisResult, DocumentDagBranchMaterializationResult, DocumentDagEntryDetails, DocumentConflictAnalysisEvent, DocumentConflictAnalysisOptions, DocumentConflictBaseValue, DocumentConflictBaseValueQuery, DocumentConflictReport, DocumentConflictReportOptions, ConflictScanCheckpoint, MindooDoc, MindooTenant, ProcessChangesCursor, ProcessChangesResult, DocumentHistoryResult, AttachmentConfig, DocumentCacheConfig, SnapshotConfig, SigningKeyPair, PerformanceCallback, ProcessChangeSummaryResult, IncompleteAttachmentUploadReclaimResult, SyncOptions, SyncResult, DocumentHistoryPageOptions, DocumentHistoryPageResult, MindooJsonPatch, MindooJsonPatchResult, MindooRichTextPatch, MindooRichTextPatchResult, MindooRichTextSnapshot, MindooTextPatch, MindooTextPatchResult, StartBackgroundWarmerOptions, BackgroundWarmerProgress } from "./types";
+import { MindooDB, CreateOptions, DeleteOptions, UndeleteOptions, ChangeOptions, DocumentDagAnalysisTimestamp, DocumentDagAnalysisResult, DocumentDagBranchMaterializationResult, DocumentDagEntryDetails, DocumentConflictAnalysisEvent, DocumentConflictAnalysisOptions, DocumentConflictBaseValue, DocumentConflictBaseValueQuery, DocumentConflictReport, DocumentConflictReportOptions, ConflictScanCheckpoint, MindooDoc, MindooTenant, ProcessChangesCursor, ProcessChangesResult, DocumentHistoryResult, RevisionCursor, ChangeRevisionResult, AttachmentConfig, DocumentCacheConfig, SnapshotConfig, SigningKeyPair, PerformanceCallback, ProcessChangeSummaryResult, IncompleteAttachmentUploadReclaimResult, SyncOptions, SyncResult, DocumentHistoryPageOptions, DocumentHistoryPageResult, MindooJsonPatch, MindooJsonPatchResult, MindooRichTextPatch, MindooRichTextPatchResult, MindooRichTextStepPatch, MindooRichTextSnapshot, MindooAutomergeSnapshot, MindooAutomergeChangesPatch, MindooAutomergePatchResult, MindooTextPatch, MindooTextPatchResult, StartBackgroundWarmerOptions, BackgroundWarmerProgress, DbChangeListener } from "./types";
 import { BaseMindooTenant } from "./BaseMindooTenant";
 import type { ContentAddressedStore } from "./appendonlystores/types";
+import { QuarantineRecord } from "./accesscontrol/materializationGuard";
+import type { AccessDecision } from "./accesscontrol/types";
 import { Logger } from "./logging";
 import type { LocalCacheStore } from "./cache/LocalCacheStore";
 import type { CacheManager } from "./cache/CacheManager";
+import { DocumentSummaryStore } from "./indexing/summary/DocumentSummaryStore";
+import type { SummaryConfig } from "./indexing/summary/types";
+import { DocumentFullTextIndex } from "./indexing/fulltext/DocumentFullTextIndex";
+import type { AttachmentTextExtractor, FulltextConfig, FulltextSearchOptions, FulltextSearchResult } from "./indexing/fulltext/types";
+import { ExtractionConfig } from "./extraction/types";
+import type { MindooQuery, MindooQueryOptions, MindooQueryResult } from "./query/types";
+import type { EphemeralSummaryView, MindooQueryViewDefinition } from "./query/queryView";
+import type { MindooQuerySubscription } from "./query/queryLive";
+import type { VirtualViewUpdateOptions } from "./indexing/virtualviews/IVirtualViewDataProvider";
 /**
  * Hard-coded initial Automerge change bytes that seed every document created
  * with a caller-provided id (`createDocument({ id })`).
@@ -57,11 +68,40 @@ export declare class BaseMindooDB implements MindooDB {
     private tenant;
     private store;
     private attachmentStore;
+    /**
+     * Per-tenant quarantine/audit log of entries rejected during materialization
+     * (docs/accesscontrol.md §10). In-memory; surfaced via {@link getQuarantineLog}
+     * for Haven's audit view.
+     */
+    private quarantineLog;
+    /**
+     * Short-TTL cache of "is access control active for this tenant?" so the
+     * materialization fast-path does not re-query the directory on every load.
+     */
+    private aclActiveCache;
+    /**
+     * Per-document cache of the original creator's signing public key (the
+     * `doc_create` entry's `createdByPublicKey`). Used by the client write
+     * prechecks to resolve `$author` (`isAuthor`) without re-scanning metadata on
+     * every change/delete. Populated on create and lazily on first lookup.
+     */
+    private creatorKeyCache;
     private chunkSizeBytes;
     private _isAdminOnlyDb;
     private readonly timeTravelDate;
     private index;
     private indexLookup;
+    /**
+     * Lazily-deferred repair marker for {@link indexLookup}: when set, positions
+     * stored in the map for array indices >= this value may be stale (entries
+     * shifted by an {@link updateIndex} splice). Key presence is always exact.
+     * Reads go through {@link getDocIndexPosition}, which validates a hit
+     * against {@link index} and triggers {@link flushIndexLookupPatch} only when
+     * the position actually moved. This turns the per-update O(index size)
+     * lookup rewrite into a single deferred pass — bulk syncs that append at the
+     * index tail never pay it at all.
+     */
+    private indexLookupStaleFrom;
     private nextChangeSeq;
     private docCache;
     private wrappedInternalDocs;
@@ -78,16 +118,83 @@ export declare class BaseMindooDB implements MindooDB {
     private readonly restoreToL2;
     private readonly snapshotMinChanges;
     private readonly snapshotCooldownMs;
+    /**
+     * Per-document count of local writes since the last snapshot eligibility
+     * check that scanned the store. Lets {@link maybeWriteSnapshotForDocument}
+     * skip the per-doc metadata scan entirely while a document is still far
+     * below {@link snapshotMinChanges}. Absent key = unknown (scan once).
+     */
+    private writesSinceSnapshotCheck;
     private processedEntryIds;
     private processedEntryCursor;
+    /**
+     * In-memory LRU of per-document merged state used by the revision-grain
+     * changefeed ({@link iterateRevisionsInternal}). Each entry holds a document's
+     * fully-merged Automerge doc together with the exact set of replay entry ids
+     * that merge covers, so an incremental feed advance can seed the next fold
+     * from the cached state (applying only the newly-arrived suffix) instead of
+     * re-decrypting and re-folding the document's whole history. Bounded by
+     * {@link revisionFeedCacheLimit}; least-recently-used docs are evicted and
+     * reconstructed from the best snapshot on the next touch.
+     */
+    private revisionFeedDocCache;
+    private readonly revisionFeedCacheLimit;
+    /**
+     * Window size for batching encrypted-payload loads while folding a document's
+     * revision suffix ({@link foldDocRevisions}): one {@link ContentAddressedStore.getEntries}
+     * round trip per window instead of one per revision, while bounding peak
+     * memory and response size on a snapshot-less cold-start re-fold.
+     */
+    private readonly revisionFoldLoadWindow;
     private automergeHashToEntryId;
     private logger;
     private performanceCallback?;
     private publicKeyCache;
     private cacheManager;
     private cachePrefix;
+    /**
+     * Lazily created document summary buffer backing ad-hoc queries and
+     * summary-based views. `null` until {@link getSummaryStore} is first
+     * called, so databases that never query pay no cost.
+     */
+    private summaryStore;
+    /**
+     * Lazily created full-text index (opt-in via `fulltextSetup` or an
+     * explicit config). `null` until {@link getFullTextIndex} is first
+     * called or the setup document enables indexing.
+     */
+    private fulltextIndex;
+    /**
+     * Attachment text extractors registered by the host environment (see
+     * {@link registerAttachmentTextExtractor}). Consulted lazily by the
+     * full-text index while documents with attachments are indexed.
+     */
+    private attachmentTextExtractors;
+    private changeListeners;
+    private pendingChangeNotifications;
+    private changeNotifyTimer;
+    /** While > 0, timer-based emission is suppressed (e.g. during a sync batch). */
+    private changeNotificationHolds;
+    private summaryAutoUpdateEnabled;
+    private summaryAutoUpdateRunning;
+    private summaryAutoUpdatePending;
+    /** Whether the setup document was already probed for auto-activation. */
+    private summarySetupProbed;
+    private fulltextAutoUpdateEnabled;
+    private fulltextAutoUpdateRunning;
+    private fulltextAutoUpdatePending;
+    /** Whether the setup document was already probed for FTS auto-activation. */
+    private fulltextSetupProbed;
     private dirtyDocIds;
     private cacheMetaDirty;
+    /**
+     * Per-document fingerprint (`changeSeq:automergeHeads`) of the state last
+     * written to the L2 cache by {@link flushDirtyDocToCache}. Lets the periodic
+     * flush skip the expensive `Automerge.save` + L2 write for documents that
+     * were marked dirty but whose persisted state is already current (e.g. docs
+     * that were merely loaded and cached, not changed).
+     */
+    private lastFlushedDocState;
     /**
      * Tenant KeyBag fingerprint observed at the time the in-memory index
      * was last reconciled with the underlying store.
@@ -126,6 +233,13 @@ export declare class BaseMindooDB implements MindooDB {
      */
     private warmerProgress;
     constructor(tenant: BaseMindooTenant, store: ContentAddressedStore, attachmentStore: ContentAddressedStore, attachmentConfig?: AttachmentConfig, documentCacheConfig?: DocumentCacheConfig, snapshotConfig?: SnapshotConfig, adminOnlyDb?: boolean, logger?: Logger, performanceCallback?: PerformanceCallback, timeTravelDate?: number | null);
+    /**
+     * Whether debug logging is enabled. Used to guard hot-path debug statements
+     * whose message interpolation is itself expensive (e.g.
+     * `JSON.stringify(Automerge.getHeads(...))` — a WASM call plus stringify per
+     * document), so bulk operations don't pay for logging that is discarded.
+     */
+    private isDebugEnabled;
     /**
      * Get the admin public key from the tenant.
      * Only used when adminOnlyDb is true.
@@ -143,6 +257,205 @@ export declare class BaseMindooDB implements MindooDB {
      * Attach a CacheManager so this DB participates in periodic cache flushing.
      */
     setCacheManager(cacheManager: CacheManager): void;
+    /**
+     * Get (lazily creating) the document summary buffer for this database.
+     *
+     * The summary is a changefeed-maintained map of queryable field values
+     * per document — the substrate for `query()`/`queryView()` (see
+     * docs/adhoc-queries.md). Passing a `config` on a later call replaces the
+     * configuration; if it differs from the active one, a resumable backfill
+     * re-extracts all documents on the next `update()` (documents are never
+     * rewritten).
+     */
+    getSummaryStore(config?: SummaryConfig): DocumentSummaryStore;
+    /**
+     * Read the summary configuration stored in the synced setup document
+     * (`dbsetup`, field `summarySetup`) — the "design document" that lets
+     * users/apps (e.g. the Haven UI) configure the summary fields in one
+     * place for all replicas. Returns `null` when no setup document or no
+     * configuration exists.
+     */
+    getSummarySetup(): Promise<SummaryConfig | null>;
+    /**
+     * Write the summary configuration into the synced setup document
+     * (creating `dbsetup` idempotently when missing; custom-ID documents
+     * share seeded Automerge ancestry, so concurrent creates on different
+     * replicas merge). Passing `null` removes the configuration (replicas
+     * fall back to the default auto-include config).
+     *
+     * Summary stores without an explicit code-provided configuration pick
+     * the change up through the changefeed and re-extract via a resumable
+     * backfill — locally and, after sync, on every other replica.
+     */
+    setSummarySetup(config: SummaryConfig | null): Promise<void>;
+    /**
+     * Enable/disable summary auto-follow (default: enabled). When enabled,
+     * the summary buffer is brought up to date in the background after every
+     * coalesced change event — one catch-up run per sync batch, one per
+     * event-loop turn for local writes — so queries don't stall on a full
+     * catch-up after receiving many documents. Compared to the network I/O
+     * of a sync the incremental extraction is cheap; disable it for
+     * bulk-import scenarios where even that is unwanted (the next query
+     * catches up lazily as before).
+     */
+    setSummaryAutoUpdateEnabled(enabled: boolean): void;
+    /**
+     * Change-event hook for summary auto-follow. While no summary store
+     * exists, the setup document decides whether to activate one: it is
+     * probed on the first event (covers reopening a database whose `dbsetup`
+     * synced earlier) and re-checked whenever a `dbsetup` change arrives
+     * (covers the configuration being created/updated locally or via sync).
+     */
+    private handleChangesForSummaryAutoUpdate;
+    /** Create the summary store when the setup document configures one. */
+    private activateSummaryFromSetupDoc;
+    /**
+     * Run a background summary catch-up, coalescing further requests into
+     * one follow-up run (mirrors the live-view scheduling in VirtualView).
+     * Errors are logged and never propagate into write/sync paths.
+     */
+    private scheduleSummaryAutoUpdate;
+    /**
+     * Get (lazily creating) the full-text index for this database.
+     *
+     * The index is a changefeed-maintained, encrypted-at-rest search index
+     * over extracted document text — configured via the synced setup
+     * document (`dbsetup`, field `fulltextSetup`) or an explicit `config`.
+     * Passing a `config` on a later call replaces the configuration; if it
+     * differs from the active one, the engine is recreated and a resumable
+     * backfill re-indexes all documents on the next `update()`.
+     *
+     * Note that indexing is OPT-IN: without `enabled: true` (in the setup
+     * document or the explicit config) the index stays empty and
+     * {@link searchText} throws.
+     */
+    getFullTextIndex(config?: FulltextConfig): DocumentFullTextIndex;
+    /**
+     * Read the full-text configuration stored in the synced setup document
+     * (`dbsetup`, field `fulltextSetup`). Returns `null` when no setup
+     * document or no configuration exists.
+     */
+    getFulltextSetup(): Promise<FulltextConfig | null>;
+    /**
+     * Write the full-text configuration into the synced setup document
+     * (creating `dbsetup` idempotently when missing). Passing `null`
+     * removes the configuration (indexing falls back to disabled).
+     *
+     * Idempotent: when the sanitized config equals what is already stored,
+     * no change is written — apps can safely call this on every start
+     * without producing changefeed/sync churn.
+     *
+     * Full-text indexes without an explicit code-provided configuration
+     * pick the change up through the changefeed and re-index via a
+     * resumable backfill — locally and, after sync, on every other replica.
+     */
+    setFulltextSetup(config: FulltextConfig | null): Promise<void>;
+    /**
+     * Read the attachment extraction configuration stored in the synced
+     * setup document (`dbsetup`, field `extractionSetup`). Configures
+     * host-side extraction services (e.g. Haven's OCR service) that persist
+     * results at the attachment entry via
+     * {@link MindooDoc.setAttachmentExtractedText}. Returns `null` when no
+     * setup document or no configuration exists.
+     */
+    getExtractionSetup(): Promise<ExtractionConfig | null>;
+    /**
+     * Write the attachment extraction configuration into the synced setup
+     * document (creating `dbsetup` idempotently when missing). Passing
+     * `null` removes the configuration (extraction services stay idle).
+     *
+     * Idempotent: when the sanitized config equals what is already stored,
+     * no change is written — services can safely call this on every start
+     * without producing changefeed/sync churn.
+     */
+    setExtractionSetup(config: ExtractionConfig | null): Promise<void>;
+    /**
+     * Register an attachment text extractor for full-text indexing (see
+     * {@link AttachmentTextExtractor}). Host environments call this when
+     * opening the database (e.g. Haven registers text/PDF/Office extractors
+     * from its preview parsers). Extraction only happens for databases
+     * whose `fulltextSetup` has `attachments: true`.
+     *
+     * @returns An unregister function.
+     */
+    registerAttachmentTextExtractor(extractor: AttachmentTextExtractor): () => void;
+    /**
+     * Full-text search over the document full-text index (see
+     * docs/fulltext-search.md). Brings the index up to date first, then
+     * returns matching documents best-score-first. Results are
+     * device-specific under E2EE: documents whose decryption keys are
+     * missing from the local KeyBag are not indexed and cannot match.
+     *
+     * @throws Error when full-text indexing is not enabled for this
+     *   database (see {@link setFulltextSetup} / {@link getFullTextIndex}).
+     */
+    searchText(query: string, options?: FulltextSearchOptions): Promise<FulltextSearchResult>;
+    /**
+     * Enable/disable full-text auto-follow (default: enabled). Mirrors
+     * {@link setSummaryAutoUpdateEnabled}: when enabled, an ACTIVE full-text
+     * index catches up in the background after every coalesced change
+     * event, so the first search after a large sync doesn't stall.
+     * Databases without an enabled `fulltextSetup` never pay any cost.
+     */
+    setFulltextAutoUpdateEnabled(enabled: boolean): void;
+    /**
+     * Change-event hook for full-text auto-follow. While no index exists,
+     * the setup document decides whether to activate one — probed on the
+     * first event and re-checked whenever a `dbsetup` change arrives
+     * (mirrors {@link handleChangesForSummaryAutoUpdate}).
+     */
+    private handleChangesForFulltextAutoUpdate;
+    /** Create the full-text index when the setup document enables one. */
+    private activateFulltextFromSetupDoc;
+    /**
+     * Run a background full-text catch-up, coalescing further requests into
+     * one follow-up run (mirrors {@link scheduleSummaryAutoUpdate}).
+     */
+    private scheduleFulltextAutoUpdate;
+    /**
+     * Register a listener notified after documents change (local writes,
+     * sync ingest, access flips, witness updates). Events are coalesced:
+     * one event per sync batch, one per event-loop turn for local writes.
+     * The event carries only lightweight metadata plus the latest change
+     * cursor — no replay guarantee; consumers needing completeness read
+     * {@link iterateChangesSince} from their own cursor.
+     *
+     * @returns An unsubscribe function.
+     */
+    addChangeListener(listener: DbChangeListener): () => void;
+    /** Record a document transition for the coalesced change event. */
+    private noteChangeForListeners;
+    private scheduleChangeNotification;
+    /**
+     * Suppress timer-based change emission for the duration of a batch
+     * operation (sync ingest); the release emits one coalesced event.
+     */
+    private beginChangeNotificationHold;
+    private endChangeNotificationHold;
+    private emitPendingChangeEvent;
+    /**
+     * Run an ad-hoc query against the document summary buffer (see
+     * docs/adhoc-queries.md). Filters and expression sort keys use the
+     * MindooDB expression language; documents are never materialized unless
+     * `options.allowFullScan` is set.
+     */
+    query(query: MindooQuery, options?: MindooQueryOptions): Promise<MindooQueryResult>;
+    /**
+     * Build an ephemeral, summary-backed VirtualView (categories, sorting,
+     * totals as usual — but fed from the summary buffer, so no documents are
+     * materialized and re-sorting via `resort()` is a pure in-memory
+     * operation). The view is not cached; call `dispose()` when done.
+     */
+    queryView(definition: MindooQueryViewDefinition, options?: VirtualViewUpdateOptions): Promise<EphemeralSummaryView>;
+    /**
+     * Live query: delivers the initial result asynchronously, then keeps
+     * re-evaluating after coalesced change events. `onResult` only fires
+     * when the result fingerprint (docIds + lastModified of the matches)
+     * actually changed.
+     */
+    queryLive(query: MindooQuery, onResult: (result: MindooQueryResult) => void, options?: MindooQueryOptions & {
+        onError?: (error: unknown) => void;
+    }): MindooQuerySubscription;
     getCachePrefix(): string;
     hasDirtyState(): boolean;
     clearDirty(): void;
@@ -219,10 +532,42 @@ export declare class BaseMindooDB implements MindooDB {
      */
     private getOrImportPublicKey;
     /**
-     * Verify a signature using a pre-imported CryptoKey.
-     * This bypasses the key import step for better performance when keys are cached.
+     * Compute the author's metadata-binding signature for a new entry (audit
+     * finding #5). The signature covers the canonical, versioned, length-prefixed
+     * metadata layout (see crypto/EntrySignature.ts) rather than only the
+     * ciphertext, so the cleartext metadata cannot be tampered with after signing.
+     * Uses the supplied custom signing key when present, otherwise the current
+     * user's signing key.
+     */
+    private computeEntryMetadataSignature;
+    /**
+     * Collect the full set of attachment references a document holds right now,
+     * for the signed {@link StoreEntryMetadata.attachmentRefs} snapshot.
+     *
+     * Refs are sorted by `attachmentId` to give a canonical, deterministic order
+     * so the bytes signed by the writer match the bytes a verifier reconstructs
+     * (see crypto/EntrySignature.ts). Reads the merged `_attachments` array, so
+     * additions, removals, and appends are all reflected.
+     */
+    private collectAttachmentRefs;
+    /**
+     * Verify a store entry's author signature using a pre-imported CryptoKey,
+     * version-aware (audit finding #5): prefers the metadata-binding
+     * `metadataSignature` when present, otherwise the legacy ciphertext signature,
+     * and re-verifies `SHA-256(encryptedData) === contentHash`. Returns false on
+     * any mismatch. The caller is responsible for the directory trust check.
      */
-    private verifySignatureWithKey;
+    private verifyEntrySignatureWithKey;
+    /**
+     * Whether the tenant storage-format floor (`requireMetadataSignatureSince`)
+     * requires `entry` to carry the v2 metadata-binding signature, based on its
+     * trusted time. The `directory` store is exempt (it must always load so the
+     * policy that defines the floor can be read); entries that already carry a
+     * `metadataSignature` short-circuit. Fail-open on resolution errors is safe —
+     * the legacy signature is still cryptographically verified; the floor only
+     * refuses the weaker fallback for new entries.
+     */
+    private requiresMetadataSignature;
     /**
      * Compare two index entries for sorting.
      * Returns negative if a < b, positive if a > b, 0 if equal.
@@ -251,11 +596,22 @@ export declare class BaseMindooDB implements MindooDB {
      *   tombstones produced by the key visibility layer
      */
     private updateIndex;
+    /**
+     * Resolve a document's position in the sorted {@link index} through the
+     * lookup map, repairing lazily-deferred staleness (see
+     * {@link indexLookupStaleFrom}) only when the cached position no longer
+     * matches. All `indexLookup.get` reads must go through this accessor.
+     */
+    private getDocIndexPosition;
+    /** Rewrite the stale tail of {@link indexLookup} recorded by {@link updateIndex}. */
+    private flushIndexLookupPatch;
     /**
      * Register an automerge hash -> entry ID mapping for a document.
      * This is used to resolve Automerge dependency hashes to entry IDs.
      */
     private registerAutomergeHashMapping;
+    private registerAutomergeHashMappingIfAbsent;
+    private registerSnapshotHeadHashMappings;
     /**
      * Get the entry ID for an automerge hash within a document.
      * Returns null if not found.
@@ -294,6 +650,16 @@ export declare class BaseMindooDB implements MindooDB {
      * then processes only the delta. Falls back to full rebuild on cache miss.
      */
     initialize(): Promise<void>;
+    /**
+     * Open-time probe for full-text auto-activation. Without it, a
+     * database whose synced `fulltextSetup` is already enabled would not
+     * build its index until the first change event arrives or the first
+     * search runs. Fired once (fire-and-forget) at the end of
+     * {@link initialize}; uses the same system-database exclusions and
+     * activation path as the change-event probe (see
+     * {@link handleChangesForFulltextAutoUpdate}).
+     */
+    private probeFulltextSetupAtOpen;
     /**
      * Compute the current tenant KeyBag fingerprint, or `null` when the
      * tenant does not expose one (older `MindooTenant` implementations).
@@ -384,6 +750,7 @@ export declare class BaseMindooDB implements MindooDB {
      * the workload is about to benefit from it.
      */
     syncStoreChanges(): Promise<void>;
+    private syncStoreChangesInternal;
     private supportsCursorScan;
     private scanAllMetadata;
     private getNewEntryMetadataForSync;
@@ -463,6 +830,33 @@ export declare class BaseMindooDB implements MindooDB {
      * @deprecated Use `createDocument({ signingKeyPair, signingKeyPassword, decryptionKeyId })` instead.
      */
     createDocumentWithSigningKey(signingKeyPair: SigningKeyPair, signingKeyPassword: string, decryptionKeyId?: string): Promise<MindooDoc>;
+    /**
+     * Bulk-create documents in a single append-only store write.
+     *
+     * Semantically equivalent to calling {@link createDocument} once per input,
+     * with these bulk-oriented differences:
+     * - All produced store entries are written through ONE `putEntries()` call,
+     *   so IndexedDB-backed stores commit the whole batch in a single readwrite
+     *   transaction instead of one per document.
+     * - Custom-id documents MAY combine `id` with `initialValues`: the values are
+     *   applied as a separate `doc_change` entry on top of the deterministic
+     *   seed change, and both entries land in the same batch. (The single-create
+     *   path rejects this combination and requires a follow-up `changeDoc()`.)
+     * - Freshly created documents are cached but intentionally NOT added to the
+     *   dirty-doc tracking: their entries are already durable in the store, so
+     *   an L1 eviction can always re-materialize them. This avoids the per-doc
+     *   flush-before-evict L2 write storm during large imports.
+     * - Snapshot scheduling is skipped (fresh documents cannot exceed the
+     *   snapshot threshold).
+     *
+     * Existing custom-id documents keep the idempotent single-create semantics:
+     * the existing document is returned (tombstones are undeleted first) and any
+     * `initialValues` are applied as a follow-up change.
+     *
+     * Fail-fast: invalid inputs are rejected up front, and a denied ACL
+     * precheck rejects the whole call before any fresh document is written.
+     */
+    createDocuments(inputs: CreateOptions[]): Promise<MindooDoc[]>;
     /**
      * Internal method to create a new document.
      *
@@ -477,9 +871,105 @@ export declare class BaseMindooDB implements MindooDB {
      * custom ID converge when synced (see `getCustomIdInitialChangeBytes`).
      */
     private createDocumentInternal;
+    /**
+     * Build the store entries and in-memory state for one fresh document of a
+     * {@link createDocuments} batch WITHOUT writing anything. The caller is
+     * responsible for persisting the returned entries (batched `putEntries`)
+     * and for cache/index registration afterwards.
+     *
+     * Mirrors {@link createDocumentInternal} for the fresh-document case, with
+     * one bulk-only extension: a custom-id document MAY carry `initialValues`,
+     * which are emitted as an extra `doc_change` entry on top of the
+     * deterministic seed change so both land in the same store batch.
+     */
+    private prepareFreshDocumentCreate;
     getDocument(docId: string): Promise<MindooDoc>;
     getDocumentAtTimestamp(docId: string, timestamp: number): Promise<MindooDoc | null>;
     iterateDocumentHistory(docId: string): AsyncGenerator<DocumentHistoryResult, void, unknown>;
+    iterateChangeRevisionsSince(cursor: RevisionCursor | null): AsyncGenerator<ChangeRevisionResult, void, unknown>;
+    iterateDocRevisionsSince(docId: string, cursor: RevisionCursor | null): AsyncGenerator<ChangeRevisionResult, void, unknown>;
+    /**
+     * Shared implementation of the revision-grain changefeed
+     * ({@link iterateChangeRevisionsSince} / {@link iterateDocRevisionsSince}).
+     *
+     * Two distinct orderings drive the feed (docs/accesscontrol.md §8):
+     *
+     * - **Discovery (receiptOrder).** New entries are discovered via the store's
+     *   gap-free `scanEntriesSince(cursor)` scan in `(receiptOrder, id)` order, so
+     *   an incremental advance reads only entries appended since the cursor and
+     *   never re-scans cold documents. The resumable {@link RevisionCursor} is this
+     *   scan position, parked just before the earliest un-witnessed entry so the
+     *   provisional head overlay is re-evaluated on every resume.
+     * - **Materialization (trusted time).** Each affected document's changes are
+     *   folded in trusted-time order, so every yielded revision carries the
+     *   document's *trusted-time-bounded merge* — the merge of all of the doc's
+     *   changes with `trustedTime <= this revision's trustedTime`. This is correct
+     *   at the head and at every intermediate node, and concurrent same-base
+     *   changes merge from the larger-trusted-time instant onward.
+     *
+     * Trusted-time rule: witnessed entries use their witness `receivedAt`;
+     * un-witnessed local entries use the current wall clock, so they always sit at
+     * the provisional head and never appear in past-time reads until witnessed.
+     *
+     * An in-memory per-doc LRU ({@link revisionFeedDocCache}) lets the common
+     * in-order advance seed from cached state and decrypt only the new suffix; a
+     * cache miss reconstructs the seed from the best snapshot whose coverage is
+     * within the fold prefix via {@link computeDocumentMaterializationPlan}.
+     */
+    private iterateRevisionsInternal;
+    /**
+     * Discovery phase of {@link iterateRevisionsInternal}: walk the store in
+     * `(receiptOrder, id)` order from `cursor`, collecting the newly-appended
+     * replay entries and computing the resume cursor.
+     *
+     * The resume cursor is the witnessed stable-prefix watermark: it advances over
+     * leading witnessed entries but stops just before the first un-witnessed entry,
+     * so un-witnessed entries (whose trusted time is provisional `now`) are
+     * re-discovered and re-evaluated as a head overlay on the next resume.
+     */
+    private discoverRevisionEntries;
+    /** Compare two entries by `(receiptOrder, id)` ascending. */
+    private compareReceiptOrder;
+    /** True when `em` is strictly after `cursor` in `(receiptOrder, id)` order. */
+    private isAfterReceiptCursor;
+    /**
+     * Materialization phase for a single affected document: fold its changes in
+     * trusted-time order and yield one revision per change from the earliest
+     * newly-discovered (or superseded) position onward, each carrying the
+     * trusted-time-bounded merged document state.
+     */
+    private foldDocRevisions;
+    /**
+     * Reconstruct the merged state of a document covering exactly the replay
+     * entries in `prefix` (the unchanged head of a trusted-time fold).
+     *
+     * Fast path: if the LRU holds a merged doc whose coverage is a subset of the
+     * prefix, clone it and apply only the missing entries. Otherwise reconstruct
+     * from the best snapshot whose coverage is fully within the prefix (so the
+     * snapshot can never pull in changes beyond the fold point) plus the uncovered
+     * prefix tail, via {@link computeDocumentMaterializationPlan}.
+     */
+    private seedRevisionFold;
+    /** True when every id in `sub` is contained in `sup`. */
+    private isIdSubset;
+    /**
+     * True when all of a snapshot's coverage roots are within `idSet`, i.e. the
+     * snapshot represents a state reachable from entries inside the set (safe to
+     * use as a seed without pulling in later changes).
+     */
+    private snapshotRootsWithin;
+    /** Load, verify, and decrypt a snapshot into an Automerge doc, or `null`. */
+    private loadSnapshotForFold;
+    /**
+     * Load, verify, decrypt, and apply a set of replay change entries onto `doc`.
+     * `Automerge.applyChanges` buffers changes whose causal dependencies are not
+     * yet present, so the entries need not be supplied in dependency order.
+     */
+    private applyChangeEntries;
+    /** Touch the revision-feed LRU, moving `docId` to most-recently-used. */
+    private getRevisionFeedCache;
+    /** Insert/update the revision-feed LRU, evicting the least-recently-used. */
+    private putRevisionFeedCache;
     getDocumentHistoryPage(docId: string, options?: DocumentHistoryPageOptions): Promise<DocumentHistoryPageResult>;
     analyzeDocumentDagAtTimestamp(docId: string, timestamp: DocumentDagAnalysisTimestamp): Promise<DocumentDagAnalysisResult>;
     /**
@@ -785,6 +1275,21 @@ export declare class BaseMindooDB implements MindooDB {
     getDeletedDocumentIds(): Promise<string[]>;
     getAllDocumentIdsAtTimestamp(timestamp: number): Promise<string[]>;
     deleteDocument(docId: string, options?: DeleteOptions): Promise<void>;
+    /**
+     * Bulk-delete documents in a single append-only store write.
+     *
+     * Semantically equivalent to calling {@link deleteDocument} once per id, but
+     * all `doc_delete` lifecycle entries are written through ONE `putEntries()`
+     * call (a single readwrite transaction on IndexedDB-backed stores), and the
+     * deleted documents are dropped from the L1 cache instead of being
+     * dirty-tracked (the entries are already durable, so no L2 flush is needed).
+     *
+     * Documents that are missing or already deleted are skipped (idempotent
+     * bulk semantics: a re-run of a destructive import must not fail because a
+     * previous run already removed some documents). Any other failure, including
+     * a denied ACL precheck, rejects the whole call before anything is written.
+     */
+    deleteDocuments(docIds: string[], options?: DeleteOptions): Promise<void>;
     deleteDocumentWithSigningKey(docId: string, signingKeyPair: SigningKeyPair, signingKeyPassword: string): Promise<void>;
     undeleteDocument(docId: string, options?: UndeleteOptions): Promise<void>;
     private assertLifecycleMutationAllowed;
@@ -796,6 +1301,24 @@ export declare class BaseMindooDB implements MindooDB {
      * StoreEntry type, signs/encrypts it, and updates local caches/indexes.
      */
     private writeLifecycleEntry;
+    /**
+     * Build (but do not persist) a delete/undelete lifecycle entry for an
+     * existing document, including the ACL precheck. Callers persist the
+     * returned `fullEntry` (single or batched `putEntries`) and then call
+     * {@link applyLifecycleEntryLocally} to update caches and indexes.
+     */
+    private prepareLifecycleEntry;
+    /**
+     * Apply a persisted lifecycle entry (see {@link prepareLifecycleEntry}) to
+     * the in-memory document, cache, and changefeed index. Must be called after
+     * the entry was written to the store.
+     *
+     * With `markDirty: false` (bulk path) the document is dropped from the L1
+     * cache instead of being dirty-tracked: the lifecycle entry is already
+     * durable in the append-only store, so skipping the L2 flush avoids the
+     * per-document flush-before-evict write storm during large batches.
+     */
+    private applyLifecycleEntryLocally;
     /**
      * Internal method to delete a document.
      * Handles both regular deletion (signed by current user) and
@@ -807,20 +1330,30 @@ export declare class BaseMindooDB implements MindooDB {
     changeDocWithSigningKey(doc: MindooDoc, changeFunc: (doc: MindooDoc) => void | Promise<void>, signingKeyPair: SigningKeyPair, signingKeyPassword: string): Promise<void>;
     applyTextPatch(doc: MindooDoc, patch: MindooTextPatch): Promise<MindooTextPatchResult>;
     applyRichTextPatch(doc: MindooDoc, patch: MindooRichTextPatch): Promise<MindooRichTextPatchResult>;
+    applyRichTextStepsPatch(doc: MindooDoc, patch: MindooRichTextStepPatch): Promise<MindooRichTextPatchResult>;
     getRichTextSnapshot(doc: MindooDoc, path: Array<string | number>): Promise<MindooRichTextSnapshot>;
+    exportAutomergeSnapshot(doc: MindooDoc): Promise<MindooAutomergeSnapshot>;
+    applyAutomergeChanges(doc: MindooDoc, patch: MindooAutomergeChangesPatch): Promise<MindooAutomergePatchResult>;
+    private resolveReadableInternalDoc;
     applyJsonPatch(doc: MindooDoc, patch: MindooJsonPatch): Promise<MindooJsonPatchResult>;
     private changeDocInternal;
     private validateTextPatch;
     private validateJsonPatch;
     private validateRichTextPatch;
+    private validateRichTextSpans;
+    private validateRichTextStepPatch;
     private validateJsonPath;
     private reviveRichTextSpans;
     private reviveRichTextValue;
     private dehydrateRichTextSpans;
     private dehydrateRichTextValue;
     private applyJsonPatchOperations;
+    private spliceJsonTextAtPath;
+    private unmarkJsonTextAtPath;
+    private clampIndex;
     private setJsonValueAtPath;
     private unsetJsonValueAtPath;
+    private readValueAtPath;
     private readJsonListAtPath;
     /**
      * Like {@link readJsonListAtPath} but creates the array (and any missing
@@ -839,8 +1372,31 @@ export declare class BaseMindooDB implements MindooDB {
     private ensureJsonParentAtPath;
     private readJsonParentAtPath;
     private ensureTextPath;
+    /**
+     * Run an Automerge change operation against `internalDoc.doc`, recovering
+     * from the "outdated document" error by cloning the cached doc and
+     * retrying once.
+     *
+     * Automerge marks a document as outdated whenever the JS reference has
+     * already been passed to `Automerge.change` / `Automerge.applyChanges` /
+     * `Automerge.changeAt` (the WASM handle's `state.heads` is set to a
+     * non-null value, putting the doc into "view" mode). The mindoodb cache
+     * normally avoids this by reassigning `internalDoc.doc = newDoc` after
+     * every change, but a stale reference (left over from an aborted or
+     * out-of-band Automerge operation) can still leak in. When that happens
+     * the doc is still semantically up to date - it just can't be mutated -
+     * and `Automerge.clone(...)` produces a fresh, writable copy at the same
+     * heads. The same workaround already lives in
+     * {@link applyNewEntriesToCachedDocument} (line ~6606) for the sync
+     * pipeline; this helper centralizes it for the patch / changeDoc paths.
+     */
+    private runChangeWithOutdatedDocRecovery;
+    private isOutdatedDocumentError;
+    private isRichTextUpdateSpansBoundsError;
     private ensureRichTextPath;
     private persistDocumentChange;
+    private persistAutomergeDocumentChanges;
+    private buildDocChangeStoreEntry;
     /**
      * Best-effort snapshot scheduling and writing.
      * A snapshot is written only when enough replay history has accumulated and
@@ -897,6 +1453,12 @@ export declare class BaseMindooDB implements MindooDB {
     private materializeDocumentFromPlan;
     iterateChangeMetadataSince(cursor: ProcessChangesCursor | null): AsyncGenerator<ProcessChangeSummaryResult, void, unknown>;
     getLatestChangeCursor(): ProcessChangesCursor | null;
+    /**
+     * Count the changefeed entries after the given cursor without iterating
+     * them. O(log n) binary search on the internal `(changeSeq, docId)` index —
+     * used for progress reporting around {@link iterateChangesSince}.
+     */
+    countChangesSince(cursor: ProcessChangesCursor | null): number;
     iterateChangesSince(cursor: ProcessChangesCursor | null): AsyncGenerator<ProcessChangesResult, void, unknown>;
     /**
      * Incrementally update a cached document with new entries.
@@ -994,6 +1556,116 @@ export declare class BaseMindooDB implements MindooDB {
      * plus once at the end of the pass with the terminal phase.
      */
     private runBackgroundWarmer;
+    /**
+     * The per-tenant quarantine/audit log: entries rejected during
+     * materialization by the access-control layer (docs/accesscontrol.md §10).
+     * Exposed for audit views (e.g. Haven). Entries remain in the append-only
+     * store but are excluded from materialized state and queries.
+     */
+    getQuarantineLog(): readonly QuarantineRecord[];
+    /**
+     * Whether access control is active for this tenant and should gate
+     * materialization. Admin-only databases (incl. the directory itself) are
+     * always exempt — admin is the root of trust, and exempting the directory DB
+     * also avoids re-entrancy. Cached briefly to keep the load fast-path cheap.
+     * Fails closed-to-disabled on any directory error so document loads never
+     * break due to a transient directory issue (Tier 2 only gates honest clients).
+     */
+    private isAclEnforced;
+    /**
+     * Synchronous client-side write-policy precheck (docs/accesscontrol.md §9).
+     * Evaluates the full Tier 1 + Tier 2 ruleset for the candidate write and
+     * throws {@link AccessDeniedError} when it is denied, so applications get
+     * immediate, meaningful feedback at the call site instead of an optimistic
+     * local write that is later rejected by the server witness or quarantined on
+     * materialization.
+     *
+     * Fails CLOSED on any directory/infra error while access control is enforced
+     * (audit finding #2): the precheck denies the write rather than letting it
+     * through optimistically. The server witness (Tier 1) and
+     * quarantine-on-materialization (Tier 2) remain the authoritative enforcers,
+     * and the user can retry once the directory is reachable again.
+     *
+     * `getBeforeDoc`/`getAfterDoc` are lazy so the (potentially costly) Automerge
+     * -> JS materialization is skipped entirely when the active policy has no
+     * Tier 2 (`withfields`) content rule for this operation/database.
+     */
+    private assertWriteAllowed;
+    /**
+     * Resolve the `decryptionKeyId` for a `doc_create`: the caller's explicit key
+     * when given, else the policy-configured default for this database (see
+     * `getEffectiveDefaultCreateKeyId` on the directory), else the legacy
+     * `"default"`. The policy default is a create-time convenience only; read/write
+     * access is governed by key possession (distribution + rotation, §13), not the
+     * server. Directory ACL writes always pass an explicit key, so this never
+     * re-enters the directory for them.
+     */
+    private resolveCreateKeyId;
+    /**
+     * Evaluate the full client-side (Tier 1 + Tier 2) write ruleset for a
+     * candidate write, returning the {@link AccessDecision}. Returns `null` only
+     * when access control is not enforced for this database (callers treat `null`
+     * as "allowed"). When access control IS enforced but the directory cannot be
+     * consulted, it returns a DENY decision (fail closed, audit finding #2). The
+     * `getBeforeDoc`/`getAfterDoc` materializers are only invoked when the active
+     * policy has a Tier 2 (`withfields`) content rule for this op/db.
+     */
+    private evaluateClientWriteAccess;
+    /** The "access control not enforced" allow decision returned by the
+     * non-throwing `canCreate`/`canChange`/`canDelete` prediction helpers. */
+    private static readonly ACL_NOT_ENFORCED_DECISION;
+    /**
+     * Predict whether a `createDocument` would be allowed by the active write
+     * policy, without writing anything (docs/accesscontrol.md §9). Lets a UI
+     * disable a Save action and surface `decision.reason` up front. The returned
+     * decision mirrors what {@link createDocument} would enforce.
+     */
+    canCreate(options?: CreateOptions): Promise<AccessDecision>;
+    /**
+     * Predict whether applying `candidateAfter` as the document's next state via
+     * {@link changeDoc} would be allowed by the active write policy, without
+     * writing anything. `candidateAfter` is the intended full "after" document
+     * (e.g. the edited JSON in a database-browser editor).
+     */
+    canChange(doc: MindooDoc, candidateAfter: Record<string, unknown>, signingKeyPair?: SigningKeyPair): Promise<AccessDecision>;
+    /**
+     * Predict whether deleting `doc` via {@link deleteDocument} would be allowed
+     * by the active write policy, without writing anything.
+     */
+    canDelete(doc: MindooDoc, signingKeyPair?: SigningKeyPair): Promise<AccessDecision>;
+    /**
+     * Predict whether undeleting `doc` via {@link undeleteDocument} would be
+     * allowed by the active write policy, without writing anything.
+     */
+    canUndelete(doc: MindooDoc, signingKeyPair?: SigningKeyPair): Promise<AccessDecision>;
+    /**
+     * Resolve the signing public key of the document's original creator (the
+     * `doc_create` entry's `createdByPublicKey`), used to set `$author`
+     * (`isAuthor`) for the client write prechecks on change/delete/undelete.
+     * Cached per document; returns `null` if the create entry isn't present yet
+     * (in which case `isAuthor` is treated as false, matching materialization).
+     */
+    private resolveCreatorSigningKey;
+    /** Append a record to the quarantine/audit log (and log it). */
+    private recordQuarantine;
+    /**
+     * Materialize a document through the access-control (Tier 2) path
+     * (docs/accesscontrol.md §10). Entries are evaluated deterministically in
+     * trusted-time order; an entry is quarantined if it violates a rule, fails
+     * op-type re-derivation, or causally depends on a quarantined entry
+     * (cascade). The accepted set is therefore a causally-closed prefix identical
+     * across replicas, which is what makes "quarantine on receipt" safe under
+     * eventual consistency.
+     *
+     * Snapshots are intentionally bypassed here and the document is rebuilt from
+     * individually-verified lifecycle entries (the spec's fallback), so a snapshot
+     * can never smuggle content past Tier 2.
+     *
+     * @returns the materialized {@link InternalDoc} (or `null` if nothing is
+     *   accepted / the document is absent), or `undefined` when access control is
+     *   not enforced (caller uses the optimized fast path).
+     */
+    private maybeMaterializeWithAccessControl;
     /**
      * Internal method to load a document from the content-addressed store
      */
@@ -1010,6 +1682,27 @@ export declare class BaseMindooDB implements MindooDB {
      * This is the read-only wrapper - write methods throw errors.
      */
     private wrapDocument;
+    /**
+     * Build a lightweight read-only tombstone for a now-inaccessible index entry
+     * (docs/accesscontrol.md §13): a document that was readable before but whose
+     * decryption key the current KeyBag no longer holds (e.g. a revoked key).
+     * Emitted by {@link iterateChangesSince} so incremental consumers get a
+     * removal signal. Per the design rule it reports `isDeleted() === true`,
+     * `isAccessible() === false`, `getData() === {}` (the plaintext is purged,
+     * never materialized) and `getHeads() === []` — backed by an empty Automerge
+     * document so it never touches the underlying ciphertext or the document cache.
+     */
+    private buildInaccessibleDoc;
+    /**
+     * Build a lightweight read-only tombstone for a deleted document, emitted
+     * by {@link iterateChangesSince} instead of materializing the deleted
+     * body. Reports `isDeleted() === true`, `isAccessible() === true` and
+     * `getData() === {}` — the counterpart to {@link buildInaccessibleDoc} for
+     * genuine deletions (distinguish the two via `isAccessible()`). Consumers
+     * that need the last state of a deleted document can use
+     * {@link iterateDocumentHistory} or {@link getDocumentAtTimestamp}.
+     */
+    private buildDeletedDoc;
     /**
      * Get an attachment reference by ID from a document's _attachments array.
      */