mindoodb 0.0.34 → 0.0.36

package/dist/core/utils/idGeneration.js

@@ -9,9 +9,12 @@
  * - Blockchain-like integrity for document entries
  */
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.generateDocId = generateDocId;
+exports.matchesDocIdPrefix = matchesDocIdPrefix;
 exports.generateDocEntryId = generateDocEntryId;
 exports.generateDepsFingerprint = generateDepsFingerprint;
 exports.generateAttachmentChunkId = generateAttachmentChunkId;
+exports.generateUniqueAttachmentChunkId = generateUniqueAttachmentChunkId;
 exports.generateFileUuid7 = generateFileUuid7;
 exports.generateChunkUuid7 = generateChunkUuid7;
 exports.parseDocEntryId = parseDocEntryId;
@@ -21,7 +24,13 @@ exports.isAttachmentChunkId = isAttachmentChunkId;
 exports.extractDocIdFromEntryId = extractDocIdFromEntryId;
 exports.computeContentHash = computeContentHash;
 const uuid_1 = require("uuid");
-const BASE62_ALPHABET = "0123456789abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ";
+/**
+ * Base62 alphabet in ASCII order (digits < uppercase < lowercase). The order
+ * matters: fixed-length, left-zero-padded encodings of numerically increasing
+ * values (e.g. UUID7 timestamps) then sort chronologically under plain
+ * lexicographic string comparison. Do NOT reorder.
+ */
+const BASE62_ALPHABET = "0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz";
 const UUID_NO_DASH_LENGTH = 32;
 const BASE62_UUID_LENGTH = 22;
 function trimLeft(target, length) {
@@ -57,6 +66,46 @@ function hexToBase62(uuid) {
     }
     return ensureLength(encoded, BASE62_UUID_LENGTH);
 }
+/**
+ * Generate a fresh, globally unique document id: a UUID7 encoded as a
+ * fixed-length (22 char), left-zero-padded base62 string, optionally prefixed
+ * with `<prefix>_`.
+ *
+ * Because the UUID7 timestamp occupies the most significant bits and the
+ * base62 alphabet is in ASCII order, ids generated later sort lexicographically
+ * after ids generated earlier (within the same prefix) — same property as raw
+ * UUID7 strings, but 14 characters shorter.
+ *
+ * The prefix (if any) is NOT validated here; callers validate it against
+ * `DOC_ID_PREFIX_REGEX` before invoking this.
+ *
+ * @param prefix Optional short application prefix (e.g. "cls"); joined with "_".
+ * @returns e.g. "0BqXa9yTFn2M4kVzR1sWpq" or "cls_0BqXa9yTFn2M4kVzR1sWpq"
+ */
+function generateDocId(prefix) {
+    const encoded = hexToBase62((0, uuid_1.v7)());
+    return prefix ? `${prefix}_${encoded}` : encoded;
+}
+/**
+ * Boundary-aware document-id prefix match used by prefix-filtered listing and
+ * changefeed iteration.
+ *
+ * A `docId` matches `idPrefix` when it either equals the prefix exactly or
+ * begins with `<idPrefix>_`. Matching on the `_` boundary (rather than a raw
+ * `startsWith`) mirrors the `<prefix>_<base62>` id scheme, so filtering by
+ * `"cls"` returns `cls_…` documents without also catching an unrelated prefix
+ * like `classroom_…`.
+ *
+ * An empty `idPrefix` matches every id (i.e. "no filter").
+ *
+ * @param docId The document id to test.
+ * @param idPrefix The prefix to match (without the trailing `_`).
+ */
+function matchesDocIdPrefix(docId, idPrefix) {
+    if (idPrefix.length === 0)
+        return true;
+    return docId === idPrefix || docId.startsWith(`${idPrefix}_`);
+}
 /**
  * Generate a document entry ID with blockchain-like chaining.
  * Format: <docId>_d_<depsFingerprint>_<automergeHash>
@@ -109,6 +158,34 @@ function generateAttachmentChunkId(docId, fileUuid7, chunkUuid7) {
     const base62Chunk = hexToBase62(chunkId);
     return `${docId}_a_${fileUuid7}_${base62Chunk}`;
 }
+/**
+ * Generate an attachment chunk id that is unique within one write operation
+ * even under case-insensitive comparison.
+ *
+ * Chunk entry ids become on-disk filenames (`entries/<id>.json`) and — unlike
+ * document entry ids — contain no lowercase-hex hash component, so two chunk
+ * ids differing only in the case of their base62 part would collide on
+ * case-insensitive filesystems (APFS/NTFS). The caller passes a set of
+ * case-folded ids already used in the current write; on the (astronomically
+ * unlikely) fold-collision the id is simply regenerated. The set is expected
+ * to be scoped to a single attachment write, so there is no persistent cost.
+ *
+ * @param docId The document ID this attachment belongs to
+ * @param fileUuid7 The UUID7 for the whole file (same for all chunks)
+ * @param usedCaseFoldedIds Case-folded ids already used in this write; the
+ *   returned id's folded form is added to the set.
+ * @returns The generated chunk ID
+ */
+function generateUniqueAttachmentChunkId(docId, fileUuid7, usedCaseFoldedIds) {
+    for (;;) {
+        const id = generateAttachmentChunkId(docId, fileUuid7);
+        const folded = id.toLowerCase();
+        if (!usedCaseFoldedIds.has(folded)) {
+            usedCaseFoldedIds.add(folded);
+            return id;
+        }
+    }
+}
 /**
  * Generate a new file UUID7.
  * This should be called once per file and reused for all chunks of that file.

package/dist/core/utils/idGeneration.js.map

@@ -1 +1 @@
-{"version":3,"file":"idGeneration.js","sourceRoot":"","sources":["../../../src/core/utils/idGeneration.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"idGeneration.js","sourceRoot":"","sources":["../../../src/core/utils/idGeneration.ts"],"names":[],"mappings":"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"}

package/dist/core/utils/index.d.ts

@@ -1,5 +1,6 @@
 /**
  * Core utility functions for MindooDB.
  */
-export { generateDocEntryId, generateDepsFingerprint, generateAttachmentChunkId, generateFileUuid7, generateChunkUuid7, parseDocEntryId, parseAttachmentChunkId, isDocEntryId, isAttachmentChunkId, extractDocIdFromEntryId, computeContentHash, } from './idGeneration';
+export { generateDocId, matchesDocIdPrefix, generateDocEntryId, generateDepsFingerprint, generateAttachmentChunkId, generateUniqueAttachmentChunkId, generateFileUuid7, generateChunkUuid7, parseDocEntryId, parseAttachmentChunkId, isDocEntryId, isAttachmentChunkId, extractDocIdFromEntryId, computeContentHash, } from './idGeneration';
+export { semanticNow, setSemanticTimeSourceForTesting, createQuantizedTimeSource, } from './timeSource';
 //# sourceMappingURL=index.d.ts.map

package/dist/core/utils/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/core/utils/index.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,EACL,kBAAkB,EAClB,uBAAuB,EACvB,yBAAyB,EACzB,iBAAiB,EACjB,kBAAkB,EAClB,eAAe,EACf,sBAAsB,EACtB,YAAY,EACZ,mBAAmB,EACnB,uBAAuB,EACvB,kBAAkB,GACnB,MAAM,gBAAgB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/core/utils/index.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,EACL,aAAa,EACb,kBAAkB,EAClB,kBAAkB,EAClB,uBAAuB,EACvB,yBAAyB,EACzB,+BAA+B,EAC/B,iBAAiB,EACjB,kBAAkB,EAClB,eAAe,EACf,sBAAsB,EACtB,YAAY,EACZ,mBAAmB,EACnB,uBAAuB,EACvB,kBAAkB,GACnB,MAAM,gBAAgB,CAAC;AAExB,OAAO,EACL,WAAW,EACX,+BAA+B,EAC/B,yBAAyB,GAC1B,MAAM,cAAc,CAAC"}

package/dist/core/utils/index.js

@@ -3,11 +3,14 @@
  * Core utility functions for MindooDB.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.computeContentHash = exports.extractDocIdFromEntryId = exports.isAttachmentChunkId = exports.isDocEntryId = exports.parseAttachmentChunkId = exports.parseDocEntryId = exports.generateChunkUuid7 = exports.generateFileUuid7 = exports.generateAttachmentChunkId = exports.generateDepsFingerprint = exports.generateDocEntryId = void 0;
+exports.createQuantizedTimeSource = exports.setSemanticTimeSourceForTesting = exports.semanticNow = exports.computeContentHash = exports.extractDocIdFromEntryId = exports.isAttachmentChunkId = exports.isDocEntryId = exports.parseAttachmentChunkId = exports.parseDocEntryId = exports.generateChunkUuid7 = exports.generateFileUuid7 = exports.generateUniqueAttachmentChunkId = exports.generateAttachmentChunkId = exports.generateDepsFingerprint = exports.generateDocEntryId = exports.matchesDocIdPrefix = exports.generateDocId = void 0;
 var idGeneration_1 = require("./idGeneration");
+Object.defineProperty(exports, "generateDocId", { enumerable: true, get: function () { return idGeneration_1.generateDocId; } });
+Object.defineProperty(exports, "matchesDocIdPrefix", { enumerable: true, get: function () { return idGeneration_1.matchesDocIdPrefix; } });
 Object.defineProperty(exports, "generateDocEntryId", { enumerable: true, get: function () { return idGeneration_1.generateDocEntryId; } });
 Object.defineProperty(exports, "generateDepsFingerprint", { enumerable: true, get: function () { return idGeneration_1.generateDepsFingerprint; } });
 Object.defineProperty(exports, "generateAttachmentChunkId", { enumerable: true, get: function () { return idGeneration_1.generateAttachmentChunkId; } });
+Object.defineProperty(exports, "generateUniqueAttachmentChunkId", { enumerable: true, get: function () { return idGeneration_1.generateUniqueAttachmentChunkId; } });
 Object.defineProperty(exports, "generateFileUuid7", { enumerable: true, get: function () { return idGeneration_1.generateFileUuid7; } });
 Object.defineProperty(exports, "generateChunkUuid7", { enumerable: true, get: function () { return idGeneration_1.generateChunkUuid7; } });
 Object.defineProperty(exports, "parseDocEntryId", { enumerable: true, get: function () { return idGeneration_1.parseDocEntryId; } });
@@ -16,4 +19,8 @@ Object.defineProperty(exports, "isDocEntryId", { enumerable: true, get: function
 Object.defineProperty(exports, "isAttachmentChunkId", { enumerable: true, get: function () { return idGeneration_1.isAttachmentChunkId; } });
 Object.defineProperty(exports, "extractDocIdFromEntryId", { enumerable: true, get: function () { return idGeneration_1.extractDocIdFromEntryId; } });
 Object.defineProperty(exports, "computeContentHash", { enumerable: true, get: function () { return idGeneration_1.computeContentHash; } });
+var timeSource_1 = require("./timeSource");
+Object.defineProperty(exports, "semanticNow", { enumerable: true, get: function () { return timeSource_1.semanticNow; } });
+Object.defineProperty(exports, "setSemanticTimeSourceForTesting", { enumerable: true, get: function () { return timeSource_1.setSemanticTimeSourceForTesting; } });
+Object.defineProperty(exports, "createQuantizedTimeSource", { enumerable: true, get: function () { return timeSource_1.createQuantizedTimeSource; } });
 //# sourceMappingURL=index.js.map

package/dist/core/utils/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/core/utils/index.ts"],"names":[],"mappings":";AAAA;;GAEG;;;AAEH,+CAYwB;AAXtB,kHAAA,kBAAkB,OAAA;AAClB,uHAAA,uBAAuB,OAAA;AACvB,yHAAA,yBAAyB,OAAA;AACzB,iHAAA,iBAAiB,OAAA;AACjB,kHAAA,kBAAkB,OAAA;AAClB,+GAAA,eAAe,OAAA;AACf,sHAAA,sBAAsB,OAAA;AACtB,4GAAA,YAAY,OAAA;AACZ,mHAAA,mBAAmB,OAAA;AACnB,uHAAA,uBAAuB,OAAA;AACvB,kHAAA,kBAAkB,OAAA"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/core/utils/index.ts"],"names":[],"mappings":";AAAA;;GAEG;;;AAEH,+CAewB;AAdtB,6GAAA,aAAa,OAAA;AACb,kHAAA,kBAAkB,OAAA;AAClB,kHAAA,kBAAkB,OAAA;AAClB,uHAAA,uBAAuB,OAAA;AACvB,yHAAA,yBAAyB,OAAA;AACzB,+HAAA,+BAA+B,OAAA;AAC/B,iHAAA,iBAAiB,OAAA;AACjB,kHAAA,kBAAkB,OAAA;AAClB,+GAAA,eAAe,OAAA;AACf,sHAAA,sBAAsB,OAAA;AACtB,4GAAA,YAAY,OAAA;AACZ,mHAAA,mBAAmB,OAAA;AACnB,uHAAA,uBAAuB,OAAA;AACvB,kHAAA,kBAAkB,OAAA;AAGpB,2CAIsB;AAHpB,yGAAA,WAAW,OAAA;AACX,6HAAA,+BAA+B,OAAA;AAC/B,uHAAA,yBAAyB,OAAA"}

package/dist/core/utils/timeSource.d.ts

@@ -0,0 +1,34 @@
+/**
+ * Semantic time source for MindooDB.
+ *
+ * Every timestamp that becomes part of persisted or user-visible state —
+ * store-entry `createdAt`, document `lastModified`/`_lastModified`, the
+ * provisional trusted-time "now" for un-witnessed entries, audit records —
+ * must come from {@link semanticNow} instead of calling `Date.now()`
+ * directly. Pure elapsed-time measurements (performance metrics, event-loop
+ * pacing, in-memory cache TTLs) intentionally keep using `Date.now()`.
+ *
+ * Why a single funnel:
+ * - Tests can pin or quantize the clock (see
+ *   {@link createQuantizedTimeSource}) to make same-millisecond timestamp
+ *   ties deterministic instead of rare — surfacing tie-handling bugs that
+ *   otherwise appear as flaky failures.
+ * - It is the seam for upgrading the timestamp scheme later (e.g. a hybrid
+ *   logical clock that can never tie or run backwards): only this module
+ *   would change, not every call site.
+ */
+/** Current semantic time in ms since epoch (wall clock unless overridden). */
+export declare function semanticNow(): number;
+/**
+ * Install (or remove, with `null`) a test-only override for
+ * {@link semanticNow}. Not intended for production use.
+ */
+export declare function setSemanticTimeSourceForTesting(fn: (() => number) | null): void;
+/**
+ * A time source that floors the wall clock to `quantumMs` buckets. Time
+ * still advances (timeouts/cooldowns keep working), but all semantic
+ * timestamps produced within one quantum collide — making timestamp-tie
+ * hazards deterministic for stress testing.
+ */
+export declare function createQuantizedTimeSource(quantumMs: number): () => number;
+//# sourceMappingURL=timeSource.d.ts.map

package/dist/core/utils/timeSource.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"timeSource.d.ts","sourceRoot":"","sources":["../../../src/core/utils/timeSource.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAIH,8EAA8E;AAC9E,wBAAgB,WAAW,IAAI,MAAM,CAEpC;AAED;;;GAGG;AACH,wBAAgB,+BAA+B,CAAC,EAAE,EAAE,CAAC,MAAM,MAAM,CAAC,GAAG,IAAI,GAAG,IAAI,CAE/E;AAED;;;;;GAKG;AACH,wBAAgB,yBAAyB,CAAC,SAAS,EAAE,MAAM,GAAG,MAAM,MAAM,CAKzE"}

package/dist/core/utils/timeSource.js

@@ -0,0 +1,49 @@
+"use strict";
+/**
+ * Semantic time source for MindooDB.
+ *
+ * Every timestamp that becomes part of persisted or user-visible state —
+ * store-entry `createdAt`, document `lastModified`/`_lastModified`, the
+ * provisional trusted-time "now" for un-witnessed entries, audit records —
+ * must come from {@link semanticNow} instead of calling `Date.now()`
+ * directly. Pure elapsed-time measurements (performance metrics, event-loop
+ * pacing, in-memory cache TTLs) intentionally keep using `Date.now()`.
+ *
+ * Why a single funnel:
+ * - Tests can pin or quantize the clock (see
+ *   {@link createQuantizedTimeSource}) to make same-millisecond timestamp
+ *   ties deterministic instead of rare — surfacing tie-handling bugs that
+ *   otherwise appear as flaky failures.
+ * - It is the seam for upgrading the timestamp scheme later (e.g. a hybrid
+ *   logical clock that can never tie or run backwards): only this module
+ *   would change, not every call site.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.semanticNow = semanticNow;
+exports.setSemanticTimeSourceForTesting = setSemanticTimeSourceForTesting;
+exports.createQuantizedTimeSource = createQuantizedTimeSource;
+let overrideFn = null;
+/** Current semantic time in ms since epoch (wall clock unless overridden). */
+function semanticNow() {
+    return overrideFn ? overrideFn() : Date.now();
+}
+/**
+ * Install (or remove, with `null`) a test-only override for
+ * {@link semanticNow}. Not intended for production use.
+ */
+function setSemanticTimeSourceForTesting(fn) {
+    overrideFn = fn;
+}
+/**
+ * A time source that floors the wall clock to `quantumMs` buckets. Time
+ * still advances (timeouts/cooldowns keep working), but all semantic
+ * timestamps produced within one quantum collide — making timestamp-tie
+ * hazards deterministic for stress testing.
+ */
+function createQuantizedTimeSource(quantumMs) {
+    if (!Number.isFinite(quantumMs) || quantumMs < 1) {
+        throw new Error(`Invalid clock quantum: ${quantumMs}`);
+    }
+    return () => Math.floor(Date.now() / quantumMs) * quantumMs;
+}
+//# sourceMappingURL=timeSource.js.map

package/dist/core/utils/timeSource.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"timeSource.js","sourceRoot":"","sources":["../../../src/core/utils/timeSource.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;;;;;;GAkBG;;AAKH,kCAEC;AAMD,0EAEC;AAQD,8DAKC;AA1BD,IAAI,UAAU,GAA0B,IAAI,CAAC;AAE7C,8EAA8E;AAC9E,SAAgB,WAAW;IACzB,OAAO,UAAU,CAAC,CAAC,CAAC,UAAU,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,GAAG,EAAE,CAAC;AAChD,CAAC;AAED;;;GAGG;AACH,SAAgB,+BAA+B,CAAC,EAAyB;IACvE,UAAU,GAAG,EAAE,CAAC;AAClB,CAAC;AAED;;;;;GAKG;AACH,SAAgB,yBAAyB,CAAC,SAAiB;IACzD,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,SAAS,CAAC,IAAI,SAAS,GAAG,CAAC,EAAE,CAAC;QACjD,MAAM,IAAI,KAAK,CAAC,0BAA0B,SAAS,EAAE,CAAC,CAAC;IACzD,CAAC;IACD,OAAO,GAAG,EAAE,CAAC,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,GAAG,EAAE,GAAG,SAAS,CAAC,GAAG,SAAS,CAAC;AAC9D,CAAC"}

package/dist/node/appendonlystores/BasicOnDiskContentAddressedStore.d.ts

@@ -38,7 +38,7 @@
  *
  * @module BasicOnDiskContentAddressedStore
  */
-import { AttachmentReadPlan, AttachmentReadPlanOptions, ContentAddressedStore, ContentAddressedStoreFactory, CreateStoreResult, DocumentMaterializationBatchPlan, DocumentMaterializationPlan, MaterializationPlanOptions, OpenStoreOptions, StoreIndexBuildStatus, StoreCompactionStatus, StoreKind, AwaitIndexReadyOptions, StoreScanCursor, StoreScanFilters, StoreScanResult, StoreIdBloomSummary } from "../../core/appendonlystores/types";
+import { AttachmentReadPlan, AttachmentReadPlanOptions, ContentAddressedStore, ContentAddressedStoreFactory, CreateStoreResult, DocumentMaterializationBatchPlan, DocumentMaterializationPlan, MaterializationPlanOptions, OpenStoreOptions, StoreIndexBuildStatus, StoreCompactionStatus, StoreKind, AwaitIndexReadyOptions, StoreScanCursor, StoreScanFilters, StoreScanResult, StoreIdBloomSummary, StoreHead } from "../../core/appendonlystores/types";
 import type { StoreEntry, StoreEntryMetadata, StoreEntryType } from "../../core/types";
 import { Logger } from "../../core/logging";
 /**
@@ -75,6 +75,8 @@ export declare class BasicOnDiskContentAddressedStore implements ContentAddresse
     private readonly metadataIndexPath;
     /** Directory containing append-only metadata segment files. */
     private readonly metadataSegmentsDir;
+    /** Path to the persisted cursor-lineage epoch file (see {@link StoreHead}). */
+    private readonly storeEpochPath;
     /** Whether in-memory indexing is active (default true). */
     private readonly indexingEnabled;
     /** Trigger compaction when this many segment files have accumulated. */
@@ -120,6 +122,12 @@ export declare class BasicOnDiskContentAddressedStore implements ContentAddresse
     private orderedMetadata;
     /** Next monotonic local receipt order assigned on insert. */
     private nextReceiptOrder;
+    /**
+     * Cursor-lineage epoch (see {@link StoreHead}). Loaded from / persisted to
+     * `store-epoch.json`; regenerated on store reset and on legacy
+     * receipt-order migration so peers discard stale persisted scan cursors.
+     */
+    private storeEpoch;
     /** Current phase and progress of the index build (building / ready). */
     private indexStatus;
     /**
@@ -336,6 +344,13 @@ export declare class BasicOnDiskContentAddressedStore implements ContentAddresse
      *          store already had receipt-order metadata (or was empty).
      */
     private ensurePersistedReceiptOrder;
+    /**
+     * Load the persisted cursor-lineage epoch, creating (and persisting) a new
+     * one when it is missing, unreadable, or `forceNew` is set (receipt-order
+     * migration). The epoch lives in its own small file so it survives index
+     * rebuilds and works with indexing disabled.
+     */
+    private loadOrCreateStoreEpoch;
     /** List all `.json` files in the `entries/` directory. */
     private listEntryFiles;
     /** Resolve the absolute path to the metadata file for a given entry id. */
@@ -502,6 +517,7 @@ export declare class BasicOnDiskContentAddressedStore implements ContentAddresse
      *          bitset, suitable for transmission over the network.
      */
     getIdBloomSummary(): Promise<StoreIdBloomSummary>;
+    getStoreHead(): Promise<StoreHead>;
     planDocumentMaterialization(docId: string, options?: MaterializationPlanOptions): Promise<DocumentMaterializationPlan>;
     planDocumentMaterializationBatch(docIds: string[], options?: MaterializationPlanOptions): Promise<DocumentMaterializationBatchPlan>;
     /**

package/dist/node/appendonlystores/BasicOnDiskContentAddressedStore.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"BasicOnDiskContentAddressedStore.d.ts","sourceRoot":"","sources":["../../../src/node/appendonlystores/BasicOnDiskContentAddressedStore.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"BasicOnDiskContentAddressedStore.d.ts","sourceRoot":"","sources":["../../../src/node/appendonlystores/BasicOnDiskContentAddressedStore.ts"],"names":[],"mappings":"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"}

package/dist/node/appendonlystores/BasicOnDiskContentAddressedStore.js

@@ -78,6 +78,7 @@ const promises_1 = require("fs/promises");
 const fs_1 = require("fs");
 const path = __importStar(require("path"));
 const types_1 = require("../../core/appendonlystores/types");
+const uuid_1 = require("uuid");
 const AttachmentReadPlanner_1 = require("../../core/appendonlystores/AttachmentReadPlanner");
 const bloom_1 = require("../../core/appendonlystores/bloom");
 const MaterializationPlanner_1 = require("../../core/appendonlystores/MaterializationPlanner");
@@ -221,6 +222,12 @@ class BasicOnDiskContentAddressedStore {
         this.orderedMetadata = [];
         /** Next monotonic local receipt order assigned on insert. */
         this.nextReceiptOrder = 1;
+        /**
+         * Cursor-lineage epoch (see {@link StoreHead}). Loaded from / persisted to
+         * `store-epoch.json`; regenerated on store reset and on legacy
+         * receipt-order migration so peers discard stale persisted scan cursors.
+         */
+        this.storeEpoch = (0, uuid_1.v7)();
         this.dbId = dbId;
         this.storeKind = storeKind;
         this.logger =
@@ -231,6 +238,7 @@ class BasicOnDiskContentAddressedStore {
         this.contentDir = path.join(this.storeRoot, "content");
         this.metadataIndexPath = path.join(this.storeRoot, "metadata-index.json");
         this.metadataSegmentsDir = path.join(this.storeRoot, "metadata-segments");
+        this.storeEpochPath = path.join(this.storeRoot, "store-epoch.json");
         this.indexingEnabled = options?.indexingEnabled !== false;
         const compactionOption = options?.metadataSegmentCompactionMinFiles;
         this.metadataSegmentCompactionMinFiles =
@@ -285,6 +293,9 @@ class BasicOnDiskContentAddressedStore {
         await (0, promises_1.mkdir)(this.contentDir, { recursive: true });
         await (0, promises_1.mkdir)(this.metadataSegmentsDir, { recursive: true });
         const migratedReceiptOrder = await this.ensurePersistedReceiptOrder();
+        // A receipt-order migration reassigns receiptOrder values, so persisted
+        // scan cursors from before the migration are invalid: start a new epoch.
+        await this.loadOrCreateStoreEpoch({ forceNew: migratedReceiptOrder });
         if (!this.indexingEnabled) {
             this.indexStatus = {
                 phase: "ready",
@@ -845,6 +856,29 @@ class BasicOnDiskContentAddressedStore {
         this.nextReceiptOrder = nextReceiptOrder;
         return true;
     }
+    /**
+     * Load the persisted cursor-lineage epoch, creating (and persisting) a new
+     * one when it is missing, unreadable, or `forceNew` is set (receipt-order
+     * migration). The epoch lives in its own small file so it survives index
+     * rebuilds and works with indexing disabled.
+     */
+    async loadOrCreateStoreEpoch(options) {
+        if (!options?.forceNew && (await this.fileExists(this.storeEpochPath))) {
+            try {
+                const raw = await (0, promises_1.readFile)(this.storeEpochPath, "utf-8");
+                const parsed = JSON.parse(raw);
+                if (typeof parsed.epoch === "string" && parsed.epoch.length > 0) {
+                    this.storeEpoch = parsed.epoch;
+                    return;
+                }
+            }
+            catch (err) {
+                this.logger.warn(`Failed to read store epoch, creating a new one: ${String(err)}`);
+            }
+        }
+        this.storeEpoch = (0, uuid_1.v7)();
+        await this.writeFileAtomic(this.storeEpochPath, JSON.stringify({ epoch: this.storeEpoch }));
+    }
     // ---------------------------------------------------------------------------
     // Filesystem I/O helpers
     // ---------------------------------------------------------------------------
@@ -1353,6 +1387,13 @@ class BasicOnDiskContentAddressedStore {
         const ids = await this.getAllIds();
         return (0, bloom_1.createIdBloomSummary)(ids);
     }
+    async getStoreHead() {
+        await this.ensureInitialized();
+        return {
+            epoch: this.storeEpoch,
+            maxReceiptOrder: this.nextReceiptOrder - 1,
+        };
+    }
     async planDocumentMaterialization(docId, options) {
         await this.ensureInitialized();
         let entries = [];
@@ -1503,6 +1544,8 @@ class BasicOnDiskContentAddressedStore {
         await (0, promises_1.mkdir)(this.entriesDir, { recursive: true });
         await (0, promises_1.mkdir)(this.contentDir, { recursive: true });
         await (0, promises_1.mkdir)(this.metadataSegmentsDir, { recursive: true });
+        // New cursor lineage after a full reset (see StoreHead.epoch).
+        await this.loadOrCreateStoreEpoch({ forceNew: true });
         if (this.indexingEnabled) {
             this.indexStatus = { phase: "ready", indexingEnabled: true, progress01: 1 };
         }