mindoodb 0.0.6 → 0.0.8

package/dist/core/BaseMindooDB.js

@@ -8,6 +8,7 @@ const automerge_adapter_1 = require("./automerge-adapter");
 const uuid_1 = require("uuid");
 const bloom_1 = require("./appendonlystores/bloom");
 const MaterializationPlanner_1 = require("./appendonlystores/MaterializationPlanner");
+const DocumentDagAnalysis_1 = require("./DocumentDagAnalysis");
 const AttachmentReadPlanner_1 = require("./appendonlystores/AttachmentReadPlanner");
 const idGeneration_1 = require("./utils/idGeneration");
 const errors_1 = require("./errors");
@@ -1370,6 +1371,245 @@ class BaseMindooDB {
         });
         return result;
     }
+    async analyzeDocumentDagAtTimestamp(docId, timestamp) {
+        const startedAt = Date.now();
+        const resolvedTimestamp = this.resolveDagTimestamp(timestamp);
+        const allEntryMetadata = await this.scanAllMetadata(this.store, { docId });
+        const relevantEntries = allEntryMetadata
+            .filter((entry) => entry.createdAt <= resolvedTimestamp && (0, DocumentDagAnalysis_1.isDagEntry)(entry));
+        const result = (0, DocumentDagAnalysis_1.computeDocumentDagAnalysis)(docId, relevantEntries, resolvedTimestamp);
+        const actorIdByEntryId = await this.decodeAutomergeActorIds(relevantEntries);
+        result.entries = result.entries.map((entry) => ({
+            ...entry,
+            automergeActorId: actorIdByEntryId.get(entry.entryId) ?? null,
+        }));
+        this.performanceCallback?.onHistoryOperation?.({
+            operation: "analyzeDocumentDagAtTimestamp",
+            docId,
+            time: Date.now() - startedAt,
+            scannedEntries: relevantEntries.length,
+            returnedEntries: result.entries.length,
+            bounded: true,
+        });
+        return result;
+    }
+    /**
+     * Decodes Automerge actor ids for replay entries so analysis consumers can color
+     * or group nodes by the logical Automerge actor instead of transport metadata.
+     */
+    async decodeAutomergeActorIds(relevantEntries) {
+        const result = new Map();
+        const replayEntries = relevantEntries.filter((entry) => entry.entryType !== "doc_snapshot");
+        if (replayEntries.length === 0) {
+            return result;
+        }
+        const loadedEntries = await this.store.getEntries(replayEntries.map((entry) => entry.id));
+        const entryById = new Map(loadedEntries.map((entry) => [entry.id, entry]));
+        for (const metadata of replayEntries) {
+            const entry = entryById.get(metadata.id);
+            if (!entry) {
+                result.set(metadata.id, null);
+                continue;
+            }
+            if (this._isAdminOnlyDb && entry.createdByPublicKey !== this.getAdminPublicKey()) {
+                result.set(metadata.id, null);
+                continue;
+            }
+            const isValid = await this.tenant.verifySignature(entry.encryptedData, entry.signature, entry.createdByPublicKey);
+            if (!isValid) {
+                result.set(metadata.id, null);
+                continue;
+            }
+            const decryptedPayload = await this.tenant.decryptPayload(entry.encryptedData, entry.decryptionKeyId);
+            const decodedAutomergeChange = automerge_adapter_1.Automerge.decodeChange(decryptedPayload);
+            result.set(metadata.id, typeof decodedAutomergeChange.actor === "string" ? decodedAutomergeChange.actor : null);
+        }
+        return result;
+    }
+    async materializeDocumentBranchAtEntry(docId, headEntryId) {
+        const startedAt = Date.now();
+        const allEntryMetadata = await this.scanAllMetadata(this.store, { docId });
+        const plan = (0, DocumentDagAnalysis_1.computeBranchMaterializationPlan)(docId, allEntryMetadata, headEntryId);
+        if (!plan) {
+            this.performanceCallback?.onHistoryOperation?.({
+                operation: "materializeDocumentBranchAtEntry",
+                docId,
+                time: Date.now() - startedAt,
+                scannedEntries: allEntryMetadata.length,
+                returnedEntries: 0,
+                bounded: true,
+            });
+            return null;
+        }
+        const metadataById = new Map(allEntryMetadata.map((entry) => [entry.id, entry]));
+        const branchEntries = plan.branchEntryIds
+            .map((entryId) => metadataById.get(entryId))
+            .filter((entry) => entry !== undefined);
+        const internalDoc = await this.materializeDocumentFromPlan(docId, allEntryMetadata, branchEntries, plan.snapshotEntryId, plan.entryIdsToApply, plan.headCreatedAt);
+        this.performanceCallback?.onHistoryOperation?.({
+            operation: "materializeDocumentBranchAtEntry",
+            docId,
+            time: Date.now() - startedAt,
+            scannedEntries: allEntryMetadata.length,
+            returnedEntries: internalDoc ? 1 : 0,
+            bounded: true,
+        });
+        if (!internalDoc) {
+            return null;
+        }
+        return {
+            docId,
+            headEntryId: plan.headEntryId,
+            headCreatedAt: plan.headCreatedAt,
+            headCreatedByPublicKey: plan.headCreatedByPublicKey,
+            snapshotEntryId: plan.snapshotEntryId,
+            entryIdsApplied: [...plan.entryIdsToApply],
+            branchEntryIds: [...plan.branchEntryIds],
+            doc: this.wrapDocument(internalDoc),
+        };
+    }
+    async materializeDocumentBranchAtTimestamp(docId, timestamp, headEntryId) {
+        const startedAt = Date.now();
+        const resolvedTimestamp = this.resolveDagTimestamp(timestamp);
+        const allEntryMetadata = await this.scanAllMetadata(this.store, { docId });
+        const relevantEntries = allEntryMetadata
+            .filter((entry) => entry.createdAt <= resolvedTimestamp && (0, DocumentDagAnalysis_1.isDagEntry)(entry));
+        const plan = (0, DocumentDagAnalysis_1.computeBranchMaterializationPlan)(docId, relevantEntries, headEntryId);
+        if (!plan) {
+            this.performanceCallback?.onHistoryOperation?.({
+                operation: "materializeDocumentBranchAtTimestamp",
+                docId,
+                time: Date.now() - startedAt,
+                scannedEntries: relevantEntries.length,
+                returnedEntries: 0,
+                bounded: true,
+            });
+            return null;
+        }
+        const metadataById = new Map(relevantEntries.map((entry) => [entry.id, entry]));
+        const branchEntries = plan.branchEntryIds
+            .map((entryId) => metadataById.get(entryId))
+            .filter((entry) => entry !== undefined);
+        const internalDoc = await this.materializeDocumentFromPlan(docId, relevantEntries, branchEntries, plan.snapshotEntryId, plan.entryIdsToApply, resolvedTimestamp);
+        this.performanceCallback?.onHistoryOperation?.({
+            operation: "materializeDocumentBranchAtTimestamp",
+            docId,
+            time: Date.now() - startedAt,
+            scannedEntries: relevantEntries.length,
+            returnedEntries: internalDoc ? 1 : 0,
+            bounded: true,
+        });
+        if (!internalDoc) {
+            return null;
+        }
+        return {
+            docId,
+            headEntryId: plan.headEntryId,
+            headCreatedAt: plan.headCreatedAt,
+            headCreatedByPublicKey: plan.headCreatedByPublicKey,
+            snapshotEntryId: plan.snapshotEntryId,
+            entryIdsApplied: [...plan.entryIdsToApply],
+            branchEntryIds: [...plan.branchEntryIds],
+            doc: this.wrapDocument(internalDoc),
+        };
+    }
+    async describeDocumentDagEntry(docId, entryId) {
+        const startedAt = Date.now();
+        const metadata = await this.store.getEntryMetadata(entryId);
+        if (!metadata || metadata.docId !== docId || !(0, DocumentDagAnalysis_1.isDagEntry)(metadata)) {
+            this.performanceCallback?.onHistoryOperation?.({
+                operation: "describeDocumentDagEntry",
+                docId,
+                time: Date.now() - startedAt,
+                scannedEntries: metadata ? 1 : 0,
+                returnedEntries: 0,
+                bounded: true,
+            });
+            return null;
+        }
+        let decodedChange = null;
+        if (metadata.entryType !== "doc_snapshot") {
+            const allEntryMetadata = await this.scanAllMetadata(this.store, { docId });
+            const entries = await this.store.getEntries([entryId]);
+            const entry = entries[0];
+            if (entry) {
+                let isValid = false;
+                if (this._isAdminOnlyDb && entry.createdByPublicKey !== this.getAdminPublicKey()) {
+                    this.logger.warn(`Admin-only DB: skipping DAG details for ${entry.id} not signed by admin key`);
+                }
+                else {
+                    isValid = await this.tenant.verifySignature(entry.encryptedData, entry.signature, entry.createdByPublicKey);
+                }
+                if (isValid) {
+                    const decryptedPayload = await this.tenant.decryptPayload(entry.encryptedData, entry.decryptionKeyId);
+                    const decodedAutomergeChange = automerge_adapter_1.Automerge.decodeChange(decryptedPayload);
+                    decodedChange = this.summarizeDecodedChange(decodedAutomergeChange);
+                    decodedChange.touchedPaths = await this.deriveReadableTouchedPaths(docId, metadata, allEntryMetadata, decodedChange.touchedKeys);
+                }
+            }
+        }
+        const parsed = (0, idGeneration_1.parseDocEntryId)(metadata.id);
+        const result = {
+            docId,
+            entryId: metadata.id,
+            entryType: metadata.entryType,
+            createdAt: metadata.createdAt,
+            createdByPublicKey: metadata.createdByPublicKey,
+            dependencyIds: [...metadata.dependencyIds],
+            snapshotHeadEntryIds: [...(metadata.snapshotHeadEntryIds ?? [])],
+            snapshotHeadHashes: [...(metadata.snapshotHeadHashes ?? [])],
+            automergeHash: parsed?.automergeHash ?? null,
+            decodedChange,
+        };
+        this.performanceCallback?.onHistoryOperation?.({
+            operation: "describeDocumentDagEntry",
+            docId,
+            time: Date.now() - startedAt,
+            scannedEntries: 1,
+            returnedEntries: 1,
+            bounded: true,
+        });
+        return result;
+    }
+    /**
+     * Derives human-readable changed field paths for one DAG entry.
+     *
+     * This compares the branch-local document state at the selected entry with each
+     * reachable parent state, then normalizes array indices so the UI can show stable
+     * paths such as `_attachments[].fileName` instead of raw Automerge op keys only.
+     */
+    async deriveReadableTouchedPaths(docId, entryMetadata, allEntryMetadata, touchedKeys) {
+        if (entryMetadata.entryType === "doc_snapshot") {
+            return [];
+        }
+        const currentDoc = await this.materializeBranchInternalDoc(docId, allEntryMetadata, entryMetadata.id);
+        const currentData = this.getReadableDiffValueForDoc(currentDoc);
+        const parentEntryIds = entryMetadata.dependencyIds.filter((dependencyId) => allEntryMetadata.some((entry) => entry.id === dependencyId));
+        const diffPaths = new Set();
+        if (parentEntryIds.length === 0) {
+            this.collectReadableDiffPaths(undefined, currentData, "", diffPaths);
+        }
+        else {
+            for (const parentEntryId of parentEntryIds) {
+                const parentDoc = await this.materializeBranchInternalDoc(docId, allEntryMetadata, parentEntryId);
+                const parentData = this.getReadableDiffValueForDoc(parentDoc);
+                this.collectReadableDiffPaths(parentData, currentData, "", diffPaths);
+            }
+        }
+        const normalizedPaths = Array.from(diffPaths)
+            .map((path) => path.replace(/\[\d+\]/g, "[]"))
+            .filter((path, index, allPaths) => path.length > 0 && allPaths.indexOf(path) === index)
+            .sort();
+        if (normalizedPaths.length === 0) {
+            return [];
+        }
+        const touchedKeySet = new Set(touchedKeys);
+        if (touchedKeySet.size === 0) {
+            return normalizedPaths;
+        }
+        const filteredPaths = normalizedPaths.filter((path) => touchedKeySet.has(this.extractLeafPathSegment(path)));
+        return filteredPaths.length > 0 ? filteredPaths : normalizedPaths;
+    }
     async getAllDocumentIds() {
         // Return all non-deleted document IDs from index
         const docIds = [];
@@ -1988,6 +2228,261 @@ class BaseMindooDB {
         }
         return startIndex;
     }
+    resolveDagTimestamp(timestamp) {
+        return timestamp === "now" ? Date.now() : timestamp;
+    }
+    previewChangeValue(value) {
+        if (value === undefined) {
+            return null;
+        }
+        if (typeof value === "string") {
+            return value.length > 80 ? `${value.slice(0, 77)}...` : value;
+        }
+        if (typeof value === "number" || typeof value === "boolean") {
+            return String(value);
+        }
+        if (value === null) {
+            return "null";
+        }
+        try {
+            const serialized = JSON.stringify(value);
+            if (!serialized) {
+                return null;
+            }
+            return serialized.length > 80 ? `${serialized.slice(0, 77)}...` : serialized;
+        }
+        catch {
+            return String(value);
+        }
+    }
+    /**
+     * Materializes a single branch-local document state for a specific DAG head.
+     *
+     * This is the internal building block used by DAG inspection helpers when they
+     * need the document exactly as that branch would have looked at `headEntryId`.
+     */
+    async materializeBranchInternalDoc(docId, allEntryMetadata, headEntryId) {
+        const plan = (0, DocumentDagAnalysis_1.computeBranchMaterializationPlan)(docId, allEntryMetadata, headEntryId);
+        if (!plan) {
+            return null;
+        }
+        const metadataById = new Map(allEntryMetadata.map((entry) => [entry.id, entry]));
+        const branchEntries = plan.branchEntryIds
+            .map((entryId) => metadataById.get(entryId))
+            .filter((entry) => entry !== undefined);
+        return this.materializeDocumentFromPlan(docId, allEntryMetadata, branchEntries, plan.snapshotEntryId, plan.entryIdsToApply, plan.headCreatedAt);
+    }
+    /**
+     * Converts an internal doc into a plain JS value that is safe to diff for UI summaries.
+     *
+     * Deleted or missing docs are normalized to `undefined` so the diff code can treat
+     * creation/deletion as ordinary before/after transitions.
+     */
+    getReadableDiffValueForDoc(internalDoc) {
+        if (!internalDoc || internalDoc.isDeleted) {
+            return undefined;
+        }
+        return this.wrapDocument(internalDoc).getData();
+    }
+    /**
+     * Walks two plain JS values and records the changed field paths.
+     *
+     * Arrays are tracked by index first and later normalized to `[]` for display,
+     * which keeps attachment-style changes readable in the DAG explorer.
+     */
+    collectReadableDiffPaths(beforeValue, afterValue, basePath, results) {
+        if (Object.is(beforeValue, afterValue)) {
+            return;
+        }
+        if (Array.isArray(beforeValue) || Array.isArray(afterValue)) {
+            const beforeArray = Array.isArray(beforeValue) ? beforeValue : [];
+            const afterArray = Array.isArray(afterValue) ? afterValue : [];
+            const maxLength = Math.max(beforeArray.length, afterArray.length);
+            if (maxLength === 0 && basePath) {
+                results.add(basePath);
+                return;
+            }
+            for (let index = 0; index < maxLength; index++) {
+                this.collectReadableDiffPaths(beforeArray[index], afterArray[index], `${basePath}[${index}]`, results);
+            }
+            return;
+        }
+        if (this.isPlainDiffObject(beforeValue) || this.isPlainDiffObject(afterValue)) {
+            const beforeObject = this.isPlainDiffObject(beforeValue) ? beforeValue : {};
+            const afterObject = this.isPlainDiffObject(afterValue) ? afterValue : {};
+            const childKeys = new Set([...Object.keys(beforeObject), ...Object.keys(afterObject)]);
+            if (childKeys.size === 0 && basePath) {
+                results.add(basePath);
+                return;
+            }
+            for (const key of childKeys) {
+                const nextPath = basePath ? `${basePath}.${key}` : key;
+                this.collectReadableDiffPaths(beforeObject[key], afterObject[key], nextPath, results);
+            }
+            return;
+        }
+        if (basePath) {
+            results.add(basePath);
+        }
+    }
+    /**
+     * Returns true for diffable object literals and false for arrays/binary payloads.
+     */
+    isPlainDiffObject(value) {
+        return value !== null
+            && typeof value === "object"
+            && !Array.isArray(value)
+            && !(value instanceof Uint8Array);
+    }
+    /**
+     * Extracts the terminal field name from a normalized path for loose key/path matching.
+     */
+    extractLeafPathSegment(path) {
+        const normalizedPath = path.replace(/\[\]/g, "");
+        const segments = normalizedPath.split(".");
+        return segments[segments.length - 1] ?? normalizedPath;
+    }
+    /**
+     * Produces a compact, UI-oriented summary of a decoded Automerge change.
+     *
+     * The raw Automerge ops are reduced to counts, touched keys, and a short list of
+     * previewable operations so Haven can show useful change context without dumping
+     * the full decoded structure.
+     */
+    summarizeDecodedChange(decodedChange) {
+        const operations = Array.isArray(decodedChange.ops) ? decodedChange.ops : [];
+        const actionCounts = {};
+        const touchedKeys = new Set();
+        const summarizedOperations = operations.slice(0, 12).map((operation) => {
+            const op = operation;
+            const action = typeof op.action === "string" ? op.action : "unknown";
+            actionCounts[action] = (actionCounts[action] ?? 0) + 1;
+            const key = typeof op.key === "string"
+                ? op.key
+                : typeof op.elemId === "string"
+                    ? op.elemId
+                    : null;
+            if (typeof op.key === "string") {
+                touchedKeys.add(op.key);
+            }
+            return {
+                action,
+                key,
+                obj: typeof op.obj === "string" ? op.obj : null,
+                insert: typeof op.insert === "boolean" ? op.insert : undefined,
+                valuePreview: this.previewChangeValue(op.value),
+            };
+        });
+        for (const operation of operations.slice(12)) {
+            const op = operation;
+            const action = typeof op.action === "string" ? op.action : "unknown";
+            actionCounts[action] = (actionCounts[action] ?? 0) + 1;
+            if (typeof op.key === "string") {
+                touchedKeys.add(op.key);
+            }
+        }
+        return {
+            actorId: typeof decodedChange.actor === "string" ? decodedChange.actor : null,
+            hash: typeof decodedChange.hash === "string" ? decodedChange.hash : null,
+            seq: typeof decodedChange.seq === "number" ? decodedChange.seq : null,
+            message: typeof decodedChange.message === "string" ? decodedChange.message : null,
+            dependencyHashes: Array.isArray(decodedChange.deps)
+                ? decodedChange.deps.filter((dep) => typeof dep === "string")
+                : [],
+            opCount: operations.length,
+            actionCounts,
+            touchedKeys: Array.from(touchedKeys).sort(),
+            touchedPaths: [],
+            operations: summarizedOperations,
+        };
+    }
+    /**
+     * Rebuilds a document from a materialization plan produced by the DAG/history planners.
+     *
+     * The plan may start from a compatible snapshot and then replay incremental changes,
+     * or fall back to a full replay if no usable snapshot is available.
+     */
+    async materializeDocumentFromPlan(docId, allEntryMetadata, replayEntriesForState, snapshotEntryId, entryIdsToApply, fallbackTimestamp) {
+        if (replayEntriesForState.length === 0 && !snapshotEntryId) {
+            return null;
+        }
+        const metadataById = new Map(allEntryMetadata.map((entry) => [entry.id, entry]));
+        let startFromSnapshot = snapshotEntryId !== null;
+        const snapshotMeta = snapshotEntryId ? (metadataById.get(snapshotEntryId) || null) : null;
+        if (startFromSnapshot && !snapshotMeta) {
+            this.logger.warn(`Materialization referenced snapshot ${snapshotEntryId} not found in metadata for ${docId}; falling back to replay without snapshot`);
+            startFromSnapshot = false;
+        }
+        let doc = undefined;
+        if (startFromSnapshot && snapshotMeta) {
+            const snapshotEntries = await this.store.getEntries([snapshotMeta.id]);
+            if (snapshotEntries.length > 0) {
+                const snapshotData = snapshotEntries[0];
+                let isValid = false;
+                if (this._isAdminOnlyDb && snapshotData.createdByPublicKey !== this.getAdminPublicKey()) {
+                    this.logger.warn(`Admin-only DB: skipping snapshot ${snapshotData.id} not signed by admin key`);
+                }
+                else {
+                    isValid = await this.tenant.verifySignature(snapshotData.encryptedData, snapshotData.signature, snapshotData.createdByPublicKey);
+                }
+                if (!isValid) {
+                    this.logger.warn(`Invalid signature for snapshot ${snapshotData.id}, falling back to replay without snapshot`);
+                    startFromSnapshot = false;
+                }
+                else {
+                    const decryptedSnapshot = await this.tenant.decryptPayload(snapshotData.encryptedData, snapshotData.decryptionKeyId);
+                    doc = automerge_adapter_1.Automerge.load(decryptedSnapshot);
+                    const parsed = (0, idGeneration_1.parseDocEntryId)(snapshotData.id);
+                    if (parsed) {
+                        this.registerAutomergeHashMapping(docId, parsed.automergeHash, snapshotData.id);
+                    }
+                }
+            }
+        }
+        if (!doc) {
+            doc = automerge_adapter_1.Automerge.init();
+        }
+        const entriesToApply = entryIdsToApply
+            .map((id) => metadataById.get(id))
+            .filter((entry) => entry !== undefined);
+        const loadedEntries = entriesToApply.length > 0
+            ? await this.store.getEntries(entriesToApply.map((entry) => entry.id))
+            : [];
+        const entryById = new Map(loadedEntries.map((entry) => [entry.id, entry]));
+        for (const entryMeta of entriesToApply) {
+            const entryData = entryById.get(entryMeta.id);
+            if (!entryData) {
+                this.logger.warn(`Entry ${entryMeta.id} not found in store, skipping`);
+                continue;
+            }
+            if (this._isAdminOnlyDb && entryData.createdByPublicKey !== this.getAdminPublicKey()) {
+                this.logger.warn(`Admin-only DB: skipping entry ${entryData.id} not signed by admin key`);
+                continue;
+            }
+            const isValid = await this.tenant.verifySignature(entryData.encryptedData, entryData.signature, entryData.createdByPublicKey);
+            if (!isValid) {
+                this.logger.warn(`Invalid signature for entry ${entryData.id}, skipping`);
+                continue;
+            }
+            const decryptedPayload = await this.tenant.decryptPayload(entryData.encryptedData, entryData.decryptionKeyId);
+            doc = automerge_adapter_1.Automerge.loadIncremental(doc, decryptedPayload);
+            const parsed = (0, idGeneration_1.parseDocEntryId)(entryData.id);
+            if (parsed) {
+                this.registerAutomergeHashMapping(docId, parsed.automergeHash, entryData.id);
+            }
+        }
+        const orderedReplayEntries = [...replayEntriesForState].sort((left, right) => left.createdAt !== right.createdAt ? left.createdAt - right.createdAt : left.id.localeCompare(right.id));
+        const firstReplayEntry = orderedReplayEntries[0] ?? null;
+        const lastReplayEntry = orderedReplayEntries[orderedReplayEntries.length - 1] ?? null;
+        return {
+            id: docId,
+            doc,
+            createdAt: firstReplayEntry?.createdAt ?? snapshotMeta?.createdAt ?? fallbackTimestamp,
+            lastModified: lastReplayEntry?.createdAt ?? snapshotMeta?.createdAt ?? fallbackTimestamp,
+            decryptionKeyId: firstReplayEntry?.decryptionKeyId ?? snapshotMeta?.decryptionKeyId ?? "default",
+            isDeleted: lastReplayEntry?.entryType === "doc_delete",
+        };
+    }
     async *iterateChangeMetadataSince(cursor) {
         const startedAt = Date.now();
         const actualCursor = cursor ?? {