mindoodb 0.0.91 → 0.0.93

package/dist/core/BaseMindooDB.js

@@ -568,6 +568,19 @@ class BaseMindooDB {
          * Maintained only via {@link rememberL2Record} / {@link forgetL2Record}.
          */
         this.l2RecordChangeSeqs = new Map();
+        /**
+         * Whether {@link l2RecordChangeSeqs} lists every L2 record this instance
+         * may use: true for a fresh cache and for checkpoints that say so
+         * (`l2Tracked`), false for older checkpoints. When true, a document
+         * without an entry has no usable L2 record and the read skips the L2
+         * lookup instead of asking the cache store (one store round trip per
+         * document on a cold start). Records another tab wrote meanwhile are
+         * missed until the next restore; the document is then materialized from
+         * the store, as on any L2 miss.
+         */
+        this.l2RecordsTracked = true;
+        /** L2 records fetched in one batch for a prefetch window (consumed by tryLoadFromL2). */
+        this.l2Prefetched = new Map();
         /**
          * Tenant KeyBag fingerprint observed at the time the in-memory index
          * was last reconciled with the underlying store.
@@ -615,6 +628,16 @@ class BaseMindooDB {
         // ---------------------------------------------------------------------------
         /** Serializes concurrent author-trust reconciles (per database). */
         this.authorTrustReconcileChain = Promise.resolve();
+        /**
+         * Key series this replica gained or lost during the current pass. Documents of
+         * a group document are not re-checked one by one when its wraps change; the
+         * next {@link reconcileGroupKeyAccess} re-runs the key visibility reconcile.
+         */
+        this.groupKeyAccessChanged = new Set();
+        /** Per document: whether its origin decrypted with the partial series held then. */
+        this.partialSeriesProbes = new Map();
+        /** Group key series last probed without success, by key id (ms), see ingestGroupKey. */
+        this.groupKeyMisses = new Map();
         (0, databaseIdValidation_1.validateDatabaseId)(store.getId(), "dbId");
         (0, databaseIdValidation_1.validateDatabaseId)(attachmentStore.getId(), "dbId");
         if (store.getId() !== attachmentStore.getId()) {
@@ -1870,6 +1893,10 @@ class BaseMindooDB {
         if (this.l2RecordChangeSeqs.size > 0) {
             checkpoint.l2RecordChangeSeqs = Object.fromEntries(this.l2RecordChangeSeqs);
         }
+        // The map above is complete only when it was complete on restore.
+        if (this.l2RecordsTracked) {
+            checkpoint.l2Tracked = true;
+        }
         // Persist the KeyBag fingerprint observed at the last reconciliation
         // so the next restore can decide whether to skip the visibility
         // metadata scan. `null` is acceptable - older checkpoints simply
@@ -1932,6 +1959,7 @@ class BaseMindooDB {
                 ? checkpoint.locallyIndexedEntryIds.filter((id) => typeof id === "string")
                 : []);
             this.l2RecordChangeSeqs.clear();
+            this.l2RecordsTracked = checkpoint.l2Tracked === true;
             if (checkpoint.l2RecordChangeSeqs &&
                 typeof checkpoint.l2RecordChangeSeqs === "object") {
                 for (const [docId, changeSeq] of Object.entries(checkpoint.l2RecordChangeSeqs)) {
@@ -3143,7 +3171,7 @@ class BaseMindooDB {
             const existingIndex = this.getDocIndexPosition(docId);
             const existing = existingIndex === undefined ? undefined : this.index[existingIndex];
             await this.ingestSealed(visibility.decryptionKeyId, metadataByDoc.get(docId));
-            const canRead = await this.tenant.hasDecryptionKey(visibility.decryptionKeyId);
+            const canRead = await this.canReadWithKey(visibility.decryptionKeyId, docId, metadataByDoc.get(docId));
             if (canRead) {
                 // This scan is the authority on visibility, so it also heals a tally
                 // that a visible->visible short-circuit below would leave untouched.
@@ -3447,6 +3475,8 @@ class BaseMindooDB {
             this.beginChangeNotificationHold();
             try {
                 await this.syncStoreChangesInternal();
+                // Joined or left a group document in this batch: its documents follow.
+                await this.reconcileGroupKeyAccess();
             }
             finally {
                 this.endChangeNotificationHold();
@@ -3505,6 +3535,26 @@ class BaseMindooDB {
                         this.logger.debug(`Dropping cached sealed document ${docId} — newest wrap is not for this user`);
                         return;
                     }
+                    // Full rebuild: drop the cached state and materialize the document
+                    // again, through the access-control path when that is enforced.
+                    const reloadFully = async () => {
+                        this.docCache.delete(docId);
+                        updatedDoc = await this.loadDocumentInternal(docId);
+                        if (updatedDoc) {
+                            // New entries triggered this reload, so force the re-emit.
+                            this.updateIndex(docId, updatedDoc.lastModified, updatedDoc.isDeleted, updatedDoc.decryptionKeyId, "visible", updatedDoc.awaitingWitness ?? false, updatedDoc.witnessed ?? false, true);
+                        }
+                    };
+                    if (await this.isAclEnforced()) {
+                        // The incremental path below applies new entries without the
+                        // access-control gate (docs/accesscontrol.md §10). With access
+                        // control active, a change by someone the rules do not allow must be
+                        // quarantined like on a fresh load, so rebuild the document through
+                        // maybeMaterializeWithAccessControl instead.
+                        this.logger.debug(`Document ${docId} found in cache, access control enforced: full reload`);
+                        await reloadFully();
+                        return;
+                    }
                     // Document is cached - try incremental update
                     this.logger.debug(`Document ${docId} found in cache, attempting incremental update`);
                     try {
@@ -3525,12 +3575,7 @@ class BaseMindooDB {
                     catch (error) {
                         // If incremental update fails, fall back to full reload
                         this.logger.warn(`Incremental update failed for document ${docId}, falling back to full reload:`, error);
-                        this.docCache.delete(docId);
-                        updatedDoc = await this.loadDocumentInternal(docId);
-                        if (updatedDoc) {
-                            // New entries triggered this reload, so force the re-emit.
-                            this.updateIndex(docId, updatedDoc.lastModified, updatedDoc.isDeleted, updatedDoc.decryptionKeyId, "visible", updatedDoc.awaitingWitness ?? false, updatedDoc.witnessed ?? false, true);
-                        }
+                        await reloadFully();
                     }
                 }
                 else {
@@ -3568,7 +3613,7 @@ class BaseMindooDB {
                             sealedIngestEntries = fullDocMetadata;
                         }
                         await this.ingestSealed(representativeEntry.decryptionKeyId, sealedIngestEntries);
-                        const keyAvailable = await this.tenant.hasDecryptionKey(representativeEntry.decryptionKeyId);
+                        const keyAvailable = await this.canReadWithKey(representativeEntry.decryptionKeyId, docId, coldSync ? entryMetadataList : fullDocMetadata);
                         if (!keyAvailable) {
                             this.logger.debug(`Skipping metadata-first index for doc ${docId} — decryption key "${representativeEntry.decryptionKeyId}" not available`);
                             // This is where a device that is still waiting for its keys meets
@@ -4497,6 +4542,10 @@ class BaseMindooDB {
                 throw new Error("createDocument: recipients is not supported together with a convergent custom id; " +
                     "pass assumeUniqueId for random ids.");
             }
+            if (useDeterministicSeed && options.groupKeyDocId !== undefined) {
+                throw new Error("createDocument: groupKeyDocId is not supported together with a convergent custom id; " +
+                    "pass assumeUniqueId for random ids.");
+            }
             if (useDeterministicSeed && (options.attachments?.length ?? 0) > 0) {
                 throw new Error("createDocument: attachments are not supported together with a convergent custom id; " +
                     "pass assumeUniqueId, or add them with changeDoc().");
@@ -4746,6 +4795,9 @@ class BaseMindooDB {
         if (useDeterministicSeed && options.recipients !== undefined) {
             throw new Error("createDocuments: recipients is not supported together with a convergent custom id; pass assumeUniqueId");
         }
+        if (useDeterministicSeed && options.groupKeyDocId !== undefined) {
+            throw new Error("createDocuments: groupKeyDocId is not supported together with a convergent custom id; pass assumeUniqueId");
+        }
         // Sanitize caller-provided initial values: internal/reserved fields are
         // managed by MindooDB and must not be seeded by callers. `undefined`
         // values are treated as "not set" (Automerge cannot represent undefined).
@@ -5084,13 +5136,112 @@ class BaseMindooDB {
     async ingestSealed(keyId, entries) {
         if (!this.tenant.ingestSealedFromEntries)
             return;
+        const hadKey = (0, sealedTypes_1.isSealedKeyId)(keyId) ? await this.tenant.hasDecryptionKey(keyId) : false;
+        const heldBefore = this.tenant.getSealedGenerations?.(keyId).length ?? 0;
         this.sealedIngestDepth++;
         try {
             await this.tenant.ingestSealedFromEntries(keyId, entries);
+            // A document encrypted with a group document's key series (`groupKeyDocId`)
+            // carries no recipient block of its own: the wraps are on the group document.
+            if ((0, sealedTypes_1.isSealedKeyId)(keyId) && !(0, recipients_1.newestRecipientBlock)(entries)) {
+                await this.ingestGroupKey(keyId);
+            }
+            // A series that does not reach back to epoch 1 may be completed from the
+            // key document's older recipient blocks; `entries` is often just a batch.
+            if ((0, sealedTypes_1.isSealedKeyId)(keyId) && this.tenant.needsDeepSealedIngest?.(keyId)) {
+                const keyDocId = (0, sealedTypes_1.sealedKeyDocId)(keyId);
+                if (keyDocId) {
+                    await this.tenant.ingestSealedFromEntries(keyId, await this.scanAllMetadata(this.store, { docId: keyDocId }), { complete: true });
+                }
+            }
         }
         finally {
             this.sealedIngestDepth--;
         }
+        if ((0, sealedTypes_1.isSealedKeyId)(keyId) &&
+            (hadKey !== (await this.tenant.hasDecryptionKey(keyId)) ||
+                (hadKey &&
+                    heldBefore !== (this.tenant.getSealedGenerations?.(keyId).length ?? 0)))) {
+            this.partialSeriesProbes.clear();
+            // Joined or left the key series: documents of a group document that were
+            // hidden (or readable) until now have to follow (see reconcileGroupKeyAccess).
+            this.groupKeyAccessChanged.add(keyId);
+        }
+    }
+    /**
+     * Whether this replica can read a document of key `keyId`. Usually the key id
+     * alone decides; a reader added to a group without its history
+     * (`history: "none"`) knows the key id but holds only the newer generations,
+     * so the document's origin entry is test-decrypted (once per document).
+     */
+    async canReadWithKey(keyId, docId, metas) {
+        if (!(await this.tenant.hasDecryptionKey(keyId)))
+            return false;
+        if (!(0, sealedTypes_1.isSealedKeyId)(keyId) || !this.tenant.isPartialSealedSeries?.(keyId))
+            return true;
+        const known = this.partialSeriesProbes.get(docId);
+        if (known !== undefined)
+            return known;
+        const all = metas ?? (await this.scanAllMetadata(this.store, { docId }));
+        // Loading starts from the newest snapshot when there is one (written under
+        // the new key when readers were added without history), else from the create.
+        const origin = all
+            .filter((meta) => meta.entryType === "doc_snapshot")
+            .sort((a, b) => b.createdAt - a.createdAt)[0] ??
+            all.find((meta) => meta.entryType === "doc_create");
+        if (!origin)
+            return true;
+        let ok = false;
+        try {
+            const [entry] = await this.store.getEntries([origin.id]);
+            if (entry) {
+                await this.tenant.decryptPayload(entry.encryptedData, entry.decryptionKeyId);
+                ok = true;
+            }
+        }
+        catch {
+            ok = false;
+        }
+        this.partialSeriesProbes.set(docId, ok);
+        return ok;
+    }
+    /**
+     * Makes the key series `$sealed:<groupDocId>` available from the group
+     * document's own entries when the session does not have it yet. A miss is
+     * remembered briefly, so a few hundred documents of a group this replica is not
+     * a member of cost one scan of the group document, not one each.
+     */
+    async ingestGroupKey(keyId) {
+        const groupDocId = (0, sealedTypes_1.sealedKeyDocId)(keyId);
+        if (!groupDocId || (await this.tenant.hasDecryptionKey(keyId)))
+            return;
+        const lastMiss = this.groupKeyMisses.get(keyId);
+        if (lastMiss !== undefined && Date.now() - lastMiss < BaseMindooDB.GROUP_KEY_MISS_TTL_MS)
+            return;
+        const groupEntries = await this.scanAllMetadata(this.store, { docId: groupDocId });
+        if (groupEntries.length > 0) {
+            await this.tenant.ingestSealedFromEntries(keyId, groupEntries);
+        }
+        if (await this.tenant.hasDecryptionKey(keyId)) {
+            this.groupKeyMisses.delete(keyId);
+        }
+        else {
+            this.groupKeyMisses.set(keyId, Date.now());
+        }
+    }
+    /**
+     * After a pass that changed access to a key series (added to or removed from a
+     * group document), reveal or hide the documents that use it. Runs the full key
+     * visibility reconcile, which is rare enough: it only happens when this
+     * replica's membership in a group changed.
+     */
+    async reconcileGroupKeyAccess() {
+        if (this.groupKeyAccessChanged.size === 0 || this.isTimeTravelMode())
+            return;
+        this.groupKeyAccessChanged.clear();
+        this.groupKeyMisses.clear();
+        await this.reconcileKeyVisibility();
+        this.groupKeyAccessChanged.clear();
     }
     /**
      * Unwrap a `$sealed:` DEK from entry recipient wraps into the tenant session
@@ -8509,7 +8660,9 @@ class BaseMindooDB {
             isAccessible: () => true,
             isAwaitingWitness: () => internalDoc.awaitingWitness ?? false,
             isWitnessed: () => internalDoc.witnessed ?? false,
-            isSealed: () => (0, sealedTypes_1.isSealedKeyId)(internalDoc.decryptionKeyId),
+            isSealed: () => (0, sealedTypes_1.isSealedKeyId)(internalDoc.decryptionKeyId) &&
+                (0, sealedTypes_1.groupKeyDocIdOf)(internalDoc.decryptionKeyId, internalDoc.id) === undefined,
+            getGroupKeyDocId: () => (0, sealedTypes_1.groupKeyDocIdOf)(internalDoc.decryptionKeyId, internalDoc.id),
             getRecipients: () => (0, recipients_1.resolveRecipientsFromPayload)(internalDoc.doc, internalDoc.sealedRecipients),
             getRecipientEpoch: () => internalDoc.sealedRecipients?.epoch ?? 0,
             isEncryptedFor: (users) => (0, sealedTypes_1.isSealedKeyId)(internalDoc.decryptionKeyId) &&
@@ -9670,6 +9823,7 @@ class BaseMindooDB {
                 attachmentIds,
                 bypassPrecheck,
                 recipients: options.recipients,
+                forceSnapshot: options.forceSnapshot,
             });
         }
         catch (error) {
@@ -9772,8 +9926,9 @@ class BaseMindooDB {
                 signingKeyPair,
                 signingKeyPassword,
                 createdByPublicKey: createdByPublicKey ?? "",
+                force: options.forceSnapshot,
             }
-            : { createdByPublicKey: createdByPublicKey ?? "" });
+            : { createdByPublicKey: createdByPublicKey ?? "", force: options.forceSnapshot });
     }
     async buildDocChangeStoreEntry(options) {
         const { internalDoc, changeBytes, now, useCustomKey, signingKeyPair, signingKeyPassword, attachmentIds, attachmentRefs, recipients, } = options;
@@ -9840,7 +9995,7 @@ class BaseMindooDB {
             // An absent counter (first write this session) forces one scan to learn
             // the real backlog, after which the counter tracks it incrementally.
             const knownWrites = this.writesSinceSnapshotCheck.get(docId);
-            if (knownWrites !== undefined) {
+            if (knownWrites !== undefined && !options.force) {
                 const writes = knownWrites + 1;
                 if (writes < this.snapshotMinChanges) {
                     this.writesSinceSnapshotCheck.set(docId, writes);
@@ -9856,10 +10011,11 @@ class BaseMindooDB {
             const latestSnapshotAt = latestSnapshot?.createdAt ?? 0;
             const changesSinceSnapshot = replayEntries.filter((em) => em.createdAt > latestSnapshotAt).length;
             this.writesSinceSnapshotCheck.set(docId, changesSinceSnapshot);
-            if (changesSinceSnapshot < this.snapshotMinChanges) {
+            if (changesSinceSnapshot < this.snapshotMinChanges && !options.force) {
                 return;
             }
-            if (latestSnapshot &&
+            if (!options.force &&
+                latestSnapshot &&
                 Date.now() - latestSnapshot.createdAt < this.snapshotCooldownMs) {
                 return;
             }
@@ -10022,6 +10178,34 @@ class BaseMindooDB {
         await flushPage();
         return buffer;
     }
+    /**
+     * Fetch the L2 records of a prefetch window in one batched read instead
+     * of one cache-store round trip per document. Only documents that may
+     * have a record are asked for (see {@link l2RecordsTracked}); the results
+     * are consumed by {@link tryLoadFromL2}. Best effort: on failure the
+     * loads fall back to their own reads.
+     */
+    async prefetchL2Records(docIds) {
+        const store = this.cacheManager?.getStore() ?? null;
+        if (!store) {
+            return [];
+        }
+        const wanted = docIds.filter((docId) => !this.l2Prefetched.has(docId) &&
+            (!this.l2RecordsTracked || this.l2RecordChangeSeqs.has(docId)));
+        if (wanted.length === 0) {
+            return [];
+        }
+        const prefix = this.getCachePrefix();
+        try {
+            const records = await store.getMany("doc", wanted.map((docId) => `${prefix}/${docId}`));
+            wanted.forEach((docId, i) => this.l2Prefetched.set(docId, records[i] ?? null));
+            return wanted;
+        }
+        catch (err) {
+            this.logger.warn(`Batched L2 read for a prefetch window failed:`, err);
+            return [];
+        }
+    }
     /**
      * Materialize a window of upcoming documents so iteration reads them from
      * the cache instead of the store.
@@ -10037,7 +10221,7 @@ class BaseMindooDB {
      *
      * Returns the position prefetched through, which the caller threads back in.
      */
-    async prefetchIterationWindow(indexSnapshot, startIndex, prefetchedThrough, idPrefix) {
+    async prefetchIterationWindow(indexSnapshot, startIndex, prefetchedThrough, idPrefix, persist = true) {
         const windowSize = this.iteratePrefetchWindowDocs;
         if (windowSize <= 0) {
             return { prefetchedThrough: startIndex, prefetchedDocuments: 0 };
@@ -10097,14 +10281,20 @@ class BaseMindooDB {
             this.logger.warn(`Failed to batch-fetch entries for prefetch window:`, err);
             this.materializationEntryBuffer = null;
         }
+        const prefetchedL2 = await this.prefetchL2Records(docIds);
         try {
-            await Promise.all(docIds.map((docId) => this.loadDocumentInternal(docId).catch((err) => {
+            await Promise.all(docIds.map((docId) => this.loadDocumentInternal(docId, persist).catch((err) => {
                 this.logger.warn(`Failed to prefetch document ${docId}:`, err);
                 return null;
             })));
         }
         finally {
             this.materializationEntryBuffer = null;
+            // Records a load did not consume (shared or failed load) must not be
+            // used by a later read: they may be outdated by then.
+            for (const docId of prefetchedL2) {
+                this.l2Prefetched.delete(docId);
+            }
         }
         return {
             prefetchedThrough: scannedThrough,
@@ -10524,6 +10714,7 @@ class BaseMindooDB {
             docId: "",
         };
         const idPrefix = this.normalizeIdPrefixFilter(options?.idPrefix);
+        const persistLoaded = options?.persistLoadedDocuments !== false;
         this.logger.debug(`Starting iteration from cursor ${JSON.stringify(actualCursor)}`);
         // Use a stable snapshot of the index for this generator run so concurrent
         // updates do not reorder/skip entries while iterating.
@@ -10536,7 +10727,7 @@ class BaseMindooDB {
         // so concurrent iterations do not share a runway.
         let prefetchedThrough = startIndex;
         const prefetchFrom = async (from) => {
-            const result = await this.prefetchIterationWindow(indexSnapshot, from, prefetchedThrough, idPrefix);
+            const result = await this.prefetchIterationWindow(indexSnapshot, from, prefetchedThrough, idPrefix, persistLoaded);
             prefetchedThrough = result.prefetchedThrough;
             prefetchedDocuments += result.prefetchedDocuments;
         };
@@ -10593,7 +10784,7 @@ class BaseMindooDB {
                     let internalDoc = this.getCachedDocument(entry.docId);
                     if (!internalDoc) {
                         this.logger.debug(`Document ${entry.docId} not in cache, loading from store`);
-                        internalDoc = await this.loadDocumentInternal(entry.docId);
+                        internalDoc = await this.loadDocumentInternal(entry.docId, persistLoaded);
                         if (internalDoc) {
                             loadedDocuments++;
                         }
@@ -10820,13 +11011,23 @@ class BaseMindooDB {
         const prefix = this.getCachePrefix();
         const key = `${prefix}/${docId}`;
         let bytes;
-        try {
-            bytes = await store.get("doc", key);
+        if (this.l2Prefetched.has(docId)) {
+            bytes = this.l2Prefetched.get(docId) ?? null;
+            this.l2Prefetched.delete(docId);
         }
-        catch (e) {
-            this.logger.warn(`L2 read failed for ${docId}; falling back to full materialization: ${e}`);
+        else if (this.l2RecordsTracked && !this.l2RecordChangeSeqs.has(docId)) {
+            // Known to have no L2 record: skip the store round trip.
             return null;
         }
+        else {
+            try {
+                bytes = await store.get("doc", key);
+            }
+            catch (e) {
+                this.logger.warn(`L2 read failed for ${docId}; falling back to full materialization: ${e}`);
+                return null;
+            }
+        }
         if (!bytes)
             return null;
         let deserialized;
@@ -11347,6 +11548,12 @@ class BaseMindooDB {
             options.decryptionKeyId !== undefined) {
             throw new Error("createDocument: recipients and decryptionKeyId are mutually exclusive");
         }
+        if (options.groupKeyDocId !== undefined) {
+            if (options.recipients !== undefined || options.decryptionKeyId !== undefined) {
+                throw new Error("createDocument: groupKeyDocId is mutually exclusive with recipients and decryptionKeyId");
+            }
+            return await this.requireGroupKey(options.groupKeyDocId);
+        }
         if (options.recipients !== undefined) {
             return (0, sealedTypes_1.sealedKeyId)(docId ?? options.id ?? "pending");
         }
@@ -11366,6 +11573,27 @@ class BaseMindooDB {
         }
         return "default";
     }
+    /**
+     * The key id of a group document's key series, after checking that the group
+     * document is a sealed document of this database and that the caller is a member.
+     */
+    async requireGroupKey(groupKeyDocId) {
+        if (!types_1.CUSTOM_DOC_ID_REGEX.test(groupKeyDocId) && !/^[a-z0-9_]+$/.test(groupKeyDocId)) {
+            throw new Error(`createDocument: invalid groupKeyDocId "${groupKeyDocId}"`);
+        }
+        const keyId = (0, sealedTypes_1.sealedKeyId)(groupKeyDocId);
+        const groupEntries = await this.scanAllMetadata(this.store, { docId: groupKeyDocId });
+        const groupCreate = groupEntries.find((entry) => entry.entryType === "doc_create");
+        if (!groupCreate || groupCreate.decryptionKeyId !== keyId) {
+            throw new Error(`createDocument: group document "${groupKeyDocId}" does not exist in this database or was not created with recipients`);
+        }
+        this.groupKeyMisses.delete(keyId);
+        await this.ingestSealed(keyId, groupEntries);
+        if (!(await this.tenant.hasDecryptionKey(keyId))) {
+            throw new Error(`createDocument: you are not a member of group document "${groupKeyDocId}"`);
+        }
+        return keyId;
+    }
     async prepareSealedCreate(options, docId, keyId, now, signerPublicKey) {
         if (options.recipients === undefined)
             return undefined;
@@ -11510,6 +11738,9 @@ class BaseMindooDB {
     async setRecipients(doc, recipients, options) {
         return this.mutateRecipients(doc, "set", recipients, options);
     }
+    async revealHistory(doc, recipients, options) {
+        return this.mutateRecipients(doc, "reveal", recipients, options);
+    }
     async canChangeRecipients(doc, next) {
         const after = { ...doc.getData() };
         after[sealedTypes_1.ENCRYPT_FOR_FIELD] = {
@@ -11523,6 +11754,10 @@ class BaseMindooDB {
         if (!(0, sealedTypes_1.isSealedKeyId)(doc.getDecryptionKeyId())) {
             throw new Error("Recipient mutators require a document created with `recipients`");
         }
+        const groupDocId = (0, sealedTypes_1.groupKeyDocIdOf)(doc.getDecryptionKeyId(), doc.getId());
+        if (groupDocId !== undefined) {
+            throw new Error(`Document ${doc.getId()} uses the key series of group document ${groupDocId}; change the recipients there`);
+        }
         const tenant = this.tenant;
         const docId = doc.getId();
         let internalDoc = this.getCachedDocument(docId) ?? (await this.loadDocumentInternal(docId));
@@ -11562,6 +11797,16 @@ class BaseMindooDB {
                     addedTargets.push(target);
             }
         }
+        const revealedIds = [];
+        if (mode === "reveal") {
+            for (const [id, entry] of Object.entries(currentMap)) {
+                if (entry.removedAt || !entry.historyFrom)
+                    continue;
+                if (resolved.targets.some((target) => matchesTarget(id, entry, target))) {
+                    revealedIds.push(id);
+                }
+            }
+        }
         if (mode === "remove") {
             for (const [id, entry] of Object.entries(currentMap)) {
                 if (entry.removedAt)
@@ -11582,19 +11827,69 @@ class BaseMindooDB {
                     removedStableIds.push(base);
             }
         }
-        const rotate = removedStableIds.length > 0;
-        const currentGens = tenant.getSealedGenerations(internalDoc.decryptionKeyId);
-        if (currentGens.length === 0) {
+        const withoutHistory = (mode === "add" || mode === "set") &&
+            addedTargets.length > 0 &&
+            (options?.history ?? sealedTypes_1.DEFAULT_RECIPIENT_HISTORY) === "none";
+        const rotate = removedStableIds.length > 0 || withoutHistory;
+        const heldSeries = tenant.getSealedSeries
+            ? tenant.getSealedSeries(internalDoc.decryptionKeyId)
+            : tenant
+                .getSealedGenerations(internalDoc.decryptionKeyId)
+                .map((key, index, all) => ({ epoch: all.length - index, key }));
+        if (heldSeries.length === 0) {
             throw new Error("Cannot change recipients: the current document key is not in this session");
         }
-        let generations = currentGens;
-        let epoch = internalDoc.sealedRecipients?.epoch ?? currentGens.length;
+        // The epoch comes from the store, not from the cached document.
+        const newestBlock = (0, recipients_1.newestRecipientBlock)(await this.scanAllMetadata(this.store, { docId })) ??
+            internalDoc.sealedRecipients;
+        let epoch = Math.max(newestBlock?.epoch ?? 0, heldSeries[0].epoch);
+        if (heldSeries[0].epoch < epoch) {
+            throw new Error("Cannot change recipients: this replica does not hold the current document key yet; sync first");
+        }
+        // What this replica can seal: the contiguous run of generations that ends at
+        // the current epoch. A member who joined without the earlier history holds a
+        // shorter run; readers entitled to more keep taking the older generations
+        // from the earlier recipient blocks (see ingestSealedFromEntries).
+        let series = heldSeries;
+        let run = [];
+        for (const entry of heldSeries) {
+            if (run.length > 0 && entry.epoch !== run[run.length - 1].epoch - 1)
+                break;
+            run.push(entry);
+        }
         if (rotate) {
             const nextDek = tenant
                 .getCryptoAdapter()
                 .getRandomValues(new Uint8Array(32));
-            generations = [nextDek, ...currentGens];
             epoch += 1;
+            run = [{ epoch, key: nextDek }, ...run];
+            series = [{ epoch, key: nextDek }, ...heldSeries];
+        }
+        /** Oldest epoch this replica can hand to anyone. */
+        const sealFrom = run[run.length - 1].epoch;
+        const generations = run.map((entry) => entry.key);
+        const addedHistoryFrom = withoutHistory
+            ? epoch
+            : sealFrom > 1
+                ? sealFrom
+                : undefined;
+        // Revealing reaches as far back as the caller's own history.
+        const revealTo = sealFrom > 1 ? sealFrom : undefined;
+        for (const id of [...revealedIds]) {
+            if ((currentMap[id]?.historyFrom ?? 1) <= sealFrom) {
+                revealedIds.splice(revealedIds.indexOf(id), 1);
+            }
+        }
+        const historyFromByStable = new Map();
+        for (const [id, entry] of Object.entries(currentMap)) {
+            if (entry.removedAt || !entry.historyFrom)
+                continue;
+            const from = revealedIds.includes(id) ? revealTo : entry.historyFrom;
+            if (!from)
+                continue;
+            historyFromByStable.set(id.split("#")[0], from);
+            if (entry.keyFingerprint)
+                historyFromByStable.set(entry.keyFingerprint, from);
         }
         const remainingByStable = new Map();
         const existingSpecs = Object.entries(currentMap)
@@ -11613,8 +11908,14 @@ class BaseMindooDB {
             for (const target of existingResolved.targets)
                 remainingByStable.set(target.stableId, target);
         }
+        for (const [stableId, target] of remainingByStable) {
+            const from = historyFromByStable.get(stableId) ??
+                historyFromByStable.get(target.keyFingerprint);
+            if (from)
+                remainingByStable.set(stableId, { ...target, historyFrom: from });
+        }
         for (const target of addedTargets)
-            remainingByStable.set(target.stableId, target);
+            remainingByStable.set(target.stableId, addedHistoryFrom ? { ...target, historyFrom: addedHistoryFrom } : target);
         for (const id of removedStableIds) {
             remainingByStable.delete(id);
             for (const [stableId, target] of [...remainingByStable.entries()]) {
@@ -11635,7 +11936,7 @@ class BaseMindooDB {
             targets: remaining,
             epoch,
         });
-        tenant.rememberSealedGenerations(internalDoc.decryptionKeyId, generations);
+        tenant.rememberSealedGenerations(internalDoc.decryptionKeyId, series.map((entry) => entry.key), recipientsBlock, series.map((entry) => entry.epoch));
         const headsBeforeChange = automerge_adapter_1.Automerge.getHeads(internalDoc.doc);
         const newDoc = automerge_adapter_1.Automerge.change(internalDoc.doc, { message: changeMessage }, (draft) => {
             if (addedTargets.length > 0) {
@@ -11647,10 +11948,22 @@ class BaseMindooDB {
                         addedBy: signer,
                         keyFingerprint: target.keyFingerprint,
                         ...(target.label ? { label: target.label } : {}),
+                        ...(addedHistoryFrom ? { historyFrom: addedHistoryFrom } : {}),
                     };
                 }
                 (0, recipients_1.applyEncryptForAdds)(draft, addMap, epoch);
             }
+            if (revealedIds.length > 0) {
+                const map = draft[sealedTypes_1.ENCRYPT_FOR_FIELD];
+                for (const id of revealedIds) {
+                    if (!map[id])
+                        continue;
+                    if (revealTo)
+                        map[id].historyFrom = revealTo;
+                    else
+                        delete map[id].historyFrom;
+                }
+            }
             if (removedStableIds.length > 0) {
                 (0, recipients_1.applyEncryptForRemoves)(draft, removedStableIds, now, signer);
             }
@@ -11671,6 +11984,9 @@ class BaseMindooDB {
             successMessage: "recipients updated",
             bypassPrecheck: options?.bypassAccessControlPrecheck,
             recipients: recipientsBlock,
+            // Readers added without history cannot decrypt the older entries of this
+            // document itself: a snapshot under the new key gives them its current state.
+            forceSnapshot: withoutHistory,
         });
         if (options?.change) {
             await this.changeDoc(this.wrapDocument(internalDoc), options.change, {
@@ -12136,21 +12452,36 @@ class BaseMindooDB {
      * document were indexed since it started, so no caller gets a state older
      * than its call.
      */
-    loadDocumentInternal(docId) {
+    loadDocumentInternal(docId, persist = true) {
         const generation = this.docEntryGeneration.get(docId) ?? 0;
         const inFlight = this.documentLoadsInFlight.get(docId);
+        let promise;
         if (inFlight && inFlight.generation === generation) {
-            return inFlight.promise;
+            promise = inFlight.promise;
+        }
+        else {
+            const started = this.loadDocumentUncoalesced(docId, persist).finally(() => {
+                if (this.documentLoadsInFlight.get(docId)?.promise === started) {
+                    this.documentLoadsInFlight.delete(docId);
+                }
+            });
+            this.documentLoadsInFlight.set(docId, { generation, promise: started });
+            promise = started;
         }
-        const promise = this.loadDocumentUncoalesced(docId).finally(() => {
-            if (this.documentLoadsInFlight.get(docId)?.promise === promise) {
-                this.documentLoadsInFlight.delete(docId);
+        if (!persist) {
+            return promise;
+        }
+        // A regular read of a document a scan materialized (shared load or L1
+        // hit) wants it in the persistent cache as usual.
+        return promise.then((loaded) => {
+            if (loaded?.scanOnly && this.docCache.get(docId) === loaded) {
+                delete loaded.scanOnly;
+                this.markDocDirty(docId);
             }
+            return loaded;
         });
-        this.documentLoadsInFlight.set(docId, { generation, promise });
-        return promise;
     }
-    async loadDocumentUncoalesced(docId) {
+    async loadDocumentUncoalesced(docId, persist = true) {
         const startedAt = Date.now();
         const cacheCheckStartedAt = Date.now();
         // Short-circuit on the visibility layer: a doc marked
@@ -12559,7 +12890,17 @@ class BaseMindooDB {
         // result is already outdated and the next read materializes again)
         if (this.isEntryGenerationCurrent(docId, entryGeneration)) {
             await this.storeCachedDocument(internalDoc);
-            this.markDocDirty(docId);
+            // Scan loads (index builds) keep the document in L1 only: marking it
+            // dirty would write every document of a full pass to the persistent
+            // L2 cache on eviction. While the background warmer is running, the
+            // L2 cache is being filled anyway: persist then, so the warmer does
+            // not materialize the same document a second time.
+            if (persist || this.warmerPromise !== null) {
+                this.markDocDirty(docId);
+            }
+            else {
+                internalDoc.scanOnly = true;
+            }
             this.logger.debug(`===== Successfully loaded document ${docId} and cached it =====`);
         }
         else {
@@ -12702,7 +13043,9 @@ class BaseMindooDB {
             isAccessible: () => internalDoc.accessible ?? true,
             isAwaitingWitness: () => internalDoc.awaitingWitness ?? false,
             isWitnessed: () => internalDoc.witnessed ?? false,
-            isSealed: () => (0, sealedTypes_1.isSealedKeyId)(internalDoc.decryptionKeyId),
+            isSealed: () => (0, sealedTypes_1.isSealedKeyId)(internalDoc.decryptionKeyId) &&
+                (0, sealedTypes_1.groupKeyDocIdOf)(internalDoc.decryptionKeyId, internalDoc.id) === undefined,
+            getGroupKeyDocId: () => (0, sealedTypes_1.groupKeyDocIdOf)(internalDoc.decryptionKeyId, internalDoc.id),
             getRecipients: () => (0, recipients_1.resolveRecipientsFromPayload)(internalDoc.doc, internalDoc.sealedRecipients),
             getRecipientEpoch: () => internalDoc.sealedRecipients?.epoch ?? 0,
             isEncryptedFor: (users) => (0, sealedTypes_1.isSealedKeyId)(internalDoc.decryptionKeyId) &&
@@ -13764,6 +14107,7 @@ class BaseMindooDB {
     }
 }
 exports.BaseMindooDB = BaseMindooDB;
+BaseMindooDB.GROUP_KEY_MISS_TTL_MS = 2000;
 /** The "access control not enforced" allow decision returned by the
  * non-throwing `canCreate`/`canChange`/`canDelete` prediction helpers. */
 BaseMindooDB.ACL_NOT_ENFORCED_DECISION = {