mindoodb 0.0.3 → 0.0.5

package/dist/core/utils/idGeneration.js

@@ -20,8 +20,43 @@ exports.isDocEntryId = isDocEntryId;
 exports.isAttachmentChunkId = isAttachmentChunkId;
 exports.extractDocIdFromEntryId = extractDocIdFromEntryId;
 exports.computeContentHash = computeContentHash;
-const uuid_base62_1 = require("@digitalmaas/uuid-base62");
 const uuid_1 = require("uuid");
+const BASE62_ALPHABET = "0123456789abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ";
+const UUID_NO_DASH_LENGTH = 32;
+const BASE62_UUID_LENGTH = 22;
+function trimLeft(target, length) {
+    let trim = 0;
+    while (target[trim] === "0" && target.length - trim > length) {
+        trim++;
+    }
+    return target.slice(trim);
+}
+function ensureLength(target, length) {
+    if (target.length < length) {
+        return target.padStart(length, "0");
+    }
+    if (target.length > length) {
+        return trimLeft(target, length);
+    }
+    return target;
+}
+function hexToBase62(uuid) {
+    const normalized = uuid.replace(/-/g, "");
+    if (!/^[0-9a-fA-F]{32}$/.test(normalized)) {
+        throw new TypeError(`Invalid UUID for base62 encoding: ${uuid}`);
+    }
+    let value = BigInt(`0x${normalized}`);
+    if (value === 0n) {
+        return "0".repeat(BASE62_UUID_LENGTH);
+    }
+    let encoded = "";
+    while (value > 0n) {
+        const digit = Number(value % 62n);
+        encoded = BASE62_ALPHABET[digit] + encoded;
+        value /= 62n;
+    }
+    return ensureLength(encoded, BASE62_UUID_LENGTH);
+}
 /**
  * Generate a document entry ID with blockchain-like chaining.
  * Format: <docId>_d_<depsFingerprint>_<automergeHash>
@@ -71,8 +106,7 @@ async function generateDepsFingerprint(dependencyAutomergeHashes, subtle) {
  */
 function generateAttachmentChunkId(docId, fileUuid7, chunkUuid7) {
     const chunkId = chunkUuid7 || (0, uuid_1.v7)();
-    // base62Encode expects UUID with dashes
-    const base62Chunk = (0, uuid_base62_1.encode)(chunkId);
+    const base62Chunk = hexToBase62(chunkId);
     return `${docId}_a_${fileUuid7}_${base62Chunk}`;
 }
 /**

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

@@ -1 +1 @@
-{"version":3,"file":"idGeneration.js","sourceRoot":"","sources":["../../../src/core/utils/idGeneration.ts"],"names":[],"mappings":";AAAA;;;;;;;;GAQG;;AAkBH,gDAQC;AAUD,0DAgBC;AAWD,8DASC;AAQD,8CAEC;AAQD,gDAEC;AAQD,0CAcC;AAQD,wDAaC;AAQD,oCAEC;AAQD,kDAEC;AAQD,0DASC;AAUD,gDAUC;AA9LD,0DAA0F;AAC1F,+BAAoC;AAEpC;;;;;;;;;;;;GAYG;AACI,KAAK,UAAU,kBAAkB,CACtC,KAAa,EACb,aAAqB,EACrB,yBAAmC,EACnC,MAAoB;IAEpB,MAAM,eAAe,GAAG,MAAM,uBAAuB,CAAC,yBAAyB,EAAE,MAAM,CAAC,CAAC;IACzF,OAAO,GAAG,KAAK,MAAM,eAAe,IAAI,aAAa,EAAE,CAAC;AAC1D,CAAC;AAED;;;;;;;GAOG;AACI,KAAK,UAAU,uBAAuB,CAC3C,yBAAmC,EACnC,MAAoB;IAEpB,IAAI,yBAAyB,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QAC3C,OAAO,GAAG,CAAC;IACb,CAAC;IAED,0CAA0C;IAC1C,MAAM,UAAU,GAAG,CAAC,GAAG,yBAAyB,CAAC,CAAC,IAAI,EAAE,CAAC;IACzD,MAAM,UAAU,GAAG,UAAU,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;IACxC,MAAM,UAAU,GAAG,MAAM,MAAM,CAAC,MAAM,CAAC,SAAS,EAAE,IAAI,WAAW,EAAE,CAAC,MAAM,CAAC,UAAU,CAAC,CAAC,CAAC;IACxF,OAAO,KAAK,CAAC,IAAI,CAAC,IAAI,UAAU,CAAC,UAAU,CAAC,CAAC;SAC1C,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC,CAAE,8BAA8B;SAC3C,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,QAAQ,CAAC,EAAE,CAAC,CAAC,QAAQ,CAAC,CAAC,EAAE,GAAG,CAAC,CAAC;SACzC,IAAI,CAAC,EAAE,CAAC,CAAC;AACd,CAAC;AAED;;;;;;;;GAQG;AACH,SAAgB,yBAAyB,CACvC,KAAa,EACb,SAAiB,EACjB,UAAmB;IAEnB,MAAM,OAAO,GAAG,UAAU,IAAI,IAAA,SAAM,GAAE,CAAC;IACvC,wCAAwC;IACxC,MAAM,WAAW,GAAG,IAAA,oBAAY,EAAC,OAAO,CAAC,CAAC;IAC1C,OAAO,GAAG,KAAK,MAAM,SAAS,IAAI,WAAW,EAAE,CAAC;AAClD,CAAC;AAED;;;;;GAKG;AACH,SAAgB,iBAAiB;IAC/B,OAAO,IAAA,SAAM,GAAE,CAAC;AAClB,CAAC;AAED;;;;;GAKG;AACH,SAAgB,kBAAkB;IAChC,OAAO,IAAA,SAAM,GAAE,CAAC;AAClB,CAAC;AAED;;;;;GAKG;AACH,SAAgB,eAAe,CAAC,EAAU;IAKxC,qDAAqD;IACrD,0EAA0E;IAC1E,MAAM,KAAK,GAAG,EAAE,CAAC,KAAK,CAAC,6BAA6B,CAAC,CAAC;IACtD,IAAI,CAAC,KAAK;QAAE,OAAO,IAAI,CAAC;IACxB,OAAO;QACL,KAAK,EAAE,KAAK,CAAC,CAAC,CAAC;QACf,eAAe,EAAE,KAAK,CAAC,CAAC,CAAC;QACzB,aAAa,EAAE,KAAK,CAAC,CAAC,CAAC;KACxB,CAAC;AACJ,CAAC;AAED;;;;;GAKG;AACH,SAAgB,sBAAsB,CAAC,EAAU;IAK/C,+CAA+C;IAC/C,MAAM,KAAK,GAAG,EAAE,CAAC,KAAK,CAAC,uBAAuB,CAAC,CAAC;IAChD,IAAI,CAAC,KAAK;QAAE,OAAO,IAAI,CAAC;IACxB,OAAO;QACL,KAAK,EAAE,KAAK,CAAC,CAAC,CAAC;QACf,SAAS,EAAE,KAAK,CAAC,CAAC,CAAC;QACnB,aAAa,EAAE,KAAK,CAAC,CAAC,CAAC;KACxB,CAAC;AACJ,CAAC;AAED;;;;;GAKG;AACH,SAAgB,YAAY,CAAC,EAAU;IACrC,OAAO,EAAE,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAC;AAC5B,CAAC;AAED;;;;;GAKG;AACH,SAAgB,mBAAmB,CAAC,EAAU;IAC5C,OAAO,EAAE,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAC;AAC5B,CAAC;AAED;;;;;GAKG;AACH,SAAgB,uBAAuB,CAAC,EAAU;IAChD,IAAI,YAAY,CAAC,EAAE,CAAC,EAAE,CAAC;QACrB,MAAM,MAAM,GAAG,eAAe,CAAC,EAAE,CAAC,CAAC;QACnC,OAAO,MAAM,EAAE,KAAK,IAAI,IAAI,CAAC;IAC/B,CAAC;SAAM,IAAI,mBAAmB,CAAC,EAAE,CAAC,EAAE,CAAC;QACnC,MAAM,MAAM,GAAG,sBAAsB,CAAC,EAAE,CAAC,CAAC;QAC1C,OAAO,MAAM,EAAE,KAAK,IAAI,IAAI,CAAC;IAC/B,CAAC;IACD,OAAO,IAAI,CAAC;AACd,CAAC;AAED;;;;;;;GAOG;AACI,KAAK,UAAU,kBAAkB,CACtC,IAAgB,EAChB,MAAoB;IAEpB,sEAAsE;IACtE,MAAM,MAAM,GAAG,IAAI,CAAC,MAAM,CAAC,KAAK,CAAC,IAAI,CAAC,UAAU,EAAE,IAAI,CAAC,UAAU,GAAG,IAAI,CAAC,UAAU,CAAgB,CAAC;IACpG,MAAM,UAAU,GAAG,MAAM,MAAM,CAAC,MAAM,CAAC,SAAS,EAAE,MAAM,CAAC,CAAC;IAC1D,OAAO,KAAK,CAAC,IAAI,CAAC,IAAI,UAAU,CAAC,UAAU,CAAC,CAAC;SAC1C,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,QAAQ,CAAC,EAAE,CAAC,CAAC,QAAQ,CAAC,CAAC,EAAE,GAAG,CAAC,CAAC;SACzC,IAAI,CAAC,EAAE,CAAC,CAAC;AACd,CAAC"}
+{"version":3,"file":"idGeneration.js","sourceRoot":"","sources":["../../../src/core/utils/idGeneration.ts"],"names":[],"mappings":"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"}

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

@@ -38,7 +38,7 @@
  *
  * @module BasicOnDiskContentAddressedStore
  */
-import { ContentAddressedStore, ContentAddressedStoreFactory, CreateStoreResult, OpenStoreOptions, StoreIndexBuildStatus, StoreCompactionStatus, AwaitIndexReadyOptions, StoreScanCursor, StoreScanFilters, StoreScanResult, StoreIdBloomSummary } from "../../core/appendonlystores/types";
+import { AttachmentReadPlan, AttachmentReadPlanOptions, ContentAddressedStore, ContentAddressedStoreFactory, CreateStoreResult, DocumentMaterializationBatchPlan, DocumentMaterializationPlan, MaterializationPlanOptions, OpenStoreOptions, StoreIndexBuildStatus, StoreCompactionStatus, AwaitIndexReadyOptions, StoreScanCursor, StoreScanFilters, StoreScanResult, StoreIdBloomSummary } from "../../core/appendonlystores/types";
 import type { StoreEntry, StoreEntryMetadata, StoreEntryType } from "../../core/types";
 import { Logger } from "../../core/logging";
 /**
@@ -111,11 +111,13 @@ export declare class BasicOnDiskContentAddressedStore implements ContentAddresse
      */
     private contentRefCount;
     /**
-     * All metadata sorted by `(createdAt ASC, id ASC)`.
+     * All metadata sorted by `(receiptOrder ASC, id ASC)`.
      * Supports O(log N) lower-bound binary search for cursor-based scans
      * in {@link scanEntriesSince}.
      */
     private orderedMetadata;
+    /** Next monotonic local receipt order assigned on insert. */
+    private nextReceiptOrder;
     /** Current phase and progress of the index build (building / ready). */
     private indexStatus;
     /**
@@ -159,7 +161,7 @@ export declare class BasicOnDiskContentAddressedStore implements ContentAddresse
      *
      * Clears all in-memory structures, reads every `entries/*.json` file,
      * populates the primary, secondary, and ref-count indexes, and finally
-     * sorts `orderedMetadata` by `(createdAt, id)`.
+     * sorts `orderedMetadata` by `(receiptOrder, id)`.
      *
      * This is the slowest startup path (O(N) filesystem reads) and is only
      * used when the persisted snapshot + segments cannot be validated.
@@ -265,13 +267,13 @@ export declare class BasicOnDiskContentAddressedStore implements ContentAddresse
      */
     private computeSegmentFilesTotalBytes;
     /**
-     * Compare two metadata entries by the canonical sort key `(createdAt, id)`.
+     * Compare two metadata entries by the canonical sort key `(receiptOrder, id)`.
      * Used to maintain and query the `orderedMetadata` sorted array.
      */
     private compareMetadata;
     /**
      * Binary search for the first index in `orderedMetadata` that is strictly
-     * greater than the given cursor position `(createdAt, id)`.
+     * greater than the given cursor position `(receiptOrder, id)`.
      *
      * Returns 0 when cursor is `null` (start from the beginning).
      * Runs in O(log N) time.
@@ -310,6 +312,23 @@ export declare class BasicOnDiskContentAddressedStore implements ContentAddresse
      * Updates `entries`, `docIndex`, `orderedMetadata`, and `contentRefCount`.
      */
     private applyMetadataUpsert;
+    private recomputeNextReceiptOrder;
+    private compareLegacyCreatedAtId;
+    /**
+     * Ensure every persisted metadata file has a `receiptOrder`.
+     *
+     * Older on-disk stores predate receipt-order discovery and therefore only
+     * persist `createdAt`. On startup we detect that legacy shape, assign a
+     * deterministic synthetic `receiptOrder` by sorting existing entries using
+     * the old `(createdAt, id)` rule, and rewrite the metadata files in that
+     * order. This preserves a stable forward cursor contract after migration,
+     * even though the exact historic arrival order is unknowable for preexisting
+     * rows.
+     *
+     * @returns `true` when a backfill rewrite was performed, `false` when the
+     *          store already had receipt-order metadata (or was empty).
+     */
+    private ensurePersistedReceiptOrder;
     /** List all `.json` files in the `entries/` directory. */
     private listEntryFiles;
     /** Resolve the absolute path to the metadata file for a given entry id. */
@@ -366,6 +385,7 @@ export declare class BasicOnDiskContentAddressedStore implements ContentAddresse
     private listAllMetadata;
     /** Return the database id this store was created for. */
     getId(): string;
+    getCacheIdentity(): string;
     /**
      * Persist one or more entries to disk.
      *
@@ -388,6 +408,8 @@ export declare class BasicOnDiskContentAddressedStore implements ContentAddresse
      * is O(1); the content read is always a disk I/O.
      */
     getEntries(ids: string[]): Promise<StoreEntry[]>;
+    getEntryMetadata(id: string): Promise<StoreEntryMetadata | null>;
+    planAttachmentReadByWalkingMetadata(lastChunkId: string, attachmentSize: number, options: AttachmentReadPlanOptions): Promise<AttachmentReadPlan>;
     /**
      * Check which of the given ids exist in the store.
      *
@@ -424,7 +446,7 @@ export declare class BasicOnDiskContentAddressedStore implements ContentAddresse
     /**
      * Return all entry ids in the store.
      *
-     * When indexing is enabled, returns ids in `(createdAt, id)` order.
+     * When indexing is enabled, returns ids in `(receiptOrder, id)` order.
      * Without indexing, order depends on the filesystem directory listing.
      */
     getAllIds(): Promise<string[]>;
@@ -433,7 +455,7 @@ export declare class BasicOnDiskContentAddressedStore implements ContentAddresse
      *
      * Designed for high-volume synchronization: the caller repeatedly advances
      * a cursor to stream through all entries in deterministic
-     * `(createdAt ASC, id ASC)` order, optionally applying filters.
+     * `(receiptOrder ASC, id ASC)` order, optionally applying filters.
      *
      * **Indexed path** (default):
      * - O(log N) binary search for the cursor position.
@@ -463,6 +485,8 @@ export declare class BasicOnDiskContentAddressedStore implements ContentAddresse
      *          bitset, suitable for transmission over the network.
      */
     getIdBloomSummary(): Promise<StoreIdBloomSummary>;
+    planDocumentMaterialization(docId: string, options?: MaterializationPlanOptions): Promise<DocumentMaterializationPlan>;
+    planDocumentMaterializationBatch(docIds: string[], options?: MaterializationPlanOptions): Promise<DocumentMaterializationBatchPlan>;
     /**
      * Traverse the dependency graph starting from a given entry id.
      *

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":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAuCG;AAKH,OAAO,EACL,qBAAqB,EACrB,4BAA4B,EAC5B,iBAAiB,EACjB,gBAAgB,EAChB,qBAAqB,EACrB,qBAAqB,EACrB,sBAAsB,EACtB,eAAe,EACf,gBAAgB,EAChB,eAAe,EACf,mBAAmB,EACpB,MAAM,mCAAmC,CAAC;AAE3C,OAAO,KAAK,EAAE,UAAU,EAAE,kBAAkB,EAAE,cAAc,EAAE,MAAM,kBAAkB,CAAC;AACvF,OAAO,EAAE,MAAM,EAAoC,MAAM,oBAAoB,CAAC;AA4G9E;;;;;;;;;;;;;;;;GAgBG;AACH,qBAAa,gCAAiC,YAAW,qBAAqB;IAK5E,wEAAwE;IACxE,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAS;IAE9B,4CAA4C;IAC5C,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAS;IAEhC,6DAA6D;IAC7D,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAS;IAEnC,gEAAgE;IAChE,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAS;IAEpC,2EAA2E;IAC3E,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAS;IAEpC,wDAAwD;IACxD,OAAO,CAAC,QAAQ,CAAC,iBAAiB,CAAS;IAE3C,+DAA+D;IAC/D,OAAO,CAAC,QAAQ,CAAC,mBAAmB,CAAS;IAE7C,2DAA2D;IAC3D,OAAO,CAAC,QAAQ,CAAC,eAAe,CAAU;IAE1C,wEAAwE;IACxE,OAAO,CAAC,QAAQ,CAAC,iCAAiC,CAAS;IAE3D,yEAAyE;IACzE,OAAO,CAAC,QAAQ,CAAC,iCAAiC,CAAS;IAE3D;;;;;OAKG;IACH,OAAO,CAAC,QAAQ,CAAC,2BAA2B,CAAqB;IAEjE,gFAAgF;IAChF,OAAO,CAAC,gBAAgB,CAAwB;IAMhD;;;OAGG;IACH,OAAO,CAAC,WAAW,CAAgB;IAMnC;;;;OAIG;IACH,OAAO,CAAC,OAAO,CAAyC;IAExD;;;OAGG;IACH,OAAO,CAAC,QAAQ,CAAkC;IAElD;;;;OAIG;IACH,OAAO,CAAC,eAAe,CAA6B;IAEpD;;;;OAIG;IACH,OAAO,CAAC,eAAe,CAA4B;IAEnD,wEAAwE;IACxE,OAAO,CAAC,WAAW,CAAwB;IAM3C;;;;;;;;;;;OAWG;gBACS,IAAI,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,gBAAgB;IA6CrE;;;;;;;;;;;;;OAaG;YACW,UAAU;IAsCxB,qFAAqF;YACvE,iBAAiB;IAI/B;;;;OAIG;YACW,yBAAyB;IASvC;;;;;;;;;OASG;YACW,sBAAsB;IA2BpC;;;;;;;;;;OAUG;YACW,qBAAqB;IAiCnC;;;;;;;;;;;;;OAaG;YACW,8BAA8B;IAsB5C;;;;;;OAMG;YACW,oBAAoB;IAQlC;;;;;OAKG;YACW,qBAAqB;IAUnC;;;;;OAKG;YACW,wBAAwB;IAStC;;;;;;;;;;;;OAYG;YACW,sBAAsB;IAwBpC;;;;;;;;;;OAUG;YACW,qBAAqB;IAYnC;;;;;;;;;;;;;;;;OAgBG;YACW,4BAA4B;IAmD1C;;;;OAIG;YACW,6BAA6B;IAkB3C;;;OAGG;IACH,OAAO,CAAC,eAAe;IAOvB;;;;;;OAMG;IACH,OAAO,CAAC,mBAAmB;IAqB3B;;;;OAIG;IACH,OAAO,CAAC,sBAAsB;IAgB9B;;;OAGG;IACH,OAAO,CAAC,qBAAqB;IAc7B;;;OAGG;IACH,OAAO,CAAC,yBAAyB;IAOjC;;;;;;;OAOG;IACH,OAAO,CAAC,mBAAmB;IAmB3B;;;;;;OAMG;IACH,OAAO,CAAC,mBAAmB;IAqB3B,0DAA0D;YAC5C,cAAc;IAS5B,2EAA2E;IAC3E,OAAO,CAAC,iBAAiB;IAIzB,6EAA6E;IAC7E,OAAO,CAAC,kBAAkB;IAI1B,gEAAgE;YAClD,UAAU;IASxB;;;;;;;;;;;OAWG;YACW,eAAe;IAkB7B;;;;;;;;OAQG;YACW,mBAAmB;IAcjC;;;;;;;OAOG;YACW,gBAAgB;IAa9B;;;;OAIG;YACW,sBAAsB;IAYpC;;;;;;OAMG;YACW,eAAe;IAmB7B,yDAAyD;IACzD,KAAK,IAAI,MAAM;IAIf;;;;;;;;;;;;OAYG;IACG,UAAU,CAAC,OAAO,EAAE,UAAU,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC;IAwCtD;;;;;;OAMG;IACG,UAAU,CAAC,GAAG,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,UAAU,EAAE,CAAC;IAsBtD;;;;;;;;OAQG;IACG,UAAU,CAAC,GAAG,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC;IAkBlD;;;;;OAKG;IACG,cAAc,CAAC,QAAQ,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,kBAAkB,EAAE,CAAC;IAOvE;;;;;OAKG;IACG,oBAAoB,CAAC,QAAQ,EAAE,MAAM,EAAE,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,kBAAkB,EAAE,CAAC;IAuB5F;;;;;;;OAOG;IACG,WAAW,CACf,IAAI,EAAE,cAAc,EACpB,gBAAgB,EAAE,MAAM,GAAG,IAAI,EAC/B,iBAAiB,EAAE,MAAM,GAAG,IAAI,GAC/B,OAAO,CAAC,kBAAkB,EAAE,CAAC;IAiBhC;;;;;OAKG;IACG,SAAS,IAAI,OAAO,CAAC,MAAM,EAAE,CAAC;IASpC;;;;;;;;;;;;;;;;;;;;OAoBG;IACG,gBAAgB,CACpB,MAAM,EAAE,eAAe,GAAG,IAAI,EAC9B,KAAK,GAAE,MAAgC,EACvC,OAAO,CAAC,EAAE,gBAAgB,GACzB,OAAO,CAAC,eAAe,CAAC;IAgF3B;;;;;;;;;;;OAWG;IACG,iBAAiB,IAAI,OAAO,CAAC,mBAAmB,CAAC;IAMvD;;;;;;;;;;;;;;;;;;;;;;OAsBG;IACG,mBAAmB,CACvB,OAAO,EAAE,MAAM,EACf,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAChC,OAAO,CAAC,MAAM,EAAE,CAAC;IAiDpB;;;;;;;;;;;;OAYG;IACG,eAAe,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IA8CnD;;;;;;OAMG;IACG,iBAAiB,IAAI,OAAO,CAAC,IAAI,CAAC;IAgBxC;;;;OAIG;IACG,eAAe,CAAC,QAAQ,CAAC,EAAE,sBAAsB,GAAG,OAAO,CAAC,qBAAqB,CAAC;IAKxF,6DAA6D;IAC7D,mBAAmB,IAAI,qBAAqB;IAI5C,8EAA8E;IACxE,mBAAmB,IAAI,OAAO,CAAC,qBAAqB,CAAC;CAG5D;AAED;;;;;;;GAOG;AACH,qBAAa,uCAAwC,YAAW,4BAA4B;IAC1F;;;;;;OAMG;IACH,WAAW,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,gBAAgB,GAAG,iBAAiB;CAKzE"}
+{"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

@@ -77,7 +77,9 @@ exports.BasicOnDiskContentAddressedStoreFactory = exports.BasicOnDiskContentAddr
 const promises_1 = require("fs/promises");
 const fs_1 = require("fs");
 const path = __importStar(require("path"));
+const AttachmentReadPlanner_1 = require("../../core/appendonlystores/AttachmentReadPlanner");
 const bloom_1 = require("../../core/appendonlystores/bloom");
+const MaterializationPlanner_1 = require("../../core/appendonlystores/MaterializationPlanner");
 const logging_1 = require("../../core/logging");
 /**
  * When the number of uncompacted segment files reaches this threshold,
@@ -198,11 +200,13 @@ class BasicOnDiskContentAddressedStore {
          */
         this.contentRefCount = new Map();
         /**
-         * All metadata sorted by `(createdAt ASC, id ASC)`.
+         * All metadata sorted by `(receiptOrder ASC, id ASC)`.
          * Supports O(log N) lower-bound binary search for cursor-based scans
          * in {@link scanEntriesSince}.
          */
         this.orderedMetadata = [];
+        /** Next monotonic local receipt order assigned on insert. */
+        this.nextReceiptOrder = 1;
         this.dbId = dbId;
         this.logger =
             logger ||
@@ -265,6 +269,7 @@ 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 });
+        const migratedReceiptOrder = await this.ensurePersistedReceiptOrder();
         if (!this.indexingEnabled) {
             this.indexStatus = {
                 phase: "ready",
@@ -273,6 +278,17 @@ class BasicOnDiskContentAddressedStore {
             };
             return;
         }
+        if (migratedReceiptOrder) {
+            await this.rebuildInMemoryIndexes();
+            await this.persistMetadataIndex();
+            await this.clearMetadataSegments(Array.from(this.appliedMetadataSegmentFiles));
+            this.indexStatus = {
+                phase: "ready",
+                indexingEnabled: true,
+                progress01: 1,
+            };
+            return;
+        }
         // Startup path:
         // 1) load snapshot (fast path)
         // 2) replay append-only segments (apply recent mutations)
@@ -286,6 +302,7 @@ class BasicOnDiskContentAddressedStore {
             await this.persistMetadataIndex();
             await this.clearMetadataSegments(Array.from(this.appliedMetadataSegmentFiles));
         }
+        this.recomputeNextReceiptOrder();
         this.indexStatus = {
             phase: "ready",
             indexingEnabled: true,
@@ -308,13 +325,14 @@ class BasicOnDiskContentAddressedStore {
         this.contentRefCount.clear();
         this.orderedMetadata = [];
         this.appliedMetadataSegmentFiles.clear();
+        this.nextReceiptOrder = 1;
     }
     /**
      * Full index rebuild from the authoritative entry files on disk.
      *
      * Clears all in-memory structures, reads every `entries/*.json` file,
      * populates the primary, secondary, and ref-count indexes, and finally
-     * sorts `orderedMetadata` by `(createdAt, id)`.
+     * sorts `orderedMetadata` by `(receiptOrder, id)`.
      *
      * This is the slowest startup path (O(N) filesystem reads) and is only
      * used when the persisted snapshot + segments cannot be validated.
@@ -338,7 +356,8 @@ class BasicOnDiskContentAddressedStore {
             this.contentRefCount.set(metadata.contentHash, (this.contentRefCount.get(metadata.contentHash) || 0) + 1);
             this.orderedMetadata.push(metadata);
         }
-        this.orderedMetadata.sort((a, b) => (a.createdAt === b.createdAt ? a.id.localeCompare(b.id) : a.createdAt - b.createdAt));
+        this.orderedMetadata.sort((a, b) => this.compareMetadata(a, b));
+        this.recomputeNextReceiptOrder();
     }
     /**
      * Attempt to hydrate the in-memory index from the persisted
@@ -372,6 +391,8 @@ class BasicOnDiskContentAddressedStore {
                 this.contentRefCount.set(metadata.contentHash, (this.contentRefCount.get(metadata.contentHash) || 0) + 1);
                 this.orderedMetadata.push(metadata);
             }
+            this.orderedMetadata.sort((a, b) => this.compareMetadata(a, b));
+            this.recomputeNextReceiptOrder();
             return true;
         }
         catch (err) {
@@ -594,18 +615,20 @@ class BasicOnDiskContentAddressedStore {
     // In-memory index helpers
     // ---------------------------------------------------------------------------
     /**
-     * Compare two metadata entries by the canonical sort key `(createdAt, id)`.
+     * Compare two metadata entries by the canonical sort key `(receiptOrder, id)`.
      * Used to maintain and query the `orderedMetadata` sorted array.
      */
     compareMetadata(a, b) {
-        if (a.createdAt !== b.createdAt) {
-            return a.createdAt - b.createdAt;
+        const leftReceiptOrder = a.receiptOrder ?? 0;
+        const rightReceiptOrder = b.receiptOrder ?? 0;
+        if (leftReceiptOrder !== rightReceiptOrder) {
+            return leftReceiptOrder - rightReceiptOrder;
         }
         return a.id.localeCompare(b.id);
     }
     /**
      * Binary search for the first index in `orderedMetadata` that is strictly
-     * greater than the given cursor position `(createdAt, id)`.
+     * greater than the given cursor position `(receiptOrder, id)`.
      *
      * Returns 0 when cursor is `null` (start from the beginning).
      * Runs in O(log N) time.
@@ -619,8 +642,8 @@ class BasicOnDiskContentAddressedStore {
         while (left < right) {
             const mid = Math.floor((left + right) / 2);
             const candidate = this.orderedMetadata[mid];
-            const greater = candidate.createdAt > cursor.createdAt ||
-                (candidate.createdAt === cursor.createdAt && candidate.id > cursor.id);
+            const greater = (candidate.receiptOrder ?? 0) > cursor.receiptOrder ||
+                ((candidate.receiptOrder ?? 0) === cursor.receiptOrder && candidate.id > cursor.id);
             if (greater) {
                 right = mid;
             }
@@ -724,6 +747,70 @@ class BasicOnDiskContentAddressedStore {
         this.docIndex.get(metadata.docId).add(metadata.id);
         this.contentRefCount.set(metadata.contentHash, (this.contentRefCount.get(metadata.contentHash) || 0) + 1);
         this.insertOrderedMetadata(metadata);
+        this.nextReceiptOrder = Math.max(this.nextReceiptOrder, (metadata.receiptOrder ?? 0) + 1);
+    }
+    recomputeNextReceiptOrder() {
+        const maxReceiptOrder = this.orderedMetadata.reduce((max, metadata) => Math.max(max, metadata.receiptOrder ?? 0), 0);
+        this.nextReceiptOrder = maxReceiptOrder + 1;
+    }
+    compareLegacyCreatedAtId(a, b) {
+        if (a.createdAt !== b.createdAt) {
+            return a.createdAt - b.createdAt;
+        }
+        return a.id.localeCompare(b.id);
+    }
+    /**
+     * Ensure every persisted metadata file has a `receiptOrder`.
+     *
+     * Older on-disk stores predate receipt-order discovery and therefore only
+     * persist `createdAt`. On startup we detect that legacy shape, assign a
+     * deterministic synthetic `receiptOrder` by sorting existing entries using
+     * the old `(createdAt, id)` rule, and rewrite the metadata files in that
+     * order. This preserves a stable forward cursor contract after migration,
+     * even though the exact historic arrival order is unknowable for preexisting
+     * rows.
+     *
+     * @returns `true` when a backfill rewrite was performed, `false` when the
+     *          store already had receipt-order metadata (or was empty).
+     */
+    async ensurePersistedReceiptOrder() {
+        const files = await this.listEntryFiles();
+        if (files.length === 0) {
+            this.nextReceiptOrder = 1;
+            return false;
+        }
+        const metadataList = [];
+        let missingReceiptOrder = false;
+        let maxReceiptOrder = 0;
+        for (const fileName of files) {
+            const metadata = await this.readMetadataByFileName(fileName);
+            if (!metadata) {
+                continue;
+            }
+            metadataList.push({ fileName, metadata });
+            if (typeof metadata.receiptOrder !== "number") {
+                missingReceiptOrder = true;
+            }
+            else {
+                maxReceiptOrder = Math.max(maxReceiptOrder, metadata.receiptOrder);
+            }
+        }
+        if (!missingReceiptOrder) {
+            this.nextReceiptOrder = maxReceiptOrder + 1;
+            return false;
+        }
+        metadataList.sort((left, right) => this.compareLegacyCreatedAtId(left.metadata, right.metadata));
+        let nextReceiptOrder = 1;
+        for (const { fileName, metadata } of metadataList) {
+            const migrated = {
+                ...metadata,
+                receiptOrder: nextReceiptOrder++,
+            };
+            const filePath = path.join(this.entriesDir, fileName);
+            await this.writeFileAtomic(filePath, JSON.stringify(serializeMetadata(migrated)));
+        }
+        this.nextReceiptOrder = nextReceiptOrder;
+        return true;
     }
     // ---------------------------------------------------------------------------
     // Filesystem I/O helpers
@@ -874,6 +961,9 @@ class BasicOnDiskContentAddressedStore {
     getId() {
         return this.dbId;
     }
+    getCacheIdentity() {
+        return `disk:${this.storeRoot}`;
+    }
     /**
      * Persist one or more entries to disk.
      *
@@ -904,7 +994,11 @@ class BasicOnDiskContentAddressedStore {
             if (!(await this.fileExists(contentPath))) {
                 await this.writeFileAtomic(contentPath, entry.encryptedData);
             }
-            const { encryptedData, ...metadata } = entry;
+            const { encryptedData, receiptOrder: _ignoredReceiptOrder, ...rest } = entry;
+            const metadata = {
+                ...rest,
+                receiptOrder: this.nextReceiptOrder++,
+            };
             const serialized = JSON.stringify(serializeMetadata(metadata));
             await this.writeFileAtomic(metadataPath, serialized);
             hasMutation = true;
@@ -945,6 +1039,14 @@ class BasicOnDiskContentAddressedStore {
         }
         return result;
     }
+    async getEntryMetadata(id) {
+        await this.ensureInitialized();
+        return this.readMetadataById(id);
+    }
+    async planAttachmentReadByWalkingMetadata(lastChunkId, attachmentSize, options) {
+        await this.ensureInitialized();
+        return (0, AttachmentReadPlanner_1.planAttachmentReadByWalkingMetadata)(this, lastChunkId, attachmentSize, options);
+    }
     /**
      * Check which of the given ids exist in the store.
      *
@@ -1036,7 +1138,7 @@ class BasicOnDiskContentAddressedStore {
     /**
      * Return all entry ids in the store.
      *
-     * When indexing is enabled, returns ids in `(createdAt, id)` order.
+     * When indexing is enabled, returns ids in `(receiptOrder, id)` order.
      * Without indexing, order depends on the filesystem directory listing.
      */
     async getAllIds() {
@@ -1052,7 +1154,7 @@ class BasicOnDiskContentAddressedStore {
      *
      * Designed for high-volume synchronization: the caller repeatedly advances
      * a cursor to stream through all entries in deterministic
-     * `(createdAt ASC, id ASC)` order, optionally applying filters.
+     * `(receiptOrder ASC, id ASC)` order, optionally applying filters.
      *
      * **Indexed path** (default):
      * - O(log N) binary search for the cursor position.
@@ -1078,7 +1180,7 @@ class BasicOnDiskContentAddressedStore {
                 const last = page.length > 0 ? page[page.length - 1] : null;
                 return {
                     entries: page,
-                    nextCursor: last ? { createdAt: last.createdAt, id: last.id } : cursor,
+                    nextCursor: last ? { receiptOrder: last.receiptOrder ?? 0, id: last.id } : cursor,
                     hasMore: startIndex + page.length < this.orderedMetadata.length,
                 };
             }
@@ -1102,7 +1204,7 @@ class BasicOnDiskContentAddressedStore {
             const last = page.length > 0 ? page[page.length - 1] : null;
             return {
                 entries: page,
-                nextCursor: last ? { createdAt: last.createdAt, id: last.id } : cursor,
+                nextCursor: last ? { receiptOrder: last.receiptOrder ?? 0, id: last.id } : cursor,
                 hasMore,
             };
         }
@@ -1123,10 +1225,10 @@ class BasicOnDiskContentAddressedStore {
             }
             return true;
         })
-            .sort((a, b) => (a.createdAt === b.createdAt ? a.id.localeCompare(b.id) : a.createdAt - b.createdAt));
+            .sort((a, b) => this.compareMetadata(a, b));
         const startIndex = cursor === null
             ? 0
-            : all.findIndex((meta) => meta.createdAt > cursor.createdAt || (meta.createdAt === cursor.createdAt && meta.id > cursor.id));
+            : all.findIndex((meta) => (meta.receiptOrder ?? 0) > cursor.receiptOrder || ((meta.receiptOrder ?? 0) === cursor.receiptOrder && meta.id > cursor.id));
         if (startIndex === -1) {
             return { entries: [], nextCursor: cursor, hasMore: false };
         }
@@ -1134,7 +1236,7 @@ class BasicOnDiskContentAddressedStore {
         const last = page.length > 0 ? page[page.length - 1] : null;
         return {
             entries: page,
-            nextCursor: last ? { createdAt: last.createdAt, id: last.id } : cursor,
+            nextCursor: last ? { receiptOrder: last.receiptOrder ?? 0, id: last.id } : cursor,
             hasMore: startIndex + page.length < all.length,
         };
     }
@@ -1155,6 +1257,26 @@ class BasicOnDiskContentAddressedStore {
         const ids = await this.getAllIds();
         return (0, bloom_1.createIdBloomSummary)(ids);
     }
+    async planDocumentMaterialization(docId, options) {
+        await this.ensureInitialized();
+        let entries = [];
+        if (this.indexingEnabled) {
+            const ids = this.docIndex.get(docId) || new Set();
+            entries = Array.from(ids)
+                .map((id) => this.entries.get(id))
+                .filter((m) => m !== undefined);
+        }
+        else {
+            const all = await this.listAllMetadata();
+            entries = all.filter((m) => m.docId === docId);
+        }
+        return (0, MaterializationPlanner_1.computeDocumentMaterializationPlan)(docId, entries, options);
+    }
+    async planDocumentMaterializationBatch(docIds, options) {
+        await this.ensureInitialized();
+        const all = await this.listAllMetadata();
+        return (0, MaterializationPlanner_1.computeBatchMaterializationPlan)(all, docIds, options);
+    }
     /**
      * Traverse the dependency graph starting from a given entry id.
      *