@peerbit/document 13.0.44 → 13.1.1

package/dist/src/search.js

@@ -32,10 +32,11 @@ var __runInitializers = (this && this.__runInitializers) || function (thisArg, i
     }
     return useValue ? value : void 0;
 };
-import { field, getSchema, serialize, variant, } from "@dao-xyz/borsh";
+import { FixedArrayKind, field, getSchema, serialize, variant, } from "@dao-xyz/borsh";
 import { Cache } from "@peerbit/cache";
 import { PublicSignKey, sha256Base64Sync, } from "@peerbit/crypto";
 import * as types from "@peerbit/document-interface";
+import { tryProjectDocumentIndexSimple, } from "./native-rust.js";
 import { CachedIndex } from "@peerbit/indexer-cache";
 import * as indexerTypes from "@peerbit/indexer-interface";
 import { HashmapIndex } from "@peerbit/indexer-simple";
@@ -55,6 +56,7 @@ import { isPutOperation } from "./operation.js";
 import { Prefetch } from "./prefetch.js";
 import { initializeResultType, isResultIndexedValue, isResultValue, isResults, } from "./result-shape.js";
 import { ResumableIterators } from "./resumable-iterator.js";
+import { canPrepareDocumentTransformBeforeAppend, canPrepareDocumentTransformWithAppendFacts, documentTransformPreservesFieldPath, getDocumentTransformDescriptor, } from "./transform.js";
 const WARNING_WHEN_ITERATING_FOR_MORE_THAN = 1e5;
 const logger = loggerFn("peerbit:program:document:search");
 const warn = logger.newScope("warn");
@@ -64,6 +66,166 @@ const indexRpcLogger = documentIndexLogger.newScope("rpc");
 const indexCacheLogger = documentIndexLogger.newScope("cache");
 const indexPrefetchLogger = documentIndexLogger.newScope("prefetch");
 const indexIteratorLogger = documentIndexLogger.newScope("iterate");
+const isPromiseLike = (value) => !!value && typeof value.then === "function";
+const schemaVariant = (schema) => {
+    const variant = schema?.variant;
+    if (variant == null) {
+        return {};
+    }
+    if (typeof variant === "number") {
+        return { type: "u8", value: String(variant) };
+    }
+    if (typeof variant === "string") {
+        return { type: "string", value: variant };
+    }
+    return;
+};
+const schemaTypeName = (type) => {
+    if (typeof type === "string") {
+        switch (type) {
+            case "string":
+            case "u8":
+            case "u32":
+            case "u64":
+            case "bool":
+                return type;
+            default:
+                return;
+        }
+    }
+    if (type === Uint8Array) {
+        return "bytes";
+    }
+    if (type === PublicSignKey) {
+        return "publicsignkey";
+    }
+    if (type instanceof FixedArrayKind && type.elementType === "u8") {
+        return `fixedbytes:${type.length}`;
+    }
+    const kind = type;
+    if (kind.constructor?.name === "OptionKind") {
+        const element = schemaTypeName(kind.elementType);
+        return element ? `option:${element}` : undefined;
+    }
+    if (kind.constructor?.name === "VecKind") {
+        const element = schemaTypeName(kind.elementType);
+        return kind.sizeEncoding === "u32" && element
+            ? `vec:${element}`
+            : undefined;
+    }
+    return;
+};
+const schemaFieldPlan = (schema) => {
+    if (!schema?.fields) {
+        return;
+    }
+    const names = [];
+    const types = [];
+    for (const field of schema.fields) {
+        const type = schemaTypeName(field.type);
+        if (!type) {
+            return;
+        }
+        names.push(field.key);
+        types.push(type);
+    }
+    return { names, types };
+};
+const asSingleFieldPath = (path) => typeof path === "string" ? path : path.length === 1 ? path[0] : undefined;
+const createSimpleProjectionPlan = (documentSchema, indexedSchema, descriptor) => {
+    if (!descriptor || descriptor.kind === "identity") {
+        return;
+    }
+    const documentVariant = schemaVariant(documentSchema);
+    const outputVariant = schemaVariant(indexedSchema);
+    const documentFields = schemaFieldPlan(documentSchema);
+    const outputFields = schemaFieldPlan(indexedSchema);
+    if (!documentVariant || !outputVariant || !documentFields || !outputFields) {
+        return;
+    }
+    const sources = new Map();
+    if (descriptor.kind === "pick") {
+        for (const field of descriptor.fields) {
+            const name = asSingleFieldPath(field);
+            if (!name) {
+                return;
+            }
+            sources.set(name, { kind: "field", value: name });
+        }
+    }
+    else {
+        for (const field of descriptor.fields) {
+            const target = asSingleFieldPath(field.target);
+            if (!target) {
+                return;
+            }
+            switch (field.source.kind) {
+                case "field": {
+                    const source = asSingleFieldPath(field.source.path);
+                    if (!source) {
+                        return;
+                    }
+                    sources.set(target, { kind: "field", value: source });
+                    break;
+                }
+                case "context":
+                    sources.set(target, {
+                        kind: "context",
+                        value: field.source.field,
+                    });
+                    break;
+                case "entryFirstSignerPublicKey":
+                    sources.set(target, {
+                        kind: "entryFirstSignerPublicKey",
+                        value: "",
+                    });
+                    break;
+            }
+        }
+    }
+    const sourceKinds = [];
+    const sourceValues = [];
+    for (const field of outputFields.names) {
+        const source = sources.get(field);
+        if (!source) {
+            return;
+        }
+        sourceKinds.push(source.kind);
+        sourceValues.push(source.value);
+    }
+    return {
+        documentVariantType: documentVariant.type,
+        documentVariantValue: documentVariant.value,
+        documentFieldNames: documentFields.names,
+        documentFieldTypes: documentFields.types,
+        outputVariantType: outputVariant.type,
+        outputVariantValue: outputVariant.value,
+        outputFieldTypes: outputFields.types,
+        sourceKinds,
+        sourceValues,
+    };
+};
+const createSimpleFieldExtractionPlan = (documentSchema, path) => {
+    const fieldName = asSingleFieldPath(path);
+    if (!fieldName) {
+        return;
+    }
+    const documentVariant = schemaVariant(documentSchema);
+    const documentFields = schemaFieldPlan(documentSchema);
+    if (!documentVariant || !documentFields) {
+        return;
+    }
+    if (!documentFields.names.includes(fieldName)) {
+        return;
+    }
+    return {
+        documentVariantType: documentVariant.type,
+        documentVariantValue: documentVariant.value,
+        documentFieldNames: documentFields.names,
+        documentFieldTypes: documentFields.types,
+        fieldName,
+    };
+};
 const getRemoteQueryPriority = (remote) => typeof remote === "object" && remote.priority != null
     ? remote.priority
     : FOREGROUND_READ_MESSAGE_PRIORITY;
@@ -228,6 +390,42 @@ export const INDEX_CONTEXT_SHAPE = {
 const isTransformerWithFunction = (options) => {
     return options.transform != null;
 };
+const stripEncodedValue = (options) => options?.encodedValue || options?.encodedValueParts || options?.transformFacts
+    ? { replace: options.replace }
+    : options;
+const writeU32Le = (target, offset, value) => {
+    target[offset] = value & 0xff;
+    target[offset + 1] = (value >>> 8) & 0xff;
+    target[offset + 2] = (value >>> 16) & 0xff;
+    target[offset + 3] = (value >>> 24) & 0xff;
+    return offset + 4;
+};
+const writeU64Le = (target, offset, value) => {
+    let remaining = value;
+    for (let i = 0; i < 8; i++) {
+        target[offset + i] = Number(remaining & 0xffn);
+        remaining >>= 8n;
+    }
+    return offset + 8;
+};
+export const encodeContextSuffix = (context) => {
+    const head = fromString(context.head);
+    const gid = fromString(context.gid);
+    const encoded = new Uint8Array(1 + 8 + 8 + 4 + head.byteLength + 4 + gid.byteLength + 4);
+    let offset = 0;
+    // Context is @variant(0); keep this byte-for-byte aligned with Borsh.
+    encoded[offset++] = 0;
+    offset = writeU64Le(encoded, offset, context.created);
+    offset = writeU64Le(encoded, offset, context.modified);
+    offset = writeU32Le(encoded, offset, head.byteLength);
+    encoded.set(head, offset);
+    offset += head.byteLength;
+    offset = writeU32Le(encoded, offset, gid.byteLength);
+    encoded.set(gid, offset);
+    offset += gid.byteLength;
+    writeU32Le(encoded, offset, context.size);
+    return encoded;
+};
 export const coerceWithContext = (value, context) => {
     let valueWithContext = value;
     valueWithContext.__context = context;
@@ -238,6 +436,32 @@ export const coerceWithIndexed = (value, indexed) => {
     valueWithContext.__indexed = indexed;
     return valueWithContext;
 };
+export const coerceWithLazyIndexed = (value, getIndexable) => {
+    let cached;
+    let hasCached = false;
+    Object.defineProperty(value, "__indexed", {
+        configurable: true,
+        enumerable: true,
+        get() {
+            if (!hasCached) {
+                cached = getIndexable();
+                hasCached = true;
+                Object.defineProperty(value, "__indexed", {
+                    configurable: true,
+                    enumerable: true,
+                    writable: true,
+                    value: cached,
+                });
+            }
+            return cached;
+        },
+        set(indexed) {
+            cached = indexed;
+            hasCached = true;
+        },
+    });
+    return value;
+};
 let DocumentIndex = (() => {
     let _classDecorators = [variant("documents_index")];
     let _classDescriptor;
@@ -263,6 +487,10 @@ let DocumentIndex = (() => {
         documentType = __runInitializers(this, __query_extraInitializers);
         // transform options
         transformer;
+        transformerIsIdentity = false;
+        nativeTransformDescriptor;
+        nativeTransformProjectionPlan;
+        nativeBackboneDocumentProjection;
         // The indexed document wrapped in a context
         wrappedIndexedType;
         indexedType;
@@ -276,6 +504,7 @@ let DocumentIndex = (() => {
         _resumableIterators;
         _prefetch;
         includeIndexed = undefined;
+        immutable = false;
         compatibility;
         // Transformation, indexer
         /* fields: IndexableFields<T, I>; */
@@ -292,9 +521,19 @@ let DocumentIndex = (() => {
         _joinListener;
         _resultQueue;
         iteratorKeepAliveTimers;
+        deleteResolvedCacheForKey(key) {
+            if (this.isProgramValued) {
+                this._resolverProgramCache.delete(key.primitive);
+                indexCacheLogger("cache:del:program", { id: key.primitive });
+            }
+            else if (this._resolverCache?.del(key.primitive)) {
+                indexCacheLogger("cache:del:value", { id: key.primitive });
+            }
+        }
         constructor(properties) {
             super();
             this._query = properties?.query || new RPC();
+            this._resultQueue = new Map();
             this.iteratorKeepAliveTimers = new Map();
         }
         get valueEncoding() {
@@ -407,7 +646,11 @@ let DocumentIndex = (() => {
             }
             return results;
         }
-        handleDocumentChange = async (event) => {
+        // Bound in open(). Deserialized instances skip constructor/field initializers
+        // (borsh creates objects via Object.create), so this must not rely on a field
+        // initializer to exist.
+        handleDocumentChange;
+        async onDocumentChange(event) {
             const added = event.detail.added;
             if (!added.length) {
                 return;
@@ -474,7 +717,7 @@ let DocumentIndex = (() => {
                     queue.pushInFlight = false;
                 }
             }
-        };
+        }
         get nestedProperties() {
             return {
                 match: (obj) => obj instanceof this.dbType,
@@ -511,6 +754,7 @@ let DocumentIndex = (() => {
             this.canRead = properties.canRead;
             this.canSearch = properties.canSearch;
             this.includeIndexed = properties.includeIndexed;
+            this.immutable = properties.immutable ?? false;
             let IndexedClassWithContext = (() => {
                 let _classDecorators = [variant(0)];
                 let _classDescriptor;
@@ -567,9 +811,19 @@ let DocumentIndex = (() => {
                 return replicateFn(rq, rs);
             };
             const transformOptions = properties.transform;
+            const hasTransformFunction = transformOptions != null && isTransformerWithFunction(transformOptions);
+            this.nativeTransformDescriptor = hasTransformFunction
+                ? getDocumentTransformDescriptor(transformOptions.transform)
+                : undefined;
+            this.nativeTransformProjectionPlan = createSimpleProjectionPlan(getSchema(this.documentType), indexedSchema, this.nativeTransformDescriptor);
+            this.transformerIsIdentity =
+                transformOptions == null ||
+                    (!hasTransformFunction && transformOptions.type == null) ||
+                    (this.nativeTransformDescriptor?.kind === "identity" &&
+                        this.indexedTypeIsDocumentType);
             this.transformer = transformOptions
-                ? isTransformerWithFunction(transformOptions)
-                    ? (obj, context) => transformOptions.transform(obj, context)
+                ? hasTransformFunction
+                    ? (obj, context, facts) => transformOptions.transform(obj, context, facts)
                     : transformOptions.type
                         ? (obj, context) => new transformOptions.type(obj, context)
                         : (obj) => obj
@@ -659,9 +913,213 @@ let DocumentIndex = (() => {
                 responseType: types.AbstractSearchResult,
                 queryType: types.AbstractSearchRequest,
             });
-            if (this.handleDocumentChange) {
-                this.documentEvents.addEventListener("change", this.handleDocumentChange);
+            this.handleDocumentChange ??= (event) => this.onDocumentChange(event);
+            this.documentEvents.addEventListener("change", this.handleDocumentChange);
+        }
+        attachNativeBackboneDocumentIndex(backbone, options) {
+            this.nativeBackboneDocumentProjection = undefined;
+            if (!backbone ||
+                this.isProgramValued ||
+                !this.canUseNativeBackboneDocumentIndex()) {
+                return false;
+            }
+            const attach = this.index
+                .attachNativeBackboneDocumentIndex;
+            const attached = typeof attach === "function" &&
+                attach.call(this.index, backbone, options) === true;
+            if (attached) {
+                const projection = backbone;
+                if (typeof projection.projectDocumentIndexSimple === "function") {
+                    this.nativeBackboneDocumentProjection = projection;
+                }
+            }
+            return attached;
+        }
+        canUseNativeBackboneDocumentIndex() {
+            return ((this.transformerIsIdentity && this.indexedTypeIsDocumentType) ||
+                this.nativeTransformDescriptor != null);
+        }
+        getNativeDocumentFieldExtractionPlan(path) {
+            return createSimpleFieldExtractionPlan(getSchema(this.documentType), path);
+        }
+        canPrepareNativeBackboneDocumentIndexCommit() {
+            return ((this.transformerIsIdentity && this.indexedTypeIsDocumentType) ||
+                canPrepareDocumentTransformBeforeAppend(this.nativeTransformDescriptor));
+        }
+        canPrepareNativeBackboneDocumentIndexCommitWithAppendFacts() {
+            return (this.canPrepareNativeBackboneDocumentIndexCommit() ||
+                !!this.nativeTransformProjectionPlan ||
+                canPrepareDocumentTransformWithAppendFacts(this.nativeTransformDescriptor));
+        }
+        canUseNativeBackboneContextualBatch() {
+            return (!this.isProgramValued &&
+                typeof this.index.putWithContextBatch ===
+                    "function" &&
+                ((this.transformerIsIdentity && this.indexedTypeIsDocumentType) ||
+                    this.canPrepareNativeBackboneDocumentIndexCommitWithAppendFacts()));
+        }
+        prepareNativeBackboneDocumentIndexCommit(value, encodedDocument, transformFacts) {
+            if (this.transformerIsIdentity && this.indexedTypeIsDocumentType) {
+                return {
+                    valuePrefixBytes: encodedDocument,
+                    usePlainPutPayload: true,
+                    indexable: value,
+                };
+            }
+            if (this.nativeTransformProjectionPlan) {
+                let projectionContext;
+                let cached;
+                let hasCached = false;
+                return {
+                    projection: {
+                        encodedDocument,
+                        plan: this.nativeTransformProjectionPlan,
+                        signer: transformFacts?.entryPublicKeys?.[0]?.bytes,
+                    },
+                    getIndexable: () => {
+                        if (!hasCached) {
+                            const transformed = this.transformer(value, projectionContext, transformFacts);
+                            if (isPromiseLike(transformed)) {
+                                throw new Error("Native descriptor transform unexpectedly returned a promise");
+                            }
+                            cached = transformed;
+                            hasCached = true;
+                        }
+                        return cached;
+                    },
+                    setContext: (context) => {
+                        projectionContext = context;
+                        hasCached = false;
+                        cached = undefined;
+                    },
+                };
+            }
+            if (!canPrepareDocumentTransformBeforeAppend(this.nativeTransformDescriptor)) {
+                return;
+            }
+            const transformed = this.transformer(value, undefined, transformFacts);
+            const finish = (indexable) => ({
+                valuePrefixBytes: serialize(this.asIndexedTypeValue(indexable)),
+                indexable,
+            });
+            return isPromiseLike(transformed)
+                ? transformed.then(finish)
+                : finish(transformed);
+        }
+        prepareNativeBackboneDocumentIndexCommitWithAppendFacts(value, encodedDocument, context, transformFacts) {
+            if (this.transformerIsIdentity && this.indexedTypeIsDocumentType) {
+                return {
+                    valuePrefixBytes: encodedDocument,
+                    usePlainPutPayload: true,
+                    indexable: value,
+                };
+            }
+            if (this.nativeTransformProjectionPlan) {
+                let projectionContext = {
+                    created: context.created,
+                    modified: context.modified,
+                    head: context.head,
+                    gid: context.gid,
+                    size: context.size,
+                    signer: transformFacts?.entryPublicKeys?.[0]?.bytes,
+                };
+                let cached;
+                let hasCached = false;
+                return {
+                    projection: {
+                        encodedDocument,
+                        plan: this.nativeTransformProjectionPlan,
+                        signer: projectionContext.signer,
+                    },
+                    getIndexable: () => {
+                        if (!hasCached) {
+                            const transformed = this.transformer(value, projectionContext, transformFacts);
+                            if (isPromiseLike(transformed)) {
+                                throw new Error("Native descriptor transform unexpectedly returned a promise");
+                            }
+                            cached = transformed;
+                            hasCached = true;
+                        }
+                        return cached;
+                    },
+                    setContext: (nextContext) => {
+                        projectionContext = {
+                            created: nextContext.created,
+                            modified: nextContext.modified,
+                            head: nextContext.head,
+                            gid: nextContext.gid,
+                            size: nextContext.size,
+                            signer: transformFacts?.entryPublicKeys?.[0]?.bytes,
+                        };
+                        hasCached = false;
+                        cached = undefined;
+                    },
+                };
+            }
+            if (!canPrepareDocumentTransformWithAppendFacts(this.nativeTransformDescriptor) &&
+                !canPrepareDocumentTransformBeforeAppend(this.nativeTransformDescriptor)) {
+                return;
+            }
+            const transformed = this.transformer(value, context, transformFacts);
+            if (isPromiseLike(transformed)) {
+                return;
             }
+            const indexable = transformed;
+            return {
+                valuePrefixBytes: serialize(this.asIndexedTypeValue(indexable)),
+                indexable,
+            };
+        }
+        prepareNativeBackboneDocumentIndexStoredCommitWithAppendFacts(encodedDocument, context, transformFacts) {
+            if (this.transformerIsIdentity && this.indexedTypeIsDocumentType) {
+                return {
+                    valuePrefixBytes: encodedDocument,
+                    usePlainPutPayload: true,
+                };
+            }
+            if (this.nativeTransformProjectionPlan) {
+                return {
+                    projection: {
+                        encodedDocument,
+                        plan: this.nativeTransformProjectionPlan,
+                        signer: transformFacts?.entryPublicKeys?.[0]?.bytes,
+                    },
+                };
+            }
+            if (!canPrepareDocumentTransformWithAppendFacts(this.nativeTransformDescriptor) &&
+                !canPrepareDocumentTransformBeforeAppend(this.nativeTransformDescriptor)) {
+                return;
+            }
+            return;
+        }
+        nativeBackboneDocumentIndexValuePrefixBytes(nativeDocumentIndex, context) {
+            return (nativeDocumentIndex.valuePrefixBytes ??
+                (nativeDocumentIndex.projection
+                    ? (this.nativeBackboneDocumentProjection?.projectDocumentIndexSimple?.(nativeDocumentIndex.projection.encodedDocument, nativeDocumentIndex.projection.plan, {
+                        created: context.created,
+                        modified: context.modified,
+                        head: context.head,
+                        gid: context.gid,
+                        size: context.size,
+                        signer: nativeDocumentIndex.projection.signer,
+                    }) ??
+                        tryProjectDocumentIndexSimple(nativeDocumentIndex.projection.encodedDocument, nativeDocumentIndex.projection.plan, {
+                            created: context.created,
+                            modified: context.modified,
+                            head: context.head,
+                            gid: context.gid,
+                            size: context.size,
+                            signer: nativeDocumentIndex.projection.signer,
+                        }))
+                    : undefined));
+        }
+        asIndexedTypeValue(value) {
+            if (value &&
+                Object.getPrototypeOf(value) ===
+                    this.indexedType.prototype) {
+                return value;
+            }
+            return Object.assign(Object.create(this.indexedType.prototype), value);
         }
         get prefetch() {
             return this._prefetch;
@@ -818,11 +1276,11 @@ let DocumentIndex = (() => {
                 if (this._joinListener) {
                     this._query.events.removeEventListener("join", this._joinListener);
                 }
-                if (this.handleDocumentChange) {
+                if (this.handleDocumentChange && this.documentEvents) {
                     this.documentEvents.removeEventListener("change", this.handleDocumentChange);
                 }
                 this.clearAllResultQueues();
-                await this._resumableIterators.clearAll();
+                await this._resumableIterators?.clearAll();
                 if (this.iteratorKeepAliveTimers) {
                     for (const timer of this.iteratorKeepAliveTimers.values()) {
                         clearTimeout(timer);
@@ -846,9 +1304,9 @@ let DocumentIndex = (() => {
         async drop(from) {
             const dropped = await super.drop(from);
             if (dropped) {
-                this.documentEvents.removeEventListener("change", this.handleDocumentChange);
+                this.documentEvents?.removeEventListener("change", this.handleDocumentChange);
                 this.clearAllResultQueues();
-                await this._resumableIterators.clearAll();
+                await this._resumableIterators?.clearAll();
                 if (this.iteratorKeepAliveTimers) {
                     for (const timer of this.iteratorKeepAliveTimers.values()) {
                         clearTimeout(timer);
@@ -977,6 +1435,426 @@ let DocumentIndex = (() => {
             await iterator.close();
             return one[0];
         }
+        async getIdentityIndexedByHead(head) {
+            if (!this.canGetIdentityIndexedByHead()) {
+                return;
+            }
+            return this.index.getByContextHead?.(head);
+        }
+        async getIdentityIndexedKeyByHead(head) {
+            const key = this.getIndexedKeyByHead(head);
+            if (key) {
+                return key;
+            }
+            const indexed = await this.getIdentityIndexedByHead(head);
+            return indexed?.id;
+        }
+        getIndexedKeyByHead(head) {
+            const getIdByHead = this.index.getIdByContextHead;
+            return typeof getIdByHead === "function"
+                ? getIdByHead.call(this.index, head)
+                : undefined;
+        }
+        getIndexedKeysByHeads(heads) {
+            const getIdByHead = this.index.getIdByContextHead;
+            if (typeof getIdByHead !== "function") {
+                return;
+            }
+            return heads.map((head) => getIdByHead.call(this.index, head));
+        }
+        tryGetIdentityIndexedKeyByHead(head) {
+            const getIdByHead = this.index.getIdByContextHead;
+            if (typeof getIdByHead !== "function") {
+                return { supported: false };
+            }
+            return {
+                supported: true,
+                key: getIdByHead.call(this.index, head),
+            };
+        }
+        async getIdentityIndexedByHeads(heads) {
+            if (!this.canGetIdentityIndexedByHead()) {
+                return;
+            }
+            const batch = this.index.getByContextHeadBatch;
+            if (batch) {
+                return batch.call(this.index, heads);
+            }
+            return Promise.all(heads.map((head) => this.getIdentityIndexedByHead(head)));
+        }
+        canGetIdentityIndexedByHead() {
+            return (this.transformerIsIdentity &&
+                this.indexedTypeIsDocumentType &&
+                !this.isProgramValued &&
+                typeof this.index.getByContextHead === "function");
+        }
+        canGetIndexedKeyByHead() {
+            return (!this.isProgramValued &&
+                typeof this.index.getIdByContextHead ===
+                    "function");
+        }
+        canReadOriginalFieldPathsFromIndexedValue(paths) {
+            return (!this.isProgramValued &&
+                paths.every((path) => this.transformerIsIdentity && this.indexedTypeIsDocumentType
+                    ? true
+                    : documentTransformPreservesFieldPath(this.nativeTransformDescriptor, path)));
+        }
+        canReadNativeIndexedFieldValues(paths) {
+            return (this.canReadOriginalFieldPathsFromIndexedValue(paths) &&
+                typeof this.index.getNativeIndexedFieldValue === "function");
+        }
+        getNativeIndexedFieldValue(id, path) {
+            const read = this.index.getNativeIndexedFieldValue;
+            if (typeof read !== "function") {
+                return undefined;
+            }
+            return read.call(this.index, id, typeof path === "string" ? [path] : path);
+        }
+        _putIdentityWithContext(value, id, context, options) {
+            const contextualPut = this.transformerIsIdentity
+                ? this.index.putWithContext
+                : undefined;
+            if (!contextualPut || this.isProgramValued) {
+                return;
+            }
+            const indexable = value;
+            const indexedValue = coerceWithIndexed(coerceWithContext(value, context), indexable);
+            this.cacheResolvedValue(id.primitive, value);
+            const handleError = (error) => {
+                if (error instanceof indexerTypes.NotStartedError && this.closed) {
+                    return indexedValue;
+                }
+                throw error;
+            };
+            try {
+                const putResult = contextualPut.call(this.index, indexable, id, context, this.withContextualEncodedValue(options, context));
+                return isPromiseLike(putResult)
+                    ? putResult.then(() => indexedValue, handleError)
+                    : indexedValue;
+            }
+            catch (error) {
+                return handleError(error);
+            }
+        }
+        _putStoredIdentityWithContext(value, id, context, encodedValueParts, options) {
+            const contextualStoredPut = this.transformerIsIdentity
+                ? this.index.putStoredContextualEncodedValue
+                : undefined;
+            if (!contextualStoredPut ||
+                this.isProgramValued ||
+                !this.indexedTypeIsDocumentType) {
+                return;
+            }
+            const indexable = value;
+            const indexedValue = coerceWithIndexed(coerceWithContext(value, context), indexable);
+            this.cacheResolvedValue(id.primitive, value);
+            const handleError = (error) => {
+                if (error instanceof indexerTypes.NotStartedError && this.closed) {
+                    return indexedValue;
+                }
+                throw error;
+            };
+            try {
+                const putResult = contextualStoredPut.call(this.index, id, encodedValueParts, options);
+                if (putResult === false) {
+                    return;
+                }
+                return isPromiseLike(putResult)
+                    ? putResult.then(() => indexedValue, handleError)
+                    : indexedValue;
+            }
+            catch (error) {
+                return handleError(error);
+            }
+        }
+        _putPreparedNativeBackboneDocumentIndexWithContext(value, id, context, nativeDocumentIndex, options) {
+            const contextualStoredPut = this.index
+                .putStoredContextualEncodedValue;
+            if (!contextualStoredPut || this.isProgramValued) {
+                return;
+            }
+            nativeDocumentIndex.setContext?.(context);
+            const valueWithContext = coerceWithContext(value, context);
+            const indexedValue = nativeDocumentIndex.indexable
+                ? coerceWithIndexed(valueWithContext, nativeDocumentIndex.indexable)
+                : nativeDocumentIndex.getIndexable
+                    ? coerceWithLazyIndexed(valueWithContext, nativeDocumentIndex.getIndexable)
+                    : undefined;
+            if (!indexedValue) {
+                return;
+            }
+            this.cacheResolvedValue(id.primitive, value);
+            const valuePrefixBytes = this.nativeBackboneDocumentIndexValuePrefixBytes(nativeDocumentIndex, context);
+            if (!valuePrefixBytes) {
+                return;
+            }
+            const encodedValueParts = {
+                prefix: valuePrefixBytes,
+                suffix: encodeContextSuffix(context),
+            };
+            const handleError = (error) => {
+                if (error instanceof indexerTypes.NotStartedError && this.closed) {
+                    return indexedValue;
+                }
+                throw error;
+            };
+            try {
+                const putResult = contextualStoredPut.call(this.index, id, encodedValueParts, options);
+                if (putResult === false) {
+                    return;
+                }
+                return isPromiseLike(putResult)
+                    ? putResult.then(() => indexedValue, handleError)
+                    : indexedValue;
+            }
+            catch (error) {
+                return handleError(error);
+            }
+        }
+        _putPreparedNativeBackboneDocumentIndexStoredWithContext(id, context, nativeDocumentIndex, options) {
+            const contextualStoredPut = this.index
+                .putStoredContextualEncodedValue;
+            if (!contextualStoredPut || this.isProgramValued) {
+                return;
+            }
+            nativeDocumentIndex.setContext?.(context);
+            const valuePrefixBytes = this.nativeBackboneDocumentIndexValuePrefixBytes(nativeDocumentIndex, context);
+            if (!valuePrefixBytes) {
+                return;
+            }
+            const encodedValueParts = {
+                prefix: valuePrefixBytes,
+                suffix: encodeContextSuffix(context),
+            };
+            const handleError = (error) => {
+                if (error instanceof indexerTypes.NotStartedError && this.closed) {
+                    return true;
+                }
+                throw error;
+            };
+            try {
+                const putResult = contextualStoredPut.call(this.index, id, encodedValueParts, options);
+                if (putResult === false) {
+                    return false;
+                }
+                return isPromiseLike(putResult)
+                    ? putResult.then(() => true, handleError)
+                    : true;
+            }
+            catch (error) {
+                return handleError(error);
+            }
+        }
+        _persistPreparedNativeBackboneDocumentIndexStoredWithContext(id, context, nativeDocumentIndex, encodedValueParts, options) {
+            const persistStoredPut = this.index
+                .persistStoredContextualEncodedValue;
+            if (!persistStoredPut || this.isProgramValued) {
+                return;
+            }
+            let storedParts;
+            if (this.transformerIsIdentity &&
+                this.indexedTypeIsDocumentType &&
+                encodedValueParts) {
+                storedParts = encodedValueParts;
+            }
+            else if (nativeDocumentIndex) {
+                nativeDocumentIndex.setContext?.(context);
+                const valuePrefixBytes = nativeDocumentIndex.valuePrefixBytes ??
+                    this.nativeBackboneDocumentIndexValuePrefixBytes(nativeDocumentIndex, context);
+                if (!valuePrefixBytes) {
+                    return;
+                }
+                storedParts = {
+                    prefix: valuePrefixBytes,
+                    suffix: encodeContextSuffix(context),
+                };
+            }
+            else {
+                return;
+            }
+            try {
+                const persistResult = persistStoredPut.call(this.index, id, storedParts, options);
+                if (persistResult === false) {
+                    return false;
+                }
+                return isPromiseLike(persistResult)
+                    ? persistResult.then(() => true, (error) => {
+                        if (error instanceof indexerTypes.NotStartedError && this.closed) {
+                            return true;
+                        }
+                        throw error;
+                    })
+                    : true;
+            }
+            catch (error) {
+                if (error instanceof indexerTypes.NotStartedError && this.closed) {
+                    return true;
+                }
+                throw error;
+            }
+        }
+        async _putManyPreparedNativeBackboneDocumentIndexWithContext(values) {
+            if (values.length === 0) {
+                return [];
+            }
+            const contextualBatchPut = this.index
+                .putWithContextBatch;
+            if (!contextualBatchPut || this.isProgramValued) {
+                return;
+            }
+            const indexedValues = [];
+            const batchValues = [];
+            for (const item of values) {
+                if (!item.nativeDocumentIndex) {
+                    return;
+                }
+                item.nativeDocumentIndex.setContext?.(item.context);
+                const valueWithContext = coerceWithContext(item.value, item.context);
+                const indexedValue = item.nativeDocumentIndex.indexable
+                    ? coerceWithIndexed(valueWithContext, item.nativeDocumentIndex.indexable)
+                    : item.nativeDocumentIndex.getIndexable
+                        ? coerceWithLazyIndexed(valueWithContext, item.nativeDocumentIndex.getIndexable)
+                        : undefined;
+                if (!indexedValue) {
+                    return;
+                }
+                const valuePrefixBytes = this.nativeBackboneDocumentIndexValuePrefixBytes(item.nativeDocumentIndex, item.context);
+                if (!valuePrefixBytes) {
+                    return;
+                }
+                this.cacheResolvedValue(item.id.primitive, item.value);
+                indexedValues.push(indexedValue);
+                batchValues.push({
+                    // Encoded native batches store from encodedValueParts; descriptor
+                    // projections keep the JS indexable lazy for event consumers.
+                    value: item.nativeDocumentIndex.indexable ?? undefined,
+                    id: item.id,
+                    context: item.context,
+                    options: {
+                        replace: item.options?.replace,
+                        encodedValueParts: {
+                            prefix: valuePrefixBytes,
+                            suffix: encodeContextSuffix(item.context),
+                        },
+                    },
+                });
+            }
+            const handleError = (error) => {
+                if (error instanceof indexerTypes.NotStartedError && this.closed) {
+                    return indexedValues;
+                }
+                throw error;
+            };
+            try {
+                const putResult = contextualBatchPut.call(this.index, batchValues);
+                return isPromiseLike(putResult)
+                    ? putResult.then(() => indexedValues, handleError)
+                    : indexedValues;
+            }
+            catch (error) {
+                return handleError(error);
+            }
+        }
+        async _putManyPreparedNativeBackboneDocumentIndexStored(values) {
+            if (values.length === 0) {
+                return true;
+            }
+            if (this.isProgramValued) {
+                return;
+            }
+            const storedBatchPut = this.index
+                .putStoredContextualEncodedValueBatch;
+            if (!storedBatchPut) {
+                return;
+            }
+            const batchValues = [];
+            for (const item of values) {
+                let encodedValueParts;
+                if (this.transformerIsIdentity &&
+                    this.indexedTypeIsDocumentType &&
+                    item.encodedValueParts) {
+                    encodedValueParts = item.encodedValueParts;
+                }
+                else if (item.nativeDocumentIndex) {
+                    item.nativeDocumentIndex.setContext?.(item.context);
+                    const valuePrefixBytes = item.nativeDocumentIndex.valuePrefixBytes ??
+                        this.nativeBackboneDocumentIndexValuePrefixBytes(item.nativeDocumentIndex, item.context);
+                    if (!valuePrefixBytes) {
+                        return;
+                    }
+                    encodedValueParts = {
+                        prefix: valuePrefixBytes,
+                        suffix: encodeContextSuffix(item.context),
+                    };
+                }
+                else {
+                    return;
+                }
+                this.cacheResolvedValue(item.id.primitive, item.value);
+                batchValues.push({
+                    id: item.id,
+                    encodedValueParts,
+                    options: item.options,
+                });
+            }
+            const handleError = (error) => {
+                if (error instanceof indexerTypes.NotStartedError && this.closed) {
+                    return true;
+                }
+                throw error;
+            };
+            try {
+                return await storedBatchPut.call(this.index, batchValues);
+            }
+            catch (error) {
+                return handleError(error);
+            }
+        }
+        async _putManyIdentityWithContext(values) {
+            if (values.length === 0) {
+                return [];
+            }
+            const contextualPut = this.transformerIsIdentity
+                ? this.index.putWithContext
+                : undefined;
+            const contextualBatchPut = this.transformerIsIdentity
+                ? this.index.putWithContextBatch
+                : undefined;
+            if ((!contextualBatchPut && !contextualPut) || this.isProgramValued) {
+                return;
+            }
+            const indexedValues = values.map((item) => {
+                const indexable = item.value;
+                this.cacheResolvedValue(item.id.primitive, item.value);
+                return {
+                    indexable,
+                    value: coerceWithIndexed(coerceWithContext(item.value, item.context), indexable),
+                };
+            });
+            try {
+                if (contextualBatchPut) {
+                    await contextualBatchPut.call(this.index, values.map((item, index) => ({
+                        value: indexedValues[index].indexable,
+                        id: item.id,
+                        context: item.context,
+                        options: this.withContextualEncodedValue(item.options, item.context),
+                    })));
+                }
+                else {
+                    for (let i = 0; i < values.length; i++) {
+                        const item = values[i];
+                        await contextualPut.call(this.index, indexedValues[i].indexable, item.id, item.context, this.withContextualEncodedValue(item.options, item.context));
+                    }
+                }
+            }
+            catch (error) {
+                if (error instanceof indexerTypes.NotStartedError && this.closed) {
+                    return indexedValues.map((item) => item.value);
+                }
+                throw error;
+            }
+            return indexedValues.map((item) => item.value);
+        }
         async put(value, id, entry, existing) {
             const existingDefined = existing === undefined
                 ? await this.index.get(id, {
@@ -993,31 +1871,33 @@ let DocumentIndex = (() => {
             });
             return this.putWithContext(value, id, context, {
                 replace: existingDefined != null,
+                transformFacts: { entryPublicKeys: entry.publicKeys },
             });
         }
         async putWithContext(value, id, context, options) {
             const idString = id.primitive;
-            if (this.isProgramValued /*
-            TODO should we skip caching program value if they are not openend through this db?
-            &&
-            (value as Program).closed === false &&
-            (value as Program).parents.includes(this._log) */) {
-                // TODO make last condition more efficient if there are many docs
-                this._resolverProgramCache.set(idString, value);
-                indexCacheLogger("cache:set:program", { id: idString });
-            }
-            else {
-                if (this._resolverCache) {
-                    this._resolverCache.add(idString, value);
-                    indexCacheLogger("cache:set:value", { id: idString });
-                }
-            }
-            const valueToIndex = await this.transformer(value, context);
-            const wrappedValueToIndex = new this.wrappedIndexedType(valueToIndex, context);
+            this.cacheResolvedValue(idString, value);
+            const valueToIndex = this.transformerIsIdentity
+                ? value
+                : await this.transformer(value, context, options?.transformFacts);
             coerceWithIndexed(value, valueToIndex);
             coerceWithContext(value, context);
             try {
-                await this.index.put(wrappedValueToIndex, undefined, options);
+                const contextualPut = this.transformerIsIdentity
+                    ? this.index.putWithContext
+                    : undefined;
+                if (contextualPut) {
+                    const encodedValueParts = this.encodeContextualIndexedValueParts(options?.encodedValue, context);
+                    await contextualPut.call(this.index, valueToIndex, id, context, encodedValueParts
+                        ? { ...options, encodedValue: undefined, encodedValueParts }
+                        : options?.encodedValue
+                            ? { ...options, encodedValue: undefined }
+                            : options);
+                }
+                else {
+                    const wrappedValueToIndex = new this.wrappedIndexedType(valueToIndex, context);
+                    await this.index.put(wrappedValueToIndex, id, stripEncodedValue(options));
+                }
             }
             catch (error) {
                 if (error instanceof indexerTypes.NotStartedError && this.closed) {
@@ -1027,20 +1907,157 @@ let DocumentIndex = (() => {
             }
             return { context, indexable: valueToIndex };
         }
-        del(key) {
-            if (this.isProgramValued) {
-                this._resolverProgramCache.delete(key.primitive);
-                indexCacheLogger("cache:del:program", { id: key.primitive });
+        async putManyWithContext(values) {
+            if (values.length === 0) {
+                return [];
+            }
+            let transformed;
+            if (this.transformerIsIdentity) {
+                transformed = new Array(values.length);
+                for (let i = 0; i < values.length; i++) {
+                    const item = values[i];
+                    this.cacheResolvedValue(item.id.primitive, item.value);
+                    const indexable = item.value;
+                    coerceWithIndexed(item.value, indexable);
+                    coerceWithContext(item.value, item.context);
+                    transformed[i] = { ...item, indexable };
+                }
             }
             else {
-                if (this._resolverCache?.del(key.primitive)) {
-                    indexCacheLogger("cache:del:value", { id: key.primitive });
+                transformed = await Promise.all(values.map(async (item) => {
+                    this.cacheResolvedValue(item.id.primitive, item.value);
+                    const indexable = await this.transformer(item.value, item.context);
+                    coerceWithIndexed(item.value, indexable);
+                    coerceWithContext(item.value, item.context);
+                    return { ...item, indexable };
+                }));
+            }
+            try {
+                const contextualBatchPut = this.transformerIsIdentity
+                    ? this.index.putWithContextBatch
+                    : undefined;
+                if (contextualBatchPut) {
+                    await contextualBatchPut.call(this.index, transformed.map((item) => ({
+                        value: item.indexable,
+                        id: item.id,
+                        context: item.context,
+                        options: this.withContextualEncodedValue(item.options, item.context),
+                    })));
+                }
+                else if (transformed.every((item) => item.options?.replace !== true) &&
+                    this.index.putBatch) {
+                    await this.index.putBatch(transformed.map((item) => new this.wrappedIndexedType(item.indexable, item.context)));
+                }
+                else {
+                    const contextualPut = this.transformerIsIdentity
+                        ? this.index.putWithContext
+                        : undefined;
+                    for (const item of transformed) {
+                        if (contextualPut) {
+                            await contextualPut.call(this.index, item.indexable, item.id, item.context, this.withContextualEncodedValue(item.options, item.context));
+                        }
+                        else {
+                            await this.index.put(new this.wrappedIndexedType(item.indexable, item.context), item.id, stripEncodedValue(item.options));
+                        }
+                    }
+                }
+            }
+            catch (error) {
+                if (error instanceof indexerTypes.NotStartedError && this.closed) {
+                    return transformed.map((item) => ({
+                        context: item.context,
+                        indexable: item.indexable,
+                    }));
                 }
+                throw error;
+            }
+            return transformed.map((item) => ({
+                context: item.context,
+                indexable: item.indexable,
+            }));
+        }
+        _cacheResolvedIdentityValue(id, value) {
+            this.cacheResolvedValue(id, value);
+        }
+        cacheResolvedValue(id, value) {
+            if (this.isProgramValued) {
+                this._resolverProgramCache.set(id, value);
+                indexCacheLogger("cache:set:program", { id });
+            }
+            else if (this._resolverCache) {
+                this._resolverCache.add(id, value);
+                indexCacheLogger("cache:set:value", { id });
             }
+        }
+        withContextualEncodedValue(options, context) {
+            if (!options?.encodedValue) {
+                return options;
+            }
+            const encodedValueParts = this.encodeContextualIndexedValueParts(options.encodedValue, context);
+            return encodedValueParts
+                ? { ...options, encodedValue: undefined, encodedValueParts }
+                : options;
+        }
+        encodeContextualIndexedValueParts(encodedValue, context) {
+            if (!encodedValue ||
+                !this.transformerIsIdentity ||
+                !this.indexedTypeIsDocumentType) {
+                return;
+            }
+            return {
+                prefix: encodedValue,
+                suffix: encodeContextSuffix(context),
+            };
+        }
+        del(key) {
+            this.deleteResolvedCacheForKey(key);
             return this.index.del({
                 query: [indexerTypes.getMatcher(this.indexBy, key.key)],
             });
         }
+        async delMany(keys) {
+            if (keys.length === 0) {
+                return;
+            }
+            for (const key of keys) {
+                this.deleteResolvedCacheForKey(key);
+            }
+            const delIdsNoReturn = this.index.delIdsNoReturn;
+            if (delIdsNoReturn) {
+                await delIdsNoReturn.call(this.index, keys);
+                return;
+            }
+            const delIds = this.index.delIds;
+            if (delIds) {
+                await delIds.call(this.index, keys);
+                return;
+            }
+            await Promise.all(keys.map((key) => this.del(key)));
+        }
+        clearResolvedCacheForKeys(keys) {
+            for (const key of keys) {
+                this.deleteResolvedCacheForKey(key);
+            }
+        }
+        delManyMaybe(keys) {
+            if (keys.length === 0) {
+                return;
+            }
+            for (const key of keys) {
+                this.deleteResolvedCacheForKey(key);
+            }
+            const delIdsNoReturn = this.index.delIdsNoReturn;
+            if (delIdsNoReturn) {
+                const result = delIdsNoReturn.call(this.index, keys);
+                return isPromiseLike(result) ? result.then(() => undefined) : undefined;
+            }
+            const delIds = this.index.delIds;
+            if (delIds) {
+                const result = delIds.call(this.index, keys);
+                return isPromiseLike(result) ? result.then(() => undefined) : undefined;
+            }
+            return Promise.all(keys.map((key) => this.del(key))).then(() => undefined);
+        }
         async getDetailed(key, options) {
             let coercedOptions = options;
             if (options?.remote && typeof options.remote !== "boolean") {
@@ -1393,14 +2410,17 @@ let DocumentIndex = (() => {
             }
         }
         get countIteratorsInProgress() {
-            return this._resumableIterators.queues.size;
+            return this._resumableIterators?.queues.size ?? 0;
         }
         clearAllResultQueues() {
+            if (!this._resultQueue) {
+                return;
+            }
             for (const [key, queue] of this._resultQueue) {
                 clearTimeout(queue.timeout);
                 this._resultQueue.delete(key);
                 this.cancelIteratorKeepAlive(key);
-                this._resumableIterators.close({ idString: key });
+                this._resumableIterators?.close({ idString: key });
             }
         }
         async waitForCoverReady(params) {
@@ -1614,33 +2634,58 @@ let DocumentIndex = (() => {
                         reachableOnly: !!remote.wait, // when we want to merge joining we can ignore pending to be online peers and instead consider them once they become online
                         signal: options?.signal,
                     });
-                // Cold start: cover can be temporarily self-only while replication metadata
-                // converges. For explicit remote searches, query bounded connected peers
-                // instead of waiting for replicator metadata to catch up.
+                // Cold start: cover can be temporarily self-only or empty while
+                // replication metadata converges. For explicit bounded remote searches,
+                // query bounded connected peers instead of waiting for replicator
+                // metadata to catch up.
                 if (!options?.remote?.from && isDefaultDomainArgs && remoteWasExplicit) {
                     const selfHash = this.node.identity.publicKey.hashcode();
                     const remoteCount = replicatorGroups.filter((h) => h !== selfHash).length;
                     if (remoteCount === 0) {
                         const waitEnabled = Boolean(remote.wait);
                         const coverIsSelfOnly = replicatorGroups.length === 1 && replicatorGroups[0] === selfHash;
-                        // If the cover is explicitly empty (no shards), don't override it unless
-                        // the caller requested waiting for joins (e.g. get(waitFor)).
-                        if (waitEnabled || coverIsSelfOnly) {
+                        const coverIsColdEmpty = replicatorGroups.length === 0 && remote.timeout != null;
+                        // If the cover is explicitly empty (no shards), don't override it
+                        // unless the caller requested waiting for joins (e.g. get(waitFor))
+                        // or bounded the remote query with a timeout.
+                        if (waitEnabled || coverIsSelfOnly || coverIsColdEmpty) {
+                            const extra = [];
+                            const addExtra = (hash) => {
+                                if (!hash || hash === selfHash || extra.includes(hash)) {
+                                    return;
+                                }
+                                extra.push(hash);
+                            };
                             const peerMap = this.node.services.pubsub?.peers;
+                            // Only consider replicators that are currently reachable.
+                            // The replicator index can contain stale (offline) peers, e.g.
+                            // persisted replicators after a restart; querying those would
+                            // block the first batch for the full wait timeout instead of
+                            // letting joining peers be merged as they arrive.
+                            if (peerMap?.has) {
+                                try {
+                                    for (const hash of await this._log.getReplicators()) {
+                                        if (peerMap.has(hash)) {
+                                            addExtra(hash);
+                                        }
+                                        if (extra.length >= 8)
+                                            break;
+                                    }
+                                }
+                                catch {
+                                    // Fall through to connected peers when the local replicator
+                                    // index is not ready yet.
+                                }
+                            }
                             if (peerMap?.keys) {
-                                const extra = [];
                                 for (const hash of peerMap.keys()) {
-                                    if (!hash || hash === selfHash)
-                                        continue;
-                                    extra.push(hash);
+                                    addExtra(hash);
                                     if (extra.length >= 8)
                                         break;
                                 }
-                                if (extra.length > 0) {
-                                    replicatorGroups = [
-                                        ...new Set([...replicatorGroups, ...extra]),
-                                    ];
-                                }
+                            }
+                            if (extra.length > 0) {
+                                replicatorGroups = [...new Set([...replicatorGroups, ...extra])];
                             }
                         }
                     }
@@ -2003,6 +3048,42 @@ let DocumentIndex = (() => {
                 }
                 return indexedPlaceholders;
             };
+            // The `visited` set prevents re-emitting the same document across pages
+            // and sources, but different sources can return different versions of the
+            // same document (e.g. a stale local head merged before a newer remote
+            // head arrives). Plain id-based dedupe would let the first-seen, stale
+            // version permanently shadow the newer one. If the id is still buffered
+            // (not yet handed to the consumer) and the incoming result is strictly
+            // preferred by the store's conflict rule, evict the stale buffered entry
+            // so the caller can buffer the preferred result in its place. Returns
+            // true when the caller should proceed to buffer the incoming result.
+            // Results that were already emitted to the consumer cannot be retracted
+            // here; those are only corrected via live updates/replication.
+            // The preference direction mirrors the index merge rule in program.ts:
+            // newest wins for mutable stores, oldest wins for immutable stores.
+            const isPreferredContext = (incoming, existing) => incoming.head !== existing.head &&
+                (this.immutable
+                    ? incoming.modified < existing.modified
+                    : incoming.modified > existing.modified);
+            const evictStaleBuffered = (indexKey, incomingContext) => {
+                for (const peerBuffer of peerBufferMap.values()) {
+                    for (let i = 0; i < peerBuffer.buffer.length; i++) {
+                        const existing = peerBuffer.buffer[i];
+                        const existingKey = indexerTypes.toId(this.indexByResolver(existing.indexed)).primitive;
+                        if (existingKey !== indexKey) {
+                            continue;
+                        }
+                        if (!isPreferredContext(incomingContext, existing.context)) {
+                            // same or non-preferred version: keep normal dedupe behavior
+                            return false;
+                        }
+                        peerBuffer.buffer.splice(i, 1);
+                        indexedPlaceholders?.delete(indexKey);
+                        return true;
+                    }
+                }
+                return false; // not buffered (already emitted): skip incoming
+            };
             let done = false;
             let drain = false; // if true, close on empty once (overrides manual)
             let first = false;
@@ -2204,7 +3285,8 @@ let DocumentIndex = (() => {
                                         indexedPlaceholders?.delete(indexKey);
                                         continue;
                                     }
-                                    if (visited.has(indexKey)) {
+                                    if (visited.has(indexKey) &&
+                                        !evictStaleBuffered(indexKey, result.context)) {
                                         continue;
                                     }
                                     visited.add(indexKey);
@@ -2218,7 +3300,8 @@ let DocumentIndex = (() => {
                                 else {
                                     const indexedResult = result;
                                     if (visited.has(indexKey) &&
-                                        !indexedPlaceholders?.has(indexKey)) {
+                                        !indexedPlaceholders?.has(indexKey) &&
+                                        !evictStaleBuffered(indexKey, indexedResult.context)) {
                                         continue;
                                     }
                                     visited.add(indexKey);
@@ -2353,7 +3436,8 @@ let DocumentIndex = (() => {
                                                 indexedPlaceholders?.delete(keyPrimitive);
                                                 continue;
                                             }
-                                            if (visited.has(keyPrimitive)) {
+                                            if (visited.has(keyPrimitive) &&
+                                                !evictStaleBuffered(keyPrimitive, result.context)) {
                                                 continue;
                                             }
                                             visited.add(keyPrimitive);
@@ -2368,7 +3452,8 @@ let DocumentIndex = (() => {
                                         else {
                                             const indexedResult = result;
                                             if (visited.has(keyPrimitive) &&
-                                                !indexedPlaceholders?.has(keyPrimitive)) {
+                                                !indexedPlaceholders?.has(keyPrimitive) &&
+                                                !evictStaleBuffered(keyPrimitive, indexedResult.context)) {
                                                 continue;
                                             }
                                             visited.add(keyPrimitive);
@@ -2448,7 +3533,8 @@ let DocumentIndex = (() => {
                                                     indexedPlaceholders?.delete(indexKey);
                                                     continue;
                                                 }
-                                                if (visited.has(indexKey)) {
+                                                if (visited.has(indexKey) &&
+                                                    !evictStaleBuffered(indexKey, result.context)) {
                                                     continue;
                                                 }
                                                 visited.add(indexKey);
@@ -2464,7 +3550,8 @@ let DocumentIndex = (() => {
                                             else {
                                                 const indexedResult = result;
                                                 if (visited.has(indexKey) &&
-                                                    !indexedPlaceholders?.has(indexKey)) {
+                                                    !indexedPlaceholders?.has(indexKey) &&
+                                                    !evictStaleBuffered(indexKey, indexedResult.context)) {
                                                     continue;
                                                 }
                                                 visited.add(indexKey);
@@ -2521,6 +3608,7 @@ let DocumentIndex = (() => {
                 if (n === 0) {
                     return [];
                 }
+                await pendingUpdateProcessing;
                 const bufferedBeforeFetch = peerBuffers().length;
                 const localHash = this.node.identity.publicKey.hashcode();
                 const hasBufferedRemoteResults = [...peerBufferMap.entries()].some(([peerHash, peerBuffer]) => peerHash !== localHash && peerBuffer.buffer.length > 0);
@@ -2710,6 +3798,7 @@ let DocumentIndex = (() => {
             const updateCallbacks = updateCallbacksRaw;
             let pendingBatchReason;
             let hasDeliveredResults = false;
+            let pendingUpdateProcessing = Promise.resolve();
             const emitOnBatch = async (batch, defaultReason) => {
                 if (!updateCallbacks?.onBatch || batch.length === 0) {
                     return;
@@ -2929,7 +4018,7 @@ let DocumentIndex = (() => {
                     }
                     return value;
                 };
-                const onChange = async (evt) => {
+                const processChange = async (evt) => {
                     // Optional filter to mutate/suppress change events
                     indexIteratorLogger.trace("processing live update change event", evt.detail);
                     let filtered = evt.detail;
@@ -3047,6 +4136,13 @@ let DocumentIndex = (() => {
                     }
                     signalUpdate();
                 };
+                const onChange = (evt) => {
+                    const task = pendingUpdateProcessing.then(() => processChange(evt));
+                    pendingUpdateProcessing = task.catch((error) => {
+                        warn("Failed to process iterator update", error);
+                    });
+                    return task;
+                };
                 this.documentEvents.addEventListener("change", onChange);
                 updatesCleanup = () => {
                     this.documentEvents.removeEventListener("change", onChange);