mindoodb 0.0.24 → 0.0.32

package/dist/core/indexing/fulltext/types.js

@@ -0,0 +1,89 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.FULLTEXT_ATTACHMENT_FIELD = exports.DEFAULT_FULLTEXT_MAX_FIELD_BYTES = exports.FULLTEXT_INDEX_FORMAT_VERSION = exports.FULLTEXT_SETUP_FIELD = void 0;
+exports.resolveFulltextConfig = resolveFulltextConfig;
+exports.sanitizeFulltextConfig = sanitizeFulltextConfig;
+exports.computeFulltextConfigFingerprint = computeFulltextConfigFingerprint;
+/**
+ * Field of the `dbsetup` document holding the {@link FulltextConfig} used
+ * by full-text indexes that were not given an explicit configuration in
+ * code. Lives next to `summarySetup` in the same synced setup document
+ * (see docs/adhoc-queries.md and docs/fulltext-search.md).
+ */
+exports.FULLTEXT_SETUP_FIELD = "fulltextSetup";
+/**
+ * Version of the persisted index format (serialization layout AND the
+ * engine/tokenizer behavior). Part of the config fingerprint, so bumping
+ * it invalidates persisted indexes and triggers a clean rebuild.
+ */
+exports.FULLTEXT_INDEX_FORMAT_VERSION = 3;
+/**
+ * Default per-field cap (approximate bytes, JS string length) for text
+ * extracted into the full-text index. Longer values are truncated — not
+ * skipped — so a huge e-mail body still contributes its first part.
+ */
+exports.DEFAULT_FULLTEXT_MAX_FIELD_BYTES = 256 * 1024;
+/**
+ * Synthetic index field holding text extracted from a document's
+ * attachments (via registered {@link AttachmentTextExtractor}s). Hits
+ * stay document-scoped (the Notes model): searching matches the document,
+ * not an individual attachment.
+ */
+exports.FULLTEXT_ATTACHMENT_FIELD = "_attachments";
+function resolveFulltextConfig(config) {
+    return {
+        enabled: config?.enabled ?? false,
+        include: [...(config?.include ?? [])],
+        attachments: config?.attachments ?? false,
+        language: config?.language ?? "und",
+        maxFieldBytes: Math.max(0, config?.maxFieldBytes ?? exports.DEFAULT_FULLTEXT_MAX_FIELD_BYTES),
+    };
+}
+/**
+ * Extract a {@link FulltextConfig} from an untyped value (the
+ * `fulltextSetup` field of the synced setup document). Unknown properties
+ * are dropped and wrongly-typed ones ignored, so a malformed document can
+ * never break index maintenance. Returns `undefined` when the value is
+ * not an object (missing field, deleted document) — callers fall back to
+ * the default (disabled) configuration.
+ */
+function sanitizeFulltextConfig(value) {
+    if (value === null || typeof value !== "object" || Array.isArray(value)) {
+        return undefined;
+    }
+    const raw = value;
+    const config = {};
+    if (typeof raw.enabled === "boolean") {
+        config.enabled = raw.enabled;
+    }
+    if (Array.isArray(raw.include)) {
+        config.include = raw.include.filter((item) => typeof item === "string");
+    }
+    if (typeof raw.attachments === "boolean") {
+        config.attachments = raw.attachments;
+    }
+    if (typeof raw.language === "string" && raw.language.length > 0 && raw.language.length <= 35) {
+        config.language = raw.language;
+    }
+    if (typeof raw.maxFieldBytes === "number" && Number.isFinite(raw.maxFieldBytes)) {
+        config.maxFieldBytes = raw.maxFieldBytes;
+    }
+    return config;
+}
+/**
+ * Deterministic fingerprint of a full-text configuration, including the
+ * index format/engine version. Persisted alongside the index; a mismatch
+ * on restore (or a config change at runtime) marks the index as
+ * `"rebuilding"` and triggers a resumable backfill.
+ */
+function computeFulltextConfigFingerprint(config) {
+    return JSON.stringify({
+        formatVersion: exports.FULLTEXT_INDEX_FORMAT_VERSION,
+        enabled: config.enabled,
+        include: [...config.include].sort(),
+        attachments: config.attachments,
+        language: config.language,
+        maxFieldBytes: config.maxFieldBytes,
+    });
+}
+//# sourceMappingURL=types.js.map

package/dist/core/indexing/fulltext/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../../../src/core/indexing/fulltext/types.ts"],"names":[],"mappings":";;;AA0FA,sDAQC;AAUD,wDAsBC;AAQD,4EASC;AAjJD;;;;;GAKG;AACU,QAAA,oBAAoB,GAAG,eAAe,CAAC;AAEpD;;;;GAIG;AACU,QAAA,6BAA6B,GAAG,CAAC,CAAC;AAE/C;;;;GAIG;AACU,QAAA,gCAAgC,GAAG,GAAG,GAAG,IAAI,CAAC;AAE3D;;;;;GAKG;AACU,QAAA,yBAAyB,GAAG,cAAc,CAAC;AA4DxD,SAAgB,qBAAqB,CAAC,MAAuB;IAC3D,OAAO;QACL,OAAO,EAAE,MAAM,EAAE,OAAO,IAAI,KAAK;QACjC,OAAO,EAAE,CAAC,GAAG,CAAC,MAAM,EAAE,OAAO,IAAI,EAAE,CAAC,CAAC;QACrC,WAAW,EAAE,MAAM,EAAE,WAAW,IAAI,KAAK;QACzC,QAAQ,EAAE,MAAM,EAAE,QAAQ,IAAI,KAAK;QACnC,aAAa,EAAE,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,MAAM,EAAE,aAAa,IAAI,wCAAgC,CAAC;KACtF,CAAC;AACJ,CAAC;AAED;;;;;;;GAOG;AACH,SAAgB,sBAAsB,CAAC,KAAc;IACnD,IAAI,KAAK,KAAK,IAAI,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,EAAE,CAAC;QACxE,OAAO,SAAS,CAAC;IACnB,CAAC;IACD,MAAM,GAAG,GAAG,KAAgC,CAAC;IAC7C,MAAM,MAAM,GAAmB,EAAE,CAAC;IAClC,IAAI,OAAO,GAAG,CAAC,OAAO,KAAK,SAAS,EAAE,CAAC;QACrC,MAAM,CAAC,OAAO,GAAG,GAAG,CAAC,OAAO,CAAC;IAC/B,CAAC;IACD,IAAI,KAAK,CAAC,OAAO,CAAC,GAAG,CAAC,OAAO,CAAC,EAAE,CAAC;QAC/B,MAAM,CAAC,OAAO,GAAG,GAAG,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC,IAAI,EAAkB,EAAE,CAAC,OAAO,IAAI,KAAK,QAAQ,CAAC,CAAC;IAC1F,CAAC;IACD,IAAI,OAAO,GAAG,CAAC,WAAW,KAAK,SAAS,EAAE,CAAC;QACzC,MAAM,CAAC,WAAW,GAAG,GAAG,CAAC,WAAW,CAAC;IACvC,CAAC;IACD,IAAI,OAAO,GAAG,CAAC,QAAQ,KAAK,QAAQ,IAAI,GAAG,CAAC,QAAQ,CAAC,MAAM,GAAG,CAAC,IAAI,GAAG,CAAC,QAAQ,CAAC,MAAM,IAAI,EAAE,EAAE,CAAC;QAC7F,MAAM,CAAC,QAAQ,GAAG,GAAG,CAAC,QAAQ,CAAC;IACjC,CAAC;IACD,IAAI,OAAO,GAAG,CAAC,aAAa,KAAK,QAAQ,IAAI,MAAM,CAAC,QAAQ,CAAC,GAAG,CAAC,aAAa,CAAC,EAAE,CAAC;QAChF,MAAM,CAAC,aAAa,GAAG,GAAG,CAAC,aAAa,CAAC;IAC3C,CAAC;IACD,OAAO,MAAM,CAAC;AAChB,CAAC;AAED;;;;;GAKG;AACH,SAAgB,gCAAgC,CAAC,MAA8B;IAC7E,OAAO,IAAI,CAAC,SAAS,CAAC;QACpB,aAAa,EAAE,qCAA6B;QAC5C,OAAO,EAAE,MAAM,CAAC,OAAO;QACvB,OAAO,EAAE,CAAC,GAAG,MAAM,CAAC,OAAO,CAAC,CAAC,IAAI,EAAE;QACnC,WAAW,EAAE,MAAM,CAAC,WAAW;QAC/B,QAAQ,EAAE,MAAM,CAAC,QAAQ;QACzB,aAAa,EAAE,MAAM,CAAC,aAAa;KACpC,CAAC,CAAC;AACL,CAAC"}

package/dist/core/indexing/summary/DocumentSummaryStore.d.ts

@@ -0,0 +1,137 @@
+import type { MindooDB, ProcessChangesCursor } from "../../types";
+import type { LocalCacheStore } from "../../cache/LocalCacheStore";
+import type { CacheManager, ICacheable } from "../../cache/CacheManager";
+import type { VirtualViewUpdateOptions } from "../virtualviews/IVirtualViewDataProvider";
+import type { DocumentSummaryEntry, ResolvedSummaryConfig, SummaryConfig, SummaryCoverage } from "./types";
+/**
+ * The document summary buffer: a changefeed-maintained, per-document map of
+ * queryable field values (see docs/adhoc-queries.md).
+ *
+ * Ad-hoc queries and summary-backed views evaluate exclusively against this
+ * store, so they never pay document materialization. The store is kept
+ * up to date incrementally via `iterateChangesSince` (deleted/inaccessible
+ * documents arrive as lightweight tombstones and are removed), persists in
+ * encrypted buckets through the tenant's {@link LocalCacheStore}, and
+ * survives configuration changes with a resumable backfill instead of any
+ * document rewrite.
+ */
+export declare class DocumentSummaryStore implements ICacheable {
+    private readonly db;
+    private config;
+    private configFingerprint;
+    /**
+     * `true` when the configuration came from code (constructor arg or
+     * `setConfig`). Without an explicit configuration the store follows the
+     * `summarySetup` field of the synced {@link DB_SETUP_DOC_ID} document.
+     */
+    private hasExplicitConfig;
+    /** Whether the setup document was already consulted (once per instance). */
+    private setupDocSeeded;
+    private entries;
+    private cursor;
+    private cacheManager;
+    private cachePrefix;
+    private readonly bucketCount;
+    private dirtyBuckets;
+    private metaDirty;
+    private restorePromise;
+    private restored;
+    private needsBackfill;
+    private backfillCursor;
+    private updatePromise;
+    constructor(db: MindooDB, config?: SummaryConfig);
+    getConfig(): ResolvedSummaryConfig;
+    getConfigFingerprint(): string;
+    /**
+     * Replace the summary configuration. When the fingerprint changes and
+     * entries already exist, the store keeps serving the previous state and
+     * schedules a resumable backfill that re-extracts all documents with the
+     * new configuration on the next `update()` run.
+     *
+     * Calling this marks the configuration as explicit: the store stops
+     * following the {@link DB_SETUP_DOC_ID} document.
+     */
+    setConfig(config?: SummaryConfig): void;
+    /** Shared config-swap logic for explicit and setup-document paths. */
+    private applyConfig;
+    private scheduleBackfill;
+    /**
+     * Adopt the configuration from the synced {@link DB_SETUP_DOC_ID}
+     * document (its `summarySetup` field) unless an explicit configuration
+     * was provided in code. Runs once per instance, BEFORE the persisted
+     * state is restored, so the fingerprint comparison on restore already
+     * sees the setup-document configuration (a stale persisted fingerprint
+     * then schedules the backfill exactly once).
+     *
+     * Later changes to the setup document — local edits or sync ingest —
+     * arrive through the changefeed and are applied in `applyDocument`.
+     */
+    private seedConfigFromSetupDoc;
+    /**
+     * Make sure the effective configuration is settled: consults the
+     * {@link DB_SETUP_DOC_ID} document once (unless the config was provided
+     * in code) and returns the resolved configuration. Callers that make
+     * decisions based on coverage (e.g. the view data-provider factory)
+     * should await this before calling {@link isFieldCovered}.
+     */
+    ensureConfigLoaded(): Promise<ResolvedSummaryConfig>;
+    /**
+     * Whether a field path can be answered from this summary (see
+     * {@link isFieldPathCovered}). Coverage is configuration-level; individual
+     * documents may still lack a value.
+     */
+    isFieldCovered(path: string): boolean;
+    /**
+     * `"full"` when all entries reflect the current configuration,
+     * `"rebuilding"` while a configuration-change backfill is in progress.
+     */
+    getCoverage(): SummaryCoverage;
+    getEntry(docId: string): DocumentSummaryEntry | undefined;
+    getAllEntries(): IterableIterator<DocumentSummaryEntry>;
+    getSize(): number;
+    getCursor(): ProcessChangesCursor | null;
+    /**
+     * Bring the summary up to date with the changefeed. Restores persisted
+     * state on first use, then consumes `iterateChangesSince` from the saved
+     * cursor and finally works down a pending configuration backfill.
+     *
+     * Accepts the same batching/progress/cancellation options as VirtualView
+     * updates; an interrupted run resumes from the saved cursors.
+     * Calls are single-flight: concurrent callers share one run.
+     */
+    update(options?: VirtualViewUpdateOptions): Promise<void>;
+    private runUpdate;
+    private applyDocument;
+    /**
+     * Drop a document's summary entry immediately (called from the DB's purge
+     * paths so plaintext field values never outlive key revocation/purges;
+     * the changefeed tombstone would remove it anyway, but only on the next
+     * update run).
+     */
+    removeDocument(docId: string): void;
+    /** Drop all entries and cursors (e.g. after the underlying store was cleared). */
+    reset(): void;
+    /**
+     * Attach cache persistence. `cachePrefix` scopes all records of this
+     * summary (recommended: `<dbCachePrefix>/summary`). Registers with the
+     * CacheManager for periodic flushing; the persisted state is restored
+     * lazily on the first `update()` call.
+     */
+    attachCache(cacheManager: CacheManager, cachePrefix: string): void;
+    getCachePrefix(): string;
+    hasDirtyState(): boolean;
+    clearDirty(): void;
+    private bucketIndexFor;
+    private markBucketDirty;
+    flushToCache(store: LocalCacheStore, _options?: {
+        force?: boolean;
+    }): Promise<number>;
+    private ensureRestored;
+    /**
+     * Restore persisted state. A config-fingerprint mismatch keeps the
+     * restored entries usable (extracted with the previous configuration)
+     * and schedules a backfill instead of discarding them.
+     */
+    private restoreFromCache;
+}
+//# sourceMappingURL=DocumentSummaryStore.d.ts.map

package/dist/core/indexing/summary/DocumentSummaryStore.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"DocumentSummaryStore.d.ts","sourceRoot":"","sources":["../../../../src/core/indexing/summary/DocumentSummaryStore.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,QAAQ,EAAE,oBAAoB,EAAE,MAAM,aAAa,CAAC;AAClE,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,6BAA6B,CAAC;AACnE,OAAO,KAAK,EAAE,YAAY,EAAE,UAAU,EAAE,MAAM,0BAA0B,CAAC;AACzE,OAAO,KAAK,EAAE,wBAAwB,EAAE,MAAM,0CAA0C,CAAC;AACzF,OAAO,KAAK,EACV,oBAAoB,EACpB,qBAAqB,EAErB,aAAa,EACb,eAAe,EAEhB,MAAM,SAAS,CAAC;AAqBjB;;;;;;;;;;;GAWG;AACH,qBAAa,oBAAqB,YAAW,UAAU;IACrD,OAAO,CAAC,QAAQ,CAAC,EAAE,CAAW;IAC9B,OAAO,CAAC,MAAM,CAAwB;IACtC,OAAO,CAAC,iBAAiB,CAAS;IAClC;;;;OAIG;IACH,OAAO,CAAC,iBAAiB,CAAU;IACnC,4EAA4E;IAC5E,OAAO,CAAC,cAAc,CAAkB;IAExC,OAAO,CAAC,OAAO,CAAgD;IAC/D,OAAO,CAAC,MAAM,CAAqC;IAGnD,OAAO,CAAC,YAAY,CAA6B;IACjD,OAAO,CAAC,WAAW,CAAuB;IAC1C,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAgC;IAC5D,OAAO,CAAC,YAAY,CAA0B;IAC9C,OAAO,CAAC,SAAS,CAAkB;IACnC,OAAO,CAAC,cAAc,CAA8B;IACpD,OAAO,CAAC,QAAQ,CAAkB;IAGlC,OAAO,CAAC,aAAa,CAAkB;IACvC,OAAO,CAAC,cAAc,CAAqC;IAG3D,OAAO,CAAC,aAAa,CAA8B;gBAEvC,EAAE,EAAE,QAAQ,EAAE,MAAM,CAAC,EAAE,aAAa;IAWhD,SAAS,IAAI,qBAAqB;IAIlC,oBAAoB,IAAI,MAAM;IAI9B;;;;;;;;OAQG;IACH,SAAS,CAAC,MAAM,CAAC,EAAE,aAAa,GAAG,IAAI;IAKvC,sEAAsE;IACtE,OAAO,CAAC,WAAW;IAenB,OAAO,CAAC,gBAAgB;IAKxB;;;;;;;;;;OAUG;YACW,sBAAsB;IAiBpC;;;;;;OAMG;IACG,kBAAkB,IAAI,OAAO,CAAC,qBAAqB,CAAC;IAK1D;;;;OAIG;IACH,cAAc,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO;IAIrC;;;OAGG;IACH,WAAW,IAAI,eAAe;IAQ9B,QAAQ,CAAC,KAAK,EAAE,MAAM,GAAG,oBAAoB,GAAG,SAAS;IAIzD,aAAa,IAAI,gBAAgB,CAAC,oBAAoB,CAAC;IAIvD,OAAO,IAAI,MAAM;IAIjB,SAAS,IAAI,oBAAoB,GAAG,IAAI;IAQxC;;;;;;;;OAQG;IACG,MAAM,CAAC,OAAO,CAAC,EAAE,wBAAwB,GAAG,OAAO,CAAC,IAAI,CAAC;YAUjD,SAAS;IA2EvB,OAAO,CAAC,aAAa;IAuCrB;;;;;OAKG;IACH,cAAc,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI;IAOnC,kFAAkF;IAClF,KAAK,IAAI,IAAI;IAgBb;;;;;OAKG;IACH,WAAW,CAAC,YAAY,EAAE,YAAY,EAAE,WAAW,EAAE,MAAM,GAAG,IAAI;IAMlE,cAAc,IAAI,MAAM;IAIxB,aAAa,IAAI,OAAO;IAIxB,UAAU,IAAI,IAAI;IAKlB,OAAO,CAAC,cAAc;IAItB,OAAO,CAAC,eAAe;IAKjB,YAAY,CAAC,KAAK,EAAE,eAAe,EAAE,QAAQ,CAAC,EAAE;QAAE,KAAK,CAAC,EAAE,OAAO,CAAA;KAAE,GAAG,OAAO,CAAC,MAAM,CAAC;YA4C7E,cAAc;IAa5B;;;;OAIG;YACW,gBAAgB;CAwD/B"}

package/dist/core/indexing/summary/DocumentSummaryStore.js

@@ -0,0 +1,438 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DocumentSummaryStore = void 0;
+const types_1 = require("./types");
+const extractSummaryFields_1 = require("./extractSummaryFields");
+const DEFAULT_BUCKET_COUNT = 64;
+/** Simple deterministic string hash (djb2) used for bucket assignment. */
+function hashDocId(docId) {
+    let hash = 5381;
+    for (let i = 0; i < docId.length; i++) {
+        hash = ((hash << 5) + hash + docId.charCodeAt(i)) | 0;
+    }
+    return hash >>> 0;
+}
+/**
+ * The document summary buffer: a changefeed-maintained, per-document map of
+ * queryable field values (see docs/adhoc-queries.md).
+ *
+ * Ad-hoc queries and summary-backed views evaluate exclusively against this
+ * store, so they never pay document materialization. The store is kept
+ * up to date incrementally via `iterateChangesSince` (deleted/inaccessible
+ * documents arrive as lightweight tombstones and are removed), persists in
+ * encrypted buckets through the tenant's {@link LocalCacheStore}, and
+ * survives configuration changes with a resumable backfill instead of any
+ * document rewrite.
+ */
+class DocumentSummaryStore {
+    constructor(db, config) {
+        /** Whether the setup document was already consulted (once per instance). */
+        this.setupDocSeeded = false;
+        this.entries = new Map();
+        this.cursor = null;
+        // --- persistence state ---
+        this.cacheManager = null;
+        this.cachePrefix = null;
+        this.bucketCount = DEFAULT_BUCKET_COUNT;
+        this.dirtyBuckets = new Set();
+        this.metaDirty = false;
+        this.restorePromise = null;
+        this.restored = false;
+        // --- backfill state (config changed while entries already exist) ---
+        this.needsBackfill = false;
+        this.backfillCursor = null;
+        // --- single-flight update ---
+        this.updatePromise = null;
+        this.db = db;
+        this.hasExplicitConfig = config !== undefined;
+        this.config = (0, types_1.resolveSummaryConfig)(config);
+        this.configFingerprint = (0, types_1.computeSummaryConfigFingerprint)(this.config);
+    }
+    // ---------------------------------------------------------------------------
+    // Configuration
+    // ---------------------------------------------------------------------------
+    getConfig() {
+        return this.config;
+    }
+    getConfigFingerprint() {
+        return this.configFingerprint;
+    }
+    /**
+     * Replace the summary configuration. When the fingerprint changes and
+     * entries already exist, the store keeps serving the previous state and
+     * schedules a resumable backfill that re-extracts all documents with the
+     * new configuration on the next `update()` run.
+     *
+     * Calling this marks the configuration as explicit: the store stops
+     * following the {@link DB_SETUP_DOC_ID} document.
+     */
+    setConfig(config) {
+        this.hasExplicitConfig = true;
+        this.applyConfig(config);
+    }
+    /** Shared config-swap logic for explicit and setup-document paths. */
+    applyConfig(config) {
+        const resolved = (0, types_1.resolveSummaryConfig)(config);
+        const fingerprint = (0, types_1.computeSummaryConfigFingerprint)(resolved);
+        if (fingerprint === this.configFingerprint) {
+            return;
+        }
+        this.config = resolved;
+        this.configFingerprint = fingerprint;
+        if (this.entries.size > 0 || this.cursor !== null) {
+            this.scheduleBackfill();
+        }
+        this.metaDirty = true;
+        this.cacheManager?.markDirty();
+    }
+    scheduleBackfill() {
+        this.needsBackfill = true;
+        this.backfillCursor = null;
+    }
+    /**
+     * Adopt the configuration from the synced {@link DB_SETUP_DOC_ID}
+     * document (its `summarySetup` field) unless an explicit configuration
+     * was provided in code. Runs once per instance, BEFORE the persisted
+     * state is restored, so the fingerprint comparison on restore already
+     * sees the setup-document configuration (a stale persisted fingerprint
+     * then schedules the backfill exactly once).
+     *
+     * Later changes to the setup document — local edits or sync ingest —
+     * arrive through the changefeed and are applied in `applyDocument`.
+     */
+    async seedConfigFromSetupDoc() {
+        if (this.setupDocSeeded || this.hasExplicitConfig) {
+            this.setupDocSeeded = true;
+            return;
+        }
+        this.setupDocSeeded = true;
+        try {
+            const doc = await this.db.getDocument(types_1.DB_SETUP_DOC_ID);
+            const config = (0, types_1.sanitizeSummaryConfig)(doc.getData()[types_1.SUMMARY_SETUP_FIELD]);
+            if (config !== undefined) {
+                this.applyConfig(config);
+            }
+        }
+        catch {
+            // No setup document (or not readable) → keep the default config.
+        }
+    }
+    /**
+     * Make sure the effective configuration is settled: consults the
+     * {@link DB_SETUP_DOC_ID} document once (unless the config was provided
+     * in code) and returns the resolved configuration. Callers that make
+     * decisions based on coverage (e.g. the view data-provider factory)
+     * should await this before calling {@link isFieldCovered}.
+     */
+    async ensureConfigLoaded() {
+        await this.seedConfigFromSetupDoc();
+        return this.config;
+    }
+    /**
+     * Whether a field path can be answered from this summary (see
+     * {@link isFieldPathCovered}). Coverage is configuration-level; individual
+     * documents may still lack a value.
+     */
+    isFieldCovered(path) {
+        return (0, extractSummaryFields_1.isFieldPathCovered)(path, this.config);
+    }
+    /**
+     * `"full"` when all entries reflect the current configuration,
+     * `"rebuilding"` while a configuration-change backfill is in progress.
+     */
+    getCoverage() {
+        return this.needsBackfill ? "rebuilding" : "full";
+    }
+    // ---------------------------------------------------------------------------
+    // Reads
+    // ---------------------------------------------------------------------------
+    getEntry(docId) {
+        return this.entries.get(docId);
+    }
+    getAllEntries() {
+        return this.entries.values();
+    }
+    getSize() {
+        return this.entries.size;
+    }
+    getCursor() {
+        return this.cursor;
+    }
+    // ---------------------------------------------------------------------------
+    // Incremental update
+    // ---------------------------------------------------------------------------
+    /**
+     * Bring the summary up to date with the changefeed. Restores persisted
+     * state on first use, then consumes `iterateChangesSince` from the saved
+     * cursor and finally works down a pending configuration backfill.
+     *
+     * Accepts the same batching/progress/cancellation options as VirtualView
+     * updates; an interrupted run resumes from the saved cursors.
+     * Calls are single-flight: concurrent callers share one run.
+     */
+    async update(options) {
+        if (this.updatePromise) {
+            return this.updatePromise;
+        }
+        this.updatePromise = this.runUpdate(options).finally(() => {
+            this.updatePromise = null;
+        });
+        return this.updatePromise;
+    }
+    async runUpdate(options) {
+        await this.seedConfigFromSetupDoc();
+        await this.ensureRestored();
+        const applyBatchSize = options?.applyBatchSize ?? 100;
+        const onProgress = options?.onProgress;
+        const signal = options?.signal;
+        const countAfter = (cursor) => this.db.countChangesSince?.(cursor) ?? 0;
+        const total = onProgress
+            ? countAfter(this.cursor) + (this.needsBackfill ? countAfter(this.backfillCursor) : 0)
+            : 0;
+        let processed = 0;
+        let processedInBatch = 0;
+        // Returns true when the run should stop after the current batch.
+        const stopRequested = () => {
+            const callbackStop = onProgress?.({ processed, total, origin: "summary" }) === false;
+            return callbackStop || signal?.aborted === true;
+        };
+        if (signal?.aborted) {
+            return;
+        }
+        // Pass 1: incremental changefeed consumption from the main cursor.
+        for await (const { doc, cursor } of this.db.iterateChangesSince(this.cursor)) {
+            this.applyDocument(doc.getId(), doc, cursor);
+            this.cursor = cursor;
+            processed++;
+            processedInBatch++;
+            if (processedInBatch >= applyBatchSize) {
+                processedInBatch = 0;
+                this.cacheManager?.markDirty();
+                if (stopRequested()) {
+                    return;
+                }
+            }
+        }
+        // Pass 2: configuration backfill (re-extract everything with the new
+        // config). The feed yields each document's latest state once, so plain
+        // overwrites converge; docs changing mid-backfill are re-processed by
+        // the next pass 1 anyway.
+        if (this.needsBackfill) {
+            for await (const { doc, cursor } of this.db.iterateChangesSince(this.backfillCursor)) {
+                this.applyDocument(doc.getId(), doc, cursor);
+                this.backfillCursor = cursor;
+                processed++;
+                processedInBatch++;
+                if (processedInBatch >= applyBatchSize) {
+                    processedInBatch = 0;
+                    this.cacheManager?.markDirty();
+                    if (stopRequested()) {
+                        return;
+                    }
+                }
+            }
+            this.needsBackfill = false;
+            this.backfillCursor = null;
+            this.metaDirty = true;
+        }
+        this.cacheManager?.markDirty();
+        if (onProgress) {
+            onProgress({ processed, total, origin: "summary" });
+        }
+    }
+    applyDocument(docId, doc, cursor) {
+        if (docId === types_1.DB_SETUP_DOC_ID) {
+            // The setup document configures the summary instead of appearing in
+            // it. Config changes (also arriving via sync) schedule a backfill;
+            // a deleted setup document falls back to the default config.
+            if (!this.hasExplicitConfig) {
+                const config = doc.isDeleted()
+                    ? undefined
+                    : (0, types_1.sanitizeSummaryConfig)(doc.getData()[types_1.SUMMARY_SETUP_FIELD]);
+                this.applyConfig(config);
+            }
+            // Drop a stale entry left over from before the setup doc was skipped.
+            if (this.entries.delete(docId)) {
+                this.markBucketDirty(docId);
+            }
+            return;
+        }
+        if (doc.isDeleted()) {
+            if (this.entries.delete(docId)) {
+                this.markBucketDirty(docId);
+            }
+            return;
+        }
+        this.entries.set(docId, {
+            docId,
+            fields: (0, extractSummaryFields_1.extractSummaryFields)(doc.getData(), this.config),
+            lastModified: doc.getLastModified(),
+            changeSeq: cursor.changeSeq ?? 0,
+            decryptionKeyId: doc.getDecryptionKeyId(),
+        });
+        this.markBucketDirty(docId);
+    }
+    /**
+     * Drop a document's summary entry immediately (called from the DB's purge
+     * paths so plaintext field values never outlive key revocation/purges;
+     * the changefeed tombstone would remove it anyway, but only on the next
+     * update run).
+     */
+    removeDocument(docId) {
+        if (this.entries.delete(docId)) {
+            this.markBucketDirty(docId);
+            this.cacheManager?.markDirty();
+        }
+    }
+    /** Drop all entries and cursors (e.g. after the underlying store was cleared). */
+    reset() {
+        this.entries.clear();
+        this.cursor = null;
+        this.needsBackfill = false;
+        this.backfillCursor = null;
+        for (let i = 0; i < this.bucketCount; i++) {
+            this.dirtyBuckets.add(i);
+        }
+        this.metaDirty = true;
+        this.cacheManager?.markDirty();
+    }
+    // ---------------------------------------------------------------------------
+    // Persistence (ICacheable)
+    // ---------------------------------------------------------------------------
+    /**
+     * Attach cache persistence. `cachePrefix` scopes all records of this
+     * summary (recommended: `<dbCachePrefix>/summary`). Registers with the
+     * CacheManager for periodic flushing; the persisted state is restored
+     * lazily on the first `update()` call.
+     */
+    attachCache(cacheManager, cachePrefix) {
+        this.cacheManager = cacheManager;
+        this.cachePrefix = cachePrefix;
+        cacheManager.register(this);
+    }
+    getCachePrefix() {
+        return this.cachePrefix ?? "summary";
+    }
+    hasDirtyState() {
+        return this.dirtyBuckets.size > 0 || this.metaDirty;
+    }
+    clearDirty() {
+        this.dirtyBuckets.clear();
+        this.metaDirty = false;
+    }
+    bucketIndexFor(docId) {
+        return hashDocId(docId) % this.bucketCount;
+    }
+    markBucketDirty(docId) {
+        this.dirtyBuckets.add(this.bucketIndexFor(docId));
+        this.metaDirty = true;
+    }
+    async flushToCache(store, _options) {
+        const prefix = this.getCachePrefix();
+        let written = 0;
+        if (this.dirtyBuckets.size > 0) {
+            // Group entries by bucket once, then rewrite only dirty buckets.
+            const byBucket = new Map();
+            for (const entry of this.entries.values()) {
+                const bucket = this.bucketIndexFor(entry.docId);
+                if (!this.dirtyBuckets.has(bucket)) {
+                    continue;
+                }
+                let list = byBucket.get(bucket);
+                if (!list) {
+                    list = [];
+                    byBucket.set(bucket, list);
+                }
+                list.push(entry);
+            }
+            for (const bucket of this.dirtyBuckets) {
+                const payload = { entries: byBucket.get(bucket) ?? [] };
+                await store.put("summary", `${prefix}/bucket/${bucket}`, new TextEncoder().encode(JSON.stringify(payload)));
+                written++;
+            }
+        }
+        const meta = {
+            cursor: this.cursor,
+            configFingerprint: this.configFingerprint,
+            bucketCount: this.bucketCount,
+            needsBackfill: this.needsBackfill,
+            backfillCursor: this.backfillCursor,
+        };
+        await store.put("summary", `${prefix}/meta`, new TextEncoder().encode(JSON.stringify(meta)));
+        written++;
+        return written;
+    }
+    async ensureRestored() {
+        if (this.restored || !this.cacheManager) {
+            this.restored = true;
+            return;
+        }
+        if (!this.restorePromise) {
+            this.restorePromise = this.restoreFromCache().finally(() => {
+                this.restored = true;
+            });
+        }
+        return this.restorePromise;
+    }
+    /**
+     * Restore persisted state. A config-fingerprint mismatch keeps the
+     * restored entries usable (extracted with the previous configuration)
+     * and schedules a backfill instead of discarding them.
+     */
+    async restoreFromCache() {
+        const store = this.cacheManager?.getStore();
+        if (!store) {
+            return;
+        }
+        const prefix = this.getCachePrefix();
+        let meta;
+        try {
+            const metaBytes = await store.get("summary", `${prefix}/meta`);
+            if (!metaBytes) {
+                return;
+            }
+            meta = JSON.parse(new TextDecoder().decode(metaBytes));
+        }
+        catch {
+            return;
+        }
+        const bucketCount = meta.bucketCount ?? DEFAULT_BUCKET_COUNT;
+        const bucketIds = [];
+        for (let i = 0; i < bucketCount; i++) {
+            bucketIds.push(`${prefix}/bucket/${i}`);
+        }
+        try {
+            const buckets = await store.getMany("summary", bucketIds);
+            for (const bytes of buckets) {
+                if (!bytes) {
+                    continue;
+                }
+                const payload = JSON.parse(new TextDecoder().decode(bytes));
+                for (const entry of payload.entries ?? []) {
+                    this.entries.set(entry.docId, entry);
+                }
+            }
+        }
+        catch {
+            // A corrupt bucket only loses cached summaries; the changefeed
+            // rebuild below restores correctness.
+            this.entries.clear();
+            this.cursor = null;
+            return;
+        }
+        this.cursor = meta.cursor ?? null;
+        if (meta.configFingerprint !== this.configFingerprint) {
+            // Entries were extracted with a different configuration: keep them
+            // usable, re-extract everything in the background.
+            this.scheduleBackfill();
+            this.metaDirty = true;
+        }
+        else if (meta.needsBackfill) {
+            // Resume an interrupted backfill where it left off.
+            this.needsBackfill = true;
+            this.backfillCursor = meta.backfillCursor ?? null;
+        }
+    }
+}
+exports.DocumentSummaryStore = DocumentSummaryStore;
+//# sourceMappingURL=DocumentSummaryStore.js.map