@forestrie/merklelog 0.0.2 → 0.1.0

package/dist/index.d.ts

@@ -12,10 +12,16 @@ export type { MassifStart, LeafComponent, LeafEnumeratorSpec, LeafEntry, } from
 export { MassifStartFmt } from "./massifs/types.js";
 export { LogFormat, Urkle, Bloom, IndexV2, leafCountForMassifHeight, leafTableBytes, nodeCountMax, nodeStoreBytes, bloomMBits, bloomBitsetBytes, bloomRegionBytes, indexDataBytesV2, peakStackEnd, massifLogEntries, urkleLeafTableStartFieldIndex, urkleLeafTableStartByteOffset, createLeafEnumerator, leafComponentByteOffset, leafComponentSize, computeLastMMRIndex, isMassifFull, } from "./massifs/types.js";
 export { parseV2StorageObjectPath } from "./massifs/v2storagepaths.js";
+export { openMassifNodeStore } from "./massifs/nodestore.js";
+export type { MassifNodeStore } from "./massifs/nodestore.js";
+export { openMassifLeafIndex, MissingIndexError } from "./massifs/leafindex.js";
+export type { MassifLeafIndex } from "./massifs/leafindex.js";
 export { mmrIndex, massifFirstLeaf, leafMinusSpurSum } from "./mmr/index.js";
 export { heightIndex, height, mmrIndexFromLeafIndex, leafIndex, mmrPosition, mmrSizeFromHeightIndex, leafCount, leafCountFromHeightIndex, } from "./mmr/math.js";
 export { bagPeaks, calculateRoot, verifyInclusion, verifyConsistency, } from "./mmr/algorithms.js";
 export { createSyncHasher } from "./mmr/algorithms-sync.js";
 export type { Proof, Peak } from "./mmr/types.js";
 export type { Hasher } from "./mmr/types.js";
+export { inclusionProof, peakMMRIndexes, peaksBitmap, peakIndexForLeafProof, indexHeight, firstMMRSize, massifIndexFromMMRIndex, peakStackMap, } from "./mmr/proof.js";
+export type { NodeGetter } from "./mmr/proof.js";
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAGH,OAAO,EAAE,MAAM,EAAE,MAAM,mBAAmB,CAAC;AAG3C,OAAO,EAAE,MAAM,EAAE,MAAM,qBAAqB,CAAC;AAC7C,YAAY,EACV,WAAW,EACX,aAAa,EACb,kBAAkB,EAClB,SAAS,GACV,MAAM,oBAAoB,CAAC;AAC5B,OAAO,EAAE,cAAc,EAAE,MAAM,oBAAoB,CAAC;AACpD,OAAO,EACL,SAAS,EACT,KAAK,EACL,KAAK,EACL,OAAO,EACP,wBAAwB,EACxB,cAAc,EACd,YAAY,EACZ,cAAc,EACd,UAAU,EACV,gBAAgB,EAChB,gBAAgB,EAChB,gBAAgB,EAChB,YAAY,EACZ,gBAAgB,EAChB,6BAA6B,EAC7B,6BAA6B,EAC7B,oBAAoB,EACpB,uBAAuB,EACvB,iBAAiB,EACjB,mBAAmB,EACnB,YAAY,GACb,MAAM,oBAAoB,CAAC;AAE5B,OAAO,EAAE,wBAAwB,EAAE,MAAM,6BAA6B,CAAC;AAGvE,OAAO,EAAE,QAAQ,EAAE,eAAe,EAAE,gBAAgB,EAAE,MAAM,gBAAgB,CAAC;AAC7E,OAAO,EACL,WAAW,EACX,MAAM,EACN,qBAAqB,EACrB,SAAS,EACT,WAAW,EACX,sBAAsB,EACtB,SAAS,EACT,wBAAwB,GACzB,MAAM,eAAe,CAAC;AACvB,OAAO,EACL,QAAQ,EACR,aAAa,EACb,eAAe,EACf,iBAAiB,GAClB,MAAM,qBAAqB,CAAC;AAC7B,OAAO,EAAE,gBAAgB,EAAE,MAAM,0BAA0B,CAAC;AAC5D,YAAY,EAAE,KAAK,EAAE,IAAI,EAAE,MAAM,gBAAgB,CAAC;AAClD,YAAY,EAAE,MAAM,EAAE,MAAM,gBAAgB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAGH,OAAO,EAAE,MAAM,EAAE,MAAM,mBAAmB,CAAC;AAG3C,OAAO,EAAE,MAAM,EAAE,MAAM,qBAAqB,CAAC;AAC7C,YAAY,EACV,WAAW,EACX,aAAa,EACb,kBAAkB,EAClB,SAAS,GACV,MAAM,oBAAoB,CAAC;AAC5B,OAAO,EAAE,cAAc,EAAE,MAAM,oBAAoB,CAAC;AACpD,OAAO,EACL,SAAS,EACT,KAAK,EACL,KAAK,EACL,OAAO,EACP,wBAAwB,EACxB,cAAc,EACd,YAAY,EACZ,cAAc,EACd,UAAU,EACV,gBAAgB,EAChB,gBAAgB,EAChB,gBAAgB,EAChB,YAAY,EACZ,gBAAgB,EAChB,6BAA6B,EAC7B,6BAA6B,EAC7B,oBAAoB,EACpB,uBAAuB,EACvB,iBAAiB,EACjB,mBAAmB,EACnB,YAAY,GACb,MAAM,oBAAoB,CAAC;AAE5B,OAAO,EAAE,wBAAwB,EAAE,MAAM,6BAA6B,CAAC;AAGvE,OAAO,EAAE,mBAAmB,EAAE,MAAM,wBAAwB,CAAC;AAC7D,YAAY,EAAE,eAAe,EAAE,MAAM,wBAAwB,CAAC;AAG9D,OAAO,EAAE,mBAAmB,EAAE,iBAAiB,EAAE,MAAM,wBAAwB,CAAC;AAChF,YAAY,EAAE,eAAe,EAAE,MAAM,wBAAwB,CAAC;AAG9D,OAAO,EAAE,QAAQ,EAAE,eAAe,EAAE,gBAAgB,EAAE,MAAM,gBAAgB,CAAC;AAC7E,OAAO,EACL,WAAW,EACX,MAAM,EACN,qBAAqB,EACrB,SAAS,EACT,WAAW,EACX,sBAAsB,EACtB,SAAS,EACT,wBAAwB,GACzB,MAAM,eAAe,CAAC;AACvB,OAAO,EACL,QAAQ,EACR,aAAa,EACb,eAAe,EACf,iBAAiB,GAClB,MAAM,qBAAqB,CAAC;AAC7B,OAAO,EAAE,gBAAgB,EAAE,MAAM,0BAA0B,CAAC;AAC5D,YAAY,EAAE,KAAK,EAAE,IAAI,EAAE,MAAM,gBAAgB,CAAC;AAClD,YAAY,EAAE,MAAM,EAAE,MAAM,gBAAgB,CAAC;AAG7C,OAAO,EACL,cAAc,EACd,cAAc,EACd,WAAW,EACX,qBAAqB,EACrB,WAAW,EACX,YAAY,EACZ,uBAAuB,EACvB,YAAY,GACb,MAAM,gBAAgB,CAAC;AACxB,YAAY,EAAE,UAAU,EAAE,MAAM,gBAAgB,CAAC"}

package/dist/index.js

@@ -13,8 +13,14 @@ export { Massif } from "./massifs/massif.js";
 export { MassifStartFmt } from "./massifs/types.js";
 export { LogFormat, Urkle, Bloom, IndexV2, leafCountForMassifHeight, leafTableBytes, nodeCountMax, nodeStoreBytes, bloomMBits, bloomBitsetBytes, bloomRegionBytes, indexDataBytesV2, peakStackEnd, massifLogEntries, urkleLeafTableStartFieldIndex, urkleLeafTableStartByteOffset, createLeafEnumerator, leafComponentByteOffset, leafComponentSize, computeLastMMRIndex, isMassifFull, } from "./massifs/types.js";
 export { parseV2StorageObjectPath } from "./massifs/v2storagepaths.js";
+// Massif blob node access for MMR proof building (plan-2607-15 §4)
+export { openMassifNodeStore } from "./massifs/nodestore.js";
+// Content-hash leaf lookup over the massif index region (FOR-373)
+export { openMassifLeafIndex, MissingIndexError } from "./massifs/leafindex.js";
 // Export mmr module
 export { mmrIndex, massifFirstLeaf, leafMinusSpurSum } from "./mmr/index.js";
 export { heightIndex, height, mmrIndexFromLeafIndex, leafIndex, mmrPosition, mmrSizeFromHeightIndex, leafCount, leafCountFromHeightIndex, } from "./mmr/math.js";
 export { bagPeaks, calculateRoot, verifyInclusion, verifyConsistency, } from "./mmr/algorithms.js";
 export { createSyncHasher } from "./mmr/algorithms-sync.js";
+// MMR proof building (pure; store-agnostic) — plan-2607-15 §4 (go: mmr/proof.go, peaks.go)
+export { inclusionProof, peakMMRIndexes, peaksBitmap, peakIndexForLeafProof, indexHeight, firstMMRSize, massifIndexFromMMRIndex, peakStackMap, } from "./mmr/proof.js";

package/dist/massifs/leafindex.d.ts

@@ -0,0 +1,47 @@
+/**
+ * Content-hash → mmrIndex leaf lookup over a v2 massif index region (FOR-373).
+ *
+ * The v2 massif index region carries, per leaf ordinal, a fixed-width record
+ * whose committed `valueBytes[32]` is the leaf's content hash — the same value
+ * committed by the urkle trie (go-merklelog `urkle/leafrecord.go`,
+ * `massifs/indexformat_v2.go`; plan-2607-15 §1.1). The urkle trie itself is
+ * keyed by the 8-byte leaf key (idtimestamp) for duplicate/exclusion detection,
+ * so content-hash resolution reads the leaf table's value column directly and
+ * maps the matching ordinal back to an MMR index
+ * (`urkle.LeafOrdinalToMMRIndex`).
+ *
+ * This lets `forestrie create-receipt --content-hash <hex>` locate a leaf's
+ * mmrIndex from a massif blob alone, with no external mapping. A negative
+ * lookup (`null`) is distinguishable from absence-of-index: a blob with no
+ * index region throws `MissingIndexError`, while a searched-but-not-present
+ * hash returns `null`.
+ *
+ * Browser-safe: pure buffer arithmetic, no node builtins (ADR-0048).
+ */
+/**
+ * Thrown when the blob carries no populated index region, so a content-hash
+ * lookup cannot even be attempted. Callers distinguish this from a `null`
+ * (searched, not found) result.
+ */
+export declare class MissingIndexError extends Error {
+    constructor(message: string);
+}
+/** Content-hash leaf lookup over one massif blob (FOR-373). */
+export interface MassifLeafIndex {
+    /**
+     * MMR index of the leaf whose committed content hash equals `h`, or `null`
+     * when no populated leaf in this massif carries that hash. `h` must be 32
+     * bytes.
+     */
+    findByContentHash(h: Uint8Array): bigint | null;
+    /** Number of populated leaves in this blob. */
+    leafCount: number;
+}
+/**
+ * Open a v2 massif blob for content-hash leaf lookups.
+ *
+ * @throws MissingIndexError if the blob is too short to contain the fixed index
+ *   region for its declared massif height (no index present).
+ */
+export declare function openMassifLeafIndex(massifBytes: Uint8Array): MassifLeafIndex;
+//# sourceMappingURL=leafindex.d.ts.map

package/dist/massifs/leafindex.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"leafindex.d.ts","sourceRoot":"","sources":["../../src/massifs/leafindex.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAeH;;;;GAIG;AACH,qBAAa,iBAAkB,SAAQ,KAAK;gBAC9B,OAAO,EAAE,MAAM;CAI5B;AAED,+DAA+D;AAC/D,MAAM,WAAW,eAAe;IAC9B;;;;OAIG;IACH,iBAAiB,CAAC,CAAC,EAAE,UAAU,GAAG,MAAM,GAAG,IAAI,CAAC;IAChD,+CAA+C;IAC/C,SAAS,EAAE,MAAM,CAAC;CACnB;AAkBD;;;;;GAKG;AACH,wBAAgB,mBAAmB,CAAC,WAAW,EAAE,UAAU,GAAG,eAAe,CA+D5E"}

package/dist/massifs/leafindex.js

@@ -0,0 +1,117 @@
+/**
+ * Content-hash → mmrIndex leaf lookup over a v2 massif index region (FOR-373).
+ *
+ * The v2 massif index region carries, per leaf ordinal, a fixed-width record
+ * whose committed `valueBytes[32]` is the leaf's content hash — the same value
+ * committed by the urkle trie (go-merklelog `urkle/leafrecord.go`,
+ * `massifs/indexformat_v2.go`; plan-2607-15 §1.1). The urkle trie itself is
+ * keyed by the 8-byte leaf key (idtimestamp) for duplicate/exclusion detection,
+ * so content-hash resolution reads the leaf table's value column directly and
+ * maps the matching ordinal back to an MMR index
+ * (`urkle.LeafOrdinalToMMRIndex`).
+ *
+ * This lets `forestrie create-receipt --content-hash <hex>` locate a leaf's
+ * mmrIndex from a massif blob alone, with no external mapping. A negative
+ * lookup (`null`) is distinguishable from absence-of-index: a blob with no
+ * index region throws `MissingIndexError`, while a searched-but-not-present
+ * hash returns `null`.
+ *
+ * Browser-safe: pure buffer arithmetic, no node builtins (ADR-0048).
+ */
+import { Massif } from "./massif.js";
+import { LogFormat } from "./logformat.js";
+import { Urkle, leafCountForMassifHeight } from "./indexformat.js";
+import { urkleLeafTableStartByteOffset } from "./urkleindex.js";
+import { peakStackEnd } from "./peakstackend.js";
+import { massifLogEntries } from "./massiflogentries.js";
+import { firstMMRSize, peaksBitmap } from "../mmr/proof.js";
+import { mmrIndex as mmrIndexFromLeafIndex } from "../mmr/index.js";
+const HASH_BYTES = Urkle.LeafValueBytes; // 32
+const VALUE_OFFSET = Urkle.LeafValueOffset; // 8 (after the 8-byte key)
+const RECORD_BYTES = Urkle.LeafRecordBytes; // 128
+/**
+ * Thrown when the blob carries no populated index region, so a content-hash
+ * lookup cannot even be attempted. Callers distinguish this from a `null`
+ * (searched, not found) result.
+ */
+export class MissingIndexError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "MissingIndexError";
+    }
+}
+function equals32(a, aOff, b) {
+    for (let i = 0; i < HASH_BYTES; i++) {
+        if (a[aOff + i] !== b[i])
+            return false;
+    }
+    return true;
+}
+/**
+ * Leaf index of the first leaf in the massif whose first MMR index is
+ * `firstMMRIndex`. (go-merklelog `mmr/leafcount.go` LeafIndex)
+ */
+function leafIndexFromMMRIndex(firstMMRIndex) {
+    if (firstMMRIndex === 0n)
+        return 0n;
+    return peaksBitmap(firstMMRSize(firstMMRIndex)) - 1n;
+}
+/**
+ * Open a v2 massif blob for content-hash leaf lookups.
+ *
+ * @throws MissingIndexError if the blob is too short to contain the fixed index
+ *   region for its declared massif height (no index present).
+ */
+export function openMassifLeafIndex(massifBytes) {
+    const massif = new Massif(massifBytes);
+    const start = massif.getStart();
+    const massifHeight = start.massifHeight;
+    if (!Number.isInteger(massifHeight) ||
+        massifHeight < 1 ||
+        massifHeight > LogFormat.MaxMmrHeight) {
+        throw new Error(`massif header has invalid height ${massifHeight}`);
+    }
+    const firstIndex = start.firstIndex;
+    const leafTableStart = urkleLeafTableStartByteOffset(massifHeight);
+    const capacity = Number(leafCountForMassifHeight(massifHeight));
+    const leafTableBytes = capacity * RECORD_BYTES;
+    const stackEnd = peakStackEnd(massifHeight);
+    // The index region must fit before the fixed peak stack + log region. A blob
+    // shorter than that has no populated index to search.
+    if (massifHeight > 1 && BigInt(leafTableStart + leafTableBytes) > stackEnd) {
+        throw new Error("massif index region math is inconsistent");
+    }
+    if (BigInt(massifBytes.byteLength) < stackEnd) {
+        throw new MissingIndexError("massif blob too short for a v2 index region (no index present)");
+    }
+    // Only leaves actually appended have populated records. Derive the populated
+    // leaf count from the log node count (index records are written 1:1 with
+    // appended leaves). Never exceed the fixed capacity for the height.
+    const logNodeCount = massifLogEntries(massifBytes.byteLength, massifHeight);
+    const firstLeafIndex = leafIndexFromMMRIndex(firstIndex);
+    let populated = 0;
+    for (let ordinal = 0; ordinal < capacity; ordinal++) {
+        // MMR index of leaf (firstLeafIndex + ordinal), relative to this blob's
+        // firstIndex, must be within the log node count.
+        const leafMMRIndex = mmrIndexFromLeafIndex(firstLeafIndex + BigInt(ordinal));
+        if (leafMMRIndex - firstIndex >= logNodeCount)
+            break;
+        populated = ordinal + 1;
+    }
+    const findByContentHash = (h) => {
+        if (h.length !== HASH_BYTES) {
+            throw new Error(`content hash must be ${HASH_BYTES} bytes, got ${h.length}`);
+        }
+        for (let ordinal = 0; ordinal < populated; ordinal++) {
+            const recordOff = leafTableStart + ordinal * RECORD_BYTES;
+            const valueOff = recordOff + VALUE_OFFSET;
+            if (valueOff + HASH_BYTES > massifBytes.byteLength)
+                break;
+            if (equals32(massifBytes, valueOff, h)) {
+                return mmrIndexFromLeafIndex(firstLeafIndex + BigInt(ordinal));
+            }
+        }
+        return null;
+    };
+    return { findByContentHash, leafCount: populated };
+}

package/dist/massifs/nodestore.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Massif blob node access for MMR proof building.
+ *
+ * A v2 massif `.log` blob is self-sufficient for any leaf→peak inclusion path
+ * whose leaf lives in that massif: local nodes give the in-massif siblings and
+ * the fixed ancestor peak stack gives everything older (plan-2607-15 §1.1).
+ * Node lookup is pure arithmetic — `LogStart + (i − firstIndex)·32` for local
+ * nodes, `peakStackMap` for ancestors.
+ *
+ * Ported from the inline copies in canopy-api `resolve-receipt.ts` and
+ * receipt-verify `build-receipt-offline.ts` (plan-2607-15 §4, phase 2).
+ * Browser-safe: pure buffer arithmetic, no node builtins (ADR-0048).
+ */
+/** Node access over a single massif blob. */
+export interface MassifNodeStore {
+    /** 32-byte node at MMR index `i` (log region for `i >= firstIndex`, else the ancestor peak stack). */
+    get(i: bigint): Uint8Array;
+    massifHeight: number;
+    massifIndex: bigint;
+    firstIndex: bigint;
+    /** Last MMR index with log data in this blob. */
+    lastIndex: bigint;
+}
+/**
+ * Open a v2 massif blob for MMR node reads. Nodes below `firstIndex` resolve
+ * through the ancestor peak stack; nodes above `lastIndex` are not present in
+ * this blob and throw when requested.
+ */
+export declare function openMassifNodeStore(massifBytes: Uint8Array): MassifNodeStore;
+//# sourceMappingURL=nodestore.d.ts.map

package/dist/massifs/nodestore.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"nodestore.d.ts","sourceRoot":"","sources":["../../src/massifs/nodestore.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAUH,6CAA6C;AAC7C,MAAM,WAAW,eAAe;IAC9B,sGAAsG;IACtG,GAAG,CAAC,CAAC,EAAE,MAAM,GAAG,UAAU,CAAC;IAC3B,YAAY,EAAE,MAAM,CAAC;IACrB,WAAW,EAAE,MAAM,CAAC;IACpB,UAAU,EAAE,MAAM,CAAC;IACnB,iDAAiD;IACjD,SAAS,EAAE,MAAM,CAAC;CACnB;AAYD;;;;GAIG;AACH,wBAAgB,mBAAmB,CAAC,WAAW,EAAE,UAAU,GAAG,eAAe,CA8C5E"}

package/dist/massifs/nodestore.js

@@ -0,0 +1,70 @@
+/**
+ * Massif blob node access for MMR proof building.
+ *
+ * A v2 massif `.log` blob is self-sufficient for any leaf→peak inclusion path
+ * whose leaf lives in that massif: local nodes give the in-massif siblings and
+ * the fixed ancestor peak stack gives everything older (plan-2607-15 §1.1).
+ * Node lookup is pure arithmetic — `LogStart + (i − firstIndex)·32` for local
+ * nodes, `peakStackMap` for ancestors.
+ *
+ * Ported from the inline copies in canopy-api `resolve-receipt.ts` and
+ * receipt-verify `build-receipt-offline.ts` (plan-2607-15 §4, phase 2).
+ * Browser-safe: pure buffer arithmetic, no node builtins (ADR-0048).
+ */
+import { Massif } from "./massif.js";
+import { LogFormat } from "./logformat.js";
+import { peakStackEnd } from "./peakstackend.js";
+import { peakStackMap } from "../mmr/proof.js";
+const VALUE_BYTES = BigInt(LogFormat.ValueBytes); // 32
+const MAX_MMR_HEIGHT = BigInt(LogFormat.MaxMmrHeight); // 64
+function slice32(buf, offset, label) {
+    if (offset < 0n || offset + VALUE_BYTES > BigInt(buf.byteLength)) {
+        throw new Error(`out of range read for ${label}: off=${offset.toString(10)}`);
+    }
+    const start = Number(offset);
+    return buf.slice(start, start + Number(VALUE_BYTES));
+}
+/**
+ * Open a v2 massif blob for MMR node reads. Nodes below `firstIndex` resolve
+ * through the ancestor peak stack; nodes above `lastIndex` are not present in
+ * this blob and throw when requested.
+ */
+export function openMassifNodeStore(massifBytes) {
+    const massif = new Massif(massifBytes);
+    const start = massif.getStart();
+    const massifHeight = start.massifHeight;
+    if (!Number.isInteger(massifHeight) ||
+        massifHeight < 1 ||
+        massifHeight > LogFormat.MaxMmrHeight) {
+        throw new Error(`massif header has invalid height ${massifHeight}`);
+    }
+    const massifIndex = BigInt(start.massifIndex);
+    const firstIndex = start.firstIndex;
+    const logStart = peakStackEnd(massifHeight);
+    const peakStackStart = logStart - MAX_MMR_HEIGHT * VALUE_BYTES;
+    const blobLen = BigInt(massifBytes.byteLength);
+    if (blobLen < logStart) {
+        throw new Error("massif blob too short for v2 layout");
+    }
+    const logNodeCount = (blobLen - logStart) / VALUE_BYTES;
+    const lastIndex = firstIndex + logNodeCount - 1n;
+    const stackMap = peakStackMap(massifHeight, firstIndex);
+    const get = (i) => {
+        if (i >= firstIndex) {
+            if (i > lastIndex) {
+                throw new Error(`mmr index ${i.toString(10)} is beyond this massif's log data ` +
+                    `(last ${lastIndex.toString(10)}); local content does not cover ` +
+                    `the requested tree size`);
+            }
+            const off = logStart + (i - firstIndex) * VALUE_BYTES;
+            return slice32(massifBytes, off, "log-data");
+        }
+        const peakIdx = stackMap.get(i);
+        if (peakIdx === undefined) {
+            throw new Error(`missing ancestor peak for mmr index ${i.toString(10)}`);
+        }
+        const off = peakStackStart + BigInt(peakIdx) * VALUE_BYTES;
+        return slice32(massifBytes, off, "peak-stack");
+    };
+    return { get, massifHeight, massifIndex, firstIndex, lastIndex };
+}

package/dist/mmr/algorithms-sync.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"algorithms-sync.d.ts","sourceRoot":"","sources":["../../src/mmr/algorithms-sync.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,YAAY,CAAC;AAazC;;;;;;GAMG;AACH,wBAAsB,gBAAgB,IAAI,OAAO,CAAC,MAAM,CAAC,CAiBxD"}
+{"version":3,"file":"algorithms-sync.d.ts","sourceRoot":"","sources":["../../src/mmr/algorithms-sync.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,YAAY,CAAC;AAazC;;;;;;GAMG;AACH,wBAAsB,gBAAgB,IAAI,OAAO,CAAC,MAAM,CAAC,CAuBxD"}

package/dist/mmr/algorithms-sync.js

@@ -23,7 +23,13 @@ function concatChunks(chunks) {
  * Only available in Node.js; throws if node:crypto is not available.
  */
 export async function createSyncHasher() {
-    const { createHash } = await import("node:crypto");
+    // Keep the specifier opaque so bundlers do not resolve node:crypto at
+    // build time: this factory is documented runtime-guarded Node-only, and
+    // browser consumers of the package index (e.g. @forestrie/receipt-verify's
+    // ADR-0048 browser-safety guard) must not get node builtins in their
+    // module graph merely by importing it.
+    const nodeCryptoSpecifier = "node:crypto";
+    const { createHash } = await import(/* @vite-ignore */ nodeCryptoSpecifier);
     const chunks = [];
     return {
         reset() {

package/dist/mmr/proof.d.ts

@@ -0,0 +1,62 @@
+/**
+ * MMR proof building (pure, store-agnostic).
+ *
+ * Ports the proof-side arithmetic from go-merklelog `mmr/proof.go` and
+ * `mmr/peaks.go`. These were previously inline-duplicated in
+ * canopy-api `resolve-receipt.ts` and receipt-verify `build-receipt-offline.ts`;
+ * this is the single hoisted home (plan-2607-15 §4, phase 2).
+ *
+ * All arithmetic is BigInt and free of node builtins so the package stays
+ * browser-safe (ADR-0048). Function names mirror the go-merklelog originals.
+ */
+/** Reads the 32-byte node at MMR index `i` from some backing store. */
+export type NodeGetter = (i: bigint) => Uint8Array;
+/**
+ * Zero-based height index of the node at MMR index `i` (leaves are 0).
+ * (go-merklelog `mmr/indexheight.go` IndexHeight)
+ */
+export declare function indexHeight(i: bigint): number;
+/**
+ * Witness path (siblings, ascending) for the node at MMR index `i` in the tree
+ * ending at `mmrLastIndex`. Terminates at the covering peak.
+ * (go-merklelog `mmr/proof.go` InclusionProof)
+ *
+ * @throws if `i > mmrLastIndex`.
+ */
+export declare function inclusionProof(get: NodeGetter, mmrLastIndex: bigint, i: bigint): Uint8Array[];
+/**
+ * Peaks bitmap for an MMR size: the numeric value equals the leaf count of the
+ * largest valid MMR with size <= `mmrSize`; each set bit marks a perfect
+ * subtree (peak). (go-merklelog `mmr/peaks.go` PeaksBitmap)
+ */
+export declare function peaksBitmap(mmrSize: bigint): bigint;
+/**
+ * Accumulator slot (left-to-right) committed by an inclusion proof of length
+ * `proofLen` in a tree of size `mmrSize`. (server resolve-receipt.ts:735,
+ * equivalent to go `mmr.PeakIndex(LeafCount(mmrSize), proofLen)`)
+ */
+export declare function peakIndexForLeafProof(mmrSize: bigint, proofLen: number): number;
+/**
+ * MMR indices of the peaks of the tree ending at `mmrIndex` (inclusive),
+ * ascending. Empty when `mmrIndex + 1` is not a valid MMR size (siblings
+ * without a parent). (go-merklelog `mmr/peaks.go` Peaks)
+ */
+export declare function peakMMRIndexes(mmrIndex: bigint): bigint[];
+/**
+ * Smallest complete MMR size that contains the node at MMR index `mmrIndex`.
+ * (go-merklelog `mmr/firstmmrsize.go` FirstMMRSize)
+ */
+export declare function firstMMRSize(mmrIndex: bigint): bigint;
+/**
+ * Massif index (0-based) that holds the node at MMR index `i` for a log of the
+ * given massif height. (go-merklelog `massifs/massifindex.go` MassifIndexFromMMRIndex)
+ */
+export declare function massifIndexFromMMRIndex(massifHeight: number, i: bigint): bigint;
+/**
+ * Map from ancestor-peak MMR index to peak-stack slot for the massif whose
+ * first MMR index is `firstIndex`. Nodes below `firstIndex` resolve through the
+ * fixed peak-stack region via this map.
+ * (go-merklelog `massifs/peakstack.go` PeakStackMap)
+ */
+export declare function peakStackMap(massifHeight: number, firstIndex: bigint): Map<bigint, number>;
+//# sourceMappingURL=proof.d.ts.map

package/dist/mmr/proof.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"proof.d.ts","sourceRoot":"","sources":["../../src/mmr/proof.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,uEAAuE;AACvE,MAAM,MAAM,UAAU,GAAG,CAAC,CAAC,EAAE,MAAM,KAAK,UAAU,CAAC;AAoCnD;;;GAGG;AACH,wBAAgB,WAAW,CAAC,CAAC,EAAE,MAAM,GAAG,MAAM,CAE7C;AAED;;;;;;GAMG;AACH,wBAAgB,cAAc,CAC5B,GAAG,EAAE,UAAU,EACf,YAAY,EAAE,MAAM,EACpB,CAAC,EAAE,MAAM,GACR,UAAU,EAAE,CAyBd;AAED;;;;GAIG;AACH,wBAAgB,WAAW,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAcnD;AAaD;;;;GAIG;AACH,wBAAgB,qBAAqB,CACnC,OAAO,EAAE,MAAM,EACf,QAAQ,EAAE,MAAM,GACf,MAAM,CAIR;AAQD;;;;GAIG;AACH,wBAAgB,cAAc,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,EAAE,CAczD;AAED;;;GAGG;AACH,wBAAgB,YAAY,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,CAUrD;AAED;;;GAGG;AACH,wBAAgB,uBAAuB,CACrC,YAAY,EAAE,MAAM,EACpB,CAAC,EAAE,MAAM,GACR,MAAM,CAKR;AAED;;;;;GAKG;AACH,wBAAgB,YAAY,CAC1B,YAAY,EAAE,MAAM,EACpB,UAAU,EAAE,MAAM,GACjB,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAWrB"}

package/dist/mmr/proof.js

@@ -0,0 +1,194 @@
+/**
+ * MMR proof building (pure, store-agnostic).
+ *
+ * Ports the proof-side arithmetic from go-merklelog `mmr/proof.go` and
+ * `mmr/peaks.go`. These were previously inline-duplicated in
+ * canopy-api `resolve-receipt.ts` and receipt-verify `build-receipt-offline.ts`;
+ * this is the single hoisted home (plan-2607-15 §4, phase 2).
+ *
+ * All arithmetic is BigInt and free of node builtins so the package stays
+ * browser-safe (ADR-0048). Function names mirror the go-merklelog originals.
+ */
+/** Number of bits needed to represent `num` (0 for 0). */
+function bitLength(num) {
+    if (num <= 0n)
+        return 0;
+    return num.toString(2).length;
+}
+/** True when `num > 0` and its binary form is all ones. */
+function allOnes(num) {
+    return num > 0n && (num & (num + 1n)) === 0n;
+}
+/**
+ * Jump left to the leftmost node at the same height.
+ * (go-merklelog `mmr/indexheight.go` JumpLeftPerfect)
+ */
+function jumpLeftPerfect(pos) {
+    const bl = bitLength(pos);
+    if (bl === 0)
+        return pos;
+    const msb = 1n << BigInt(bl - 1);
+    return pos - (msb - 1n);
+}
+/**
+ * Height of a 1-based position.
+ * (go-merklelog `mmr/indexheight.go` PosHeight)
+ */
+function posHeight(pos) {
+    let current = pos;
+    while (!allOnes(current)) {
+        current = jumpLeftPerfect(current);
+    }
+    return bitLength(current) - 1;
+}
+/**
+ * Zero-based height index of the node at MMR index `i` (leaves are 0).
+ * (go-merklelog `mmr/indexheight.go` IndexHeight)
+ */
+export function indexHeight(i) {
+    return posHeight(i + 1n);
+}
+/**
+ * Witness path (siblings, ascending) for the node at MMR index `i` in the tree
+ * ending at `mmrLastIndex`. Terminates at the covering peak.
+ * (go-merklelog `mmr/proof.go` InclusionProof)
+ *
+ * @throws if `i > mmrLastIndex`.
+ */
+export function inclusionProof(get, mmrLastIndex, i) {
+    if (i > mmrLastIndex) {
+        throw new Error("index out of range");
+    }
+    let g = BigInt(indexHeight(i));
+    const proof = [];
+    // iSibling out of range guarantees loop termination.
+    for (;;) {
+        const siblingOffset = 2n << g;
+        let iSibling;
+        if (BigInt(indexHeight(i + 1n)) > g) {
+            // right sibling
+            iSibling = i - siblingOffset + 1n;
+            i += 1n;
+        }
+        else {
+            // left sibling
+            iSibling = i + siblingOffset - 1n;
+            i += siblingOffset;
+        }
+        if (iSibling > mmrLastIndex) {
+            return proof;
+        }
+        proof.push(get(iSibling));
+        g += 1n;
+    }
+}
+/**
+ * Peaks bitmap for an MMR size: the numeric value equals the leaf count of the
+ * largest valid MMR with size <= `mmrSize`; each set bit marks a perfect
+ * subtree (peak). (go-merklelog `mmr/peaks.go` PeaksBitmap)
+ */
+export function peaksBitmap(mmrSize) {
+    if (mmrSize === 0n)
+        return 0n;
+    let pos = mmrSize;
+    let peakSize = (1n << BigInt(bitLength(mmrSize))) - 1n;
+    let peakMap = 0n;
+    while (peakSize > 0n) {
+        peakMap <<= 1n;
+        if (pos >= peakSize) {
+            pos -= peakSize;
+            peakMap |= 1n;
+        }
+        peakSize >>= 1n;
+    }
+    return peakMap;
+}
+/** Population count of a non-negative BigInt. */
+function popcount(x) {
+    let count = 0;
+    let v = x;
+    while (v > 0n) {
+        if ((v & 1n) === 1n)
+            count += 1;
+        v >>= 1n;
+    }
+    return count;
+}
+/**
+ * Accumulator slot (left-to-right) committed by an inclusion proof of length
+ * `proofLen` in a tree of size `mmrSize`. (server resolve-receipt.ts:735,
+ * equivalent to go `mmr.PeakIndex(LeafCount(mmrSize), proofLen)`)
+ */
+export function peakIndexForLeafProof(mmrSize, proofLen) {
+    const leafCount = peaksBitmap(mmrSize);
+    const peaksMask = (1n << BigInt(proofLen + 1)) - 1n;
+    return popcount(leafCount) - popcount(leafCount & peaksMask);
+}
+/** Largest peak size <= size of the tree ending at index `i`. (go `mmr/peaks.go` TopPeak) */
+function topPeak(i) {
+    const bl = bitLength(i + 2n);
+    return (1n << BigInt(bl - 1)) - 2n;
+}
+/**
+ * MMR indices of the peaks of the tree ending at `mmrIndex` (inclusive),
+ * ascending. Empty when `mmrIndex + 1` is not a valid MMR size (siblings
+ * without a parent). (go-merklelog `mmr/peaks.go` Peaks)
+ */
+export function peakMMRIndexes(mmrIndex) {
+    let mmrSize = mmrIndex + 1n;
+    if (posHeight(mmrSize + 1n) > posHeight(mmrSize)) {
+        return [];
+    }
+    let peak = 0n;
+    const out = [];
+    while (mmrSize !== 0n) {
+        const peakSize = topPeak(mmrSize - 1n) + 1n;
+        peak = peak + peakSize;
+        out.push(peak - 1n);
+        mmrSize -= peakSize;
+    }
+    return out;
+}
+/**
+ * Smallest complete MMR size that contains the node at MMR index `mmrIndex`.
+ * (go-merklelog `mmr/firstmmrsize.go` FirstMMRSize)
+ */
+export function firstMMRSize(mmrIndex) {
+    let i = mmrIndex;
+    let h0 = indexHeight(i);
+    let h1 = indexHeight(i + 1n);
+    while (h0 < h1) {
+        i += 1n;
+        h0 = h1;
+        h1 = indexHeight(i + 1n);
+    }
+    return i + 1n;
+}
+/**
+ * Massif index (0-based) that holds the node at MMR index `i` for a log of the
+ * given massif height. (go-merklelog `massifs/massifindex.go` MassifIndexFromMMRIndex)
+ */
+export function massifIndexFromMMRIndex(massifHeight, i) {
+    const size = firstMMRSize(i);
+    const leafIndex = peaksBitmap(size) - 1n;
+    const massifMaxLeaves = 1n << BigInt(massifHeight - 1);
+    return leafIndex / massifMaxLeaves;
+}
+/**
+ * Map from ancestor-peak MMR index to peak-stack slot for the massif whose
+ * first MMR index is `firstIndex`. Nodes below `firstIndex` resolve through the
+ * fixed peak-stack region via this map.
+ * (go-merklelog `massifs/peakstack.go` PeakStackMap)
+ */
+export function peakStackMap(massifHeight, firstIndex) {
+    const map = new Map();
+    const iPeaks = peakMMRIndexes(firstIndex);
+    for (let i = 0; i < iPeaks.length; i++) {
+        const ip = iPeaks[i];
+        if (indexHeight(ip) < massifHeight - 1) {
+            continue;
+        }
+        map.set(ip, i);
+    }
+    return map;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@forestrie/merklelog",
-  "version": "0.0.2",
+  "version": "0.1.0",
   "license": "MIT",
   "type": "module",
   "description": "MMR (merkle mountain range) proofs and massif storage format for Forestrie transparency logs",
@@ -28,13 +28,15 @@
   ],
   "dependencies": {},
   "devDependencies": {
+    "esbuild": "^0.24.0",
     "typescript": "^5.9.2",
     "vitest": "^3.2.4"
   },
   "scripts": {
     "build": "tsc -p tsconfig.build.json",
     "typecheck": "tsc --noEmit",
-    "test": "vitest --run",
+    "check:browser-safe": "node tools/check-browser-safe.mjs",
+    "test": "pnpm run check:browser-safe && vitest --run",
     "test:watch": "vitest",
     "test:debug": "vitest --inspect --no-file-parallelism"
   }

package/src/index.ts

@@ -45,6 +45,14 @@ export {
 
 export { parseV2StorageObjectPath } from "./massifs/v2storagepaths.js";
 
+// Massif blob node access for MMR proof building (plan-2607-15 §4)
+export { openMassifNodeStore } from "./massifs/nodestore.js";
+export type { MassifNodeStore } from "./massifs/nodestore.js";
+
+// Content-hash leaf lookup over the massif index region (FOR-373)
+export { openMassifLeafIndex, MissingIndexError } from "./massifs/leafindex.js";
+export type { MassifLeafIndex } from "./massifs/leafindex.js";
+
 // Export mmr module
 export { mmrIndex, massifFirstLeaf, leafMinusSpurSum } from "./mmr/index.js";
 export {
@@ -66,3 +74,16 @@ export {
 export { createSyncHasher } from "./mmr/algorithms-sync.js";
 export type { Proof, Peak } from "./mmr/types.js";
 export type { Hasher } from "./mmr/types.js";
+
+// MMR proof building (pure; store-agnostic) — plan-2607-15 §4 (go: mmr/proof.go, peaks.go)
+export {
+  inclusionProof,
+  peakMMRIndexes,
+  peaksBitmap,
+  peakIndexForLeafProof,
+  indexHeight,
+  firstMMRSize,
+  massifIndexFromMMRIndex,
+  peakStackMap,
+} from "./mmr/proof.js";
+export type { NodeGetter } from "./mmr/proof.js";

package/src/massifs/leafindex.ts

@@ -0,0 +1,144 @@
+/**
+ * Content-hash → mmrIndex leaf lookup over a v2 massif index region (FOR-373).
+ *
+ * The v2 massif index region carries, per leaf ordinal, a fixed-width record
+ * whose committed `valueBytes[32]` is the leaf's content hash — the same value
+ * committed by the urkle trie (go-merklelog `urkle/leafrecord.go`,
+ * `massifs/indexformat_v2.go`; plan-2607-15 §1.1). The urkle trie itself is
+ * keyed by the 8-byte leaf key (idtimestamp) for duplicate/exclusion detection,
+ * so content-hash resolution reads the leaf table's value column directly and
+ * maps the matching ordinal back to an MMR index
+ * (`urkle.LeafOrdinalToMMRIndex`).
+ *
+ * This lets `forestrie create-receipt --content-hash <hex>` locate a leaf's
+ * mmrIndex from a massif blob alone, with no external mapping. A negative
+ * lookup (`null`) is distinguishable from absence-of-index: a blob with no
+ * index region throws `MissingIndexError`, while a searched-but-not-present
+ * hash returns `null`.
+ *
+ * Browser-safe: pure buffer arithmetic, no node builtins (ADR-0048).
+ */
+
+import { Massif } from "./massif.js";
+import { LogFormat } from "./logformat.js";
+import { Urkle, leafCountForMassifHeight } from "./indexformat.js";
+import { urkleLeafTableStartByteOffset } from "./urkleindex.js";
+import { peakStackEnd } from "./peakstackend.js";
+import { massifLogEntries } from "./massiflogentries.js";
+import { firstMMRSize, peaksBitmap } from "../mmr/proof.js";
+import { mmrIndex as mmrIndexFromLeafIndex } from "../mmr/index.js";
+
+const HASH_BYTES = Urkle.LeafValueBytes; // 32
+const VALUE_OFFSET = Urkle.LeafValueOffset; // 8 (after the 8-byte key)
+const RECORD_BYTES = Urkle.LeafRecordBytes; // 128
+
+/**
+ * Thrown when the blob carries no populated index region, so a content-hash
+ * lookup cannot even be attempted. Callers distinguish this from a `null`
+ * (searched, not found) result.
+ */
+export class MissingIndexError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = "MissingIndexError";
+  }
+}
+
+/** Content-hash leaf lookup over one massif blob (FOR-373). */
+export interface MassifLeafIndex {
+  /**
+   * MMR index of the leaf whose committed content hash equals `h`, or `null`
+   * when no populated leaf in this massif carries that hash. `h` must be 32
+   * bytes.
+   */
+  findByContentHash(h: Uint8Array): bigint | null;
+  /** Number of populated leaves in this blob. */
+  leafCount: number;
+}
+
+function equals32(a: Uint8Array, aOff: number, b: Uint8Array): boolean {
+  for (let i = 0; i < HASH_BYTES; i++) {
+    if (a[aOff + i] !== b[i]) return false;
+  }
+  return true;
+}
+
+/**
+ * Leaf index of the first leaf in the massif whose first MMR index is
+ * `firstMMRIndex`. (go-merklelog `mmr/leafcount.go` LeafIndex)
+ */
+function leafIndexFromMMRIndex(firstMMRIndex: bigint): bigint {
+  if (firstMMRIndex === 0n) return 0n;
+  return peaksBitmap(firstMMRSize(firstMMRIndex)) - 1n;
+}
+
+/**
+ * Open a v2 massif blob for content-hash leaf lookups.
+ *
+ * @throws MissingIndexError if the blob is too short to contain the fixed index
+ *   region for its declared massif height (no index present).
+ */
+export function openMassifLeafIndex(massifBytes: Uint8Array): MassifLeafIndex {
+  const massif = new Massif(massifBytes);
+  const start = massif.getStart();
+  const massifHeight = start.massifHeight;
+  if (
+    !Number.isInteger(massifHeight) ||
+    massifHeight < 1 ||
+    massifHeight > LogFormat.MaxMmrHeight
+  ) {
+    throw new Error(`massif header has invalid height ${massifHeight}`);
+  }
+  const firstIndex = start.firstIndex;
+
+  const leafTableStart = urkleLeafTableStartByteOffset(massifHeight);
+  const capacity = Number(leafCountForMassifHeight(massifHeight));
+  const leafTableBytes = capacity * RECORD_BYTES;
+  const stackEnd = peakStackEnd(massifHeight);
+
+  // The index region must fit before the fixed peak stack + log region. A blob
+  // shorter than that has no populated index to search.
+  if (massifHeight > 1 && BigInt(leafTableStart + leafTableBytes) > stackEnd) {
+    throw new Error("massif index region math is inconsistent");
+  }
+  if (BigInt(massifBytes.byteLength) < stackEnd) {
+    throw new MissingIndexError(
+      "massif blob too short for a v2 index region (no index present)",
+    );
+  }
+
+  // Only leaves actually appended have populated records. Derive the populated
+  // leaf count from the log node count (index records are written 1:1 with
+  // appended leaves). Never exceed the fixed capacity for the height.
+  const logNodeCount = massifLogEntries(massifBytes.byteLength, massifHeight);
+  const firstLeafIndex = leafIndexFromMMRIndex(firstIndex);
+  let populated = 0;
+  for (let ordinal = 0; ordinal < capacity; ordinal++) {
+    // MMR index of leaf (firstLeafIndex + ordinal), relative to this blob's
+    // firstIndex, must be within the log node count.
+    const leafMMRIndex = mmrIndexFromLeafIndex(
+      firstLeafIndex + BigInt(ordinal),
+    );
+    if (leafMMRIndex - firstIndex >= logNodeCount) break;
+    populated = ordinal + 1;
+  }
+
+  const findByContentHash = (h: Uint8Array): bigint | null => {
+    if (h.length !== HASH_BYTES) {
+      throw new Error(
+        `content hash must be ${HASH_BYTES} bytes, got ${h.length}`,
+      );
+    }
+    for (let ordinal = 0; ordinal < populated; ordinal++) {
+      const recordOff = leafTableStart + ordinal * RECORD_BYTES;
+      const valueOff = recordOff + VALUE_OFFSET;
+      if (valueOff + HASH_BYTES > massifBytes.byteLength) break;
+      if (equals32(massifBytes, valueOff, h)) {
+        return mmrIndexFromLeafIndex(firstLeafIndex + BigInt(ordinal));
+      }
+    }
+    return null;
+  };
+
+  return { findByContentHash, leafCount: populated };
+}

package/src/massifs/nodestore.ts

@@ -0,0 +1,95 @@
+/**
+ * Massif blob node access for MMR proof building.
+ *
+ * A v2 massif `.log` blob is self-sufficient for any leaf→peak inclusion path
+ * whose leaf lives in that massif: local nodes give the in-massif siblings and
+ * the fixed ancestor peak stack gives everything older (plan-2607-15 §1.1).
+ * Node lookup is pure arithmetic — `LogStart + (i − firstIndex)·32` for local
+ * nodes, `peakStackMap` for ancestors.
+ *
+ * Ported from the inline copies in canopy-api `resolve-receipt.ts` and
+ * receipt-verify `build-receipt-offline.ts` (plan-2607-15 §4, phase 2).
+ * Browser-safe: pure buffer arithmetic, no node builtins (ADR-0048).
+ */
+
+import { Massif } from "./massif.js";
+import { LogFormat } from "./logformat.js";
+import { peakStackEnd } from "./peakstackend.js";
+import { peakStackMap } from "../mmr/proof.js";
+
+const VALUE_BYTES = BigInt(LogFormat.ValueBytes); // 32
+const MAX_MMR_HEIGHT = BigInt(LogFormat.MaxMmrHeight); // 64
+
+/** Node access over a single massif blob. */
+export interface MassifNodeStore {
+  /** 32-byte node at MMR index `i` (log region for `i >= firstIndex`, else the ancestor peak stack). */
+  get(i: bigint): Uint8Array;
+  massifHeight: number;
+  massifIndex: bigint;
+  firstIndex: bigint;
+  /** Last MMR index with log data in this blob. */
+  lastIndex: bigint;
+}
+
+function slice32(buf: Uint8Array, offset: bigint, label: string): Uint8Array {
+  if (offset < 0n || offset + VALUE_BYTES > BigInt(buf.byteLength)) {
+    throw new Error(
+      `out of range read for ${label}: off=${offset.toString(10)}`,
+    );
+  }
+  const start = Number(offset);
+  return buf.slice(start, start + Number(VALUE_BYTES));
+}
+
+/**
+ * Open a v2 massif blob for MMR node reads. Nodes below `firstIndex` resolve
+ * through the ancestor peak stack; nodes above `lastIndex` are not present in
+ * this blob and throw when requested.
+ */
+export function openMassifNodeStore(massifBytes: Uint8Array): MassifNodeStore {
+  const massif = new Massif(massifBytes);
+  const start = massif.getStart();
+  const massifHeight = start.massifHeight;
+  if (
+    !Number.isInteger(massifHeight) ||
+    massifHeight < 1 ||
+    massifHeight > LogFormat.MaxMmrHeight
+  ) {
+    throw new Error(`massif header has invalid height ${massifHeight}`);
+  }
+  const massifIndex = BigInt(start.massifIndex);
+  const firstIndex = start.firstIndex;
+
+  const logStart = peakStackEnd(massifHeight);
+  const peakStackStart = logStart - MAX_MMR_HEIGHT * VALUE_BYTES;
+  const blobLen = BigInt(massifBytes.byteLength);
+  if (blobLen < logStart) {
+    throw new Error("massif blob too short for v2 layout");
+  }
+  const logNodeCount = (blobLen - logStart) / VALUE_BYTES;
+  const lastIndex = firstIndex + logNodeCount - 1n;
+
+  const stackMap = peakStackMap(massifHeight, firstIndex);
+
+  const get = (i: bigint): Uint8Array => {
+    if (i >= firstIndex) {
+      if (i > lastIndex) {
+        throw new Error(
+          `mmr index ${i.toString(10)} is beyond this massif's log data ` +
+            `(last ${lastIndex.toString(10)}); local content does not cover ` +
+            `the requested tree size`,
+        );
+      }
+      const off = logStart + (i - firstIndex) * VALUE_BYTES;
+      return slice32(massifBytes, off, "log-data");
+    }
+    const peakIdx = stackMap.get(i);
+    if (peakIdx === undefined) {
+      throw new Error(`missing ancestor peak for mmr index ${i.toString(10)}`);
+    }
+    const off = peakStackStart + BigInt(peakIdx) * VALUE_BYTES;
+    return slice32(massifBytes, off, "peak-stack");
+  };
+
+  return { get, massifHeight, massifIndex, firstIndex, lastIndex };
+}

package/src/mmr/algorithms-sync.ts

@@ -27,7 +27,13 @@ function concatChunks(chunks: Uint8Array[]): Uint8Array {
  * Only available in Node.js; throws if node:crypto is not available.
  */
 export async function createSyncHasher(): Promise<Hasher> {
-  const { createHash } = await import("node:crypto");
+  // Keep the specifier opaque so bundlers do not resolve node:crypto at
+  // build time: this factory is documented runtime-guarded Node-only, and
+  // browser consumers of the package index (e.g. @forestrie/receipt-verify's
+  // ADR-0048 browser-safety guard) must not get node builtins in their
+  // module graph merely by importing it.
+  const nodeCryptoSpecifier = "node:crypto";
+  const { createHash } = await import(/* @vite-ignore */ nodeCryptoSpecifier);
   const chunks: Uint8Array[] = [];
   return {
     reset(): void {

package/src/mmr/proof.ts

@@ -0,0 +1,219 @@
+/**
+ * MMR proof building (pure, store-agnostic).
+ *
+ * Ports the proof-side arithmetic from go-merklelog `mmr/proof.go` and
+ * `mmr/peaks.go`. These were previously inline-duplicated in
+ * canopy-api `resolve-receipt.ts` and receipt-verify `build-receipt-offline.ts`;
+ * this is the single hoisted home (plan-2607-15 §4, phase 2).
+ *
+ * All arithmetic is BigInt and free of node builtins so the package stays
+ * browser-safe (ADR-0048). Function names mirror the go-merklelog originals.
+ */
+
+/** Reads the 32-byte node at MMR index `i` from some backing store. */
+export type NodeGetter = (i: bigint) => Uint8Array;
+
+/** Number of bits needed to represent `num` (0 for 0). */
+function bitLength(num: bigint): number {
+  if (num <= 0n) return 0;
+  return num.toString(2).length;
+}
+
+/** True when `num > 0` and its binary form is all ones. */
+function allOnes(num: bigint): boolean {
+  return num > 0n && (num & (num + 1n)) === 0n;
+}
+
+/**
+ * Jump left to the leftmost node at the same height.
+ * (go-merklelog `mmr/indexheight.go` JumpLeftPerfect)
+ */
+function jumpLeftPerfect(pos: bigint): bigint {
+  const bl = bitLength(pos);
+  if (bl === 0) return pos;
+  const msb = 1n << BigInt(bl - 1);
+  return pos - (msb - 1n);
+}
+
+/**
+ * Height of a 1-based position.
+ * (go-merklelog `mmr/indexheight.go` PosHeight)
+ */
+function posHeight(pos: bigint): number {
+  let current = pos;
+  while (!allOnes(current)) {
+    current = jumpLeftPerfect(current);
+  }
+  return bitLength(current) - 1;
+}
+
+/**
+ * Zero-based height index of the node at MMR index `i` (leaves are 0).
+ * (go-merklelog `mmr/indexheight.go` IndexHeight)
+ */
+export function indexHeight(i: bigint): number {
+  return posHeight(i + 1n);
+}
+
+/**
+ * Witness path (siblings, ascending) for the node at MMR index `i` in the tree
+ * ending at `mmrLastIndex`. Terminates at the covering peak.
+ * (go-merklelog `mmr/proof.go` InclusionProof)
+ *
+ * @throws if `i > mmrLastIndex`.
+ */
+export function inclusionProof(
+  get: NodeGetter,
+  mmrLastIndex: bigint,
+  i: bigint,
+): Uint8Array[] {
+  if (i > mmrLastIndex) {
+    throw new Error("index out of range");
+  }
+  let g = BigInt(indexHeight(i));
+  const proof: Uint8Array[] = [];
+  // iSibling out of range guarantees loop termination.
+  for (;;) {
+    const siblingOffset = 2n << g;
+    let iSibling: bigint;
+    if (BigInt(indexHeight(i + 1n)) > g) {
+      // right sibling
+      iSibling = i - siblingOffset + 1n;
+      i += 1n;
+    } else {
+      // left sibling
+      iSibling = i + siblingOffset - 1n;
+      i += siblingOffset;
+    }
+    if (iSibling > mmrLastIndex) {
+      return proof;
+    }
+    proof.push(get(iSibling));
+    g += 1n;
+  }
+}
+
+/**
+ * Peaks bitmap for an MMR size: the numeric value equals the leaf count of the
+ * largest valid MMR with size <= `mmrSize`; each set bit marks a perfect
+ * subtree (peak). (go-merklelog `mmr/peaks.go` PeaksBitmap)
+ */
+export function peaksBitmap(mmrSize: bigint): bigint {
+  if (mmrSize === 0n) return 0n;
+  let pos = mmrSize;
+  let peakSize = (1n << BigInt(bitLength(mmrSize))) - 1n;
+  let peakMap = 0n;
+  while (peakSize > 0n) {
+    peakMap <<= 1n;
+    if (pos >= peakSize) {
+      pos -= peakSize;
+      peakMap |= 1n;
+    }
+    peakSize >>= 1n;
+  }
+  return peakMap;
+}
+
+/** Population count of a non-negative BigInt. */
+function popcount(x: bigint): number {
+  let count = 0;
+  let v = x;
+  while (v > 0n) {
+    if ((v & 1n) === 1n) count += 1;
+    v >>= 1n;
+  }
+  return count;
+}
+
+/**
+ * Accumulator slot (left-to-right) committed by an inclusion proof of length
+ * `proofLen` in a tree of size `mmrSize`. (server resolve-receipt.ts:735,
+ * equivalent to go `mmr.PeakIndex(LeafCount(mmrSize), proofLen)`)
+ */
+export function peakIndexForLeafProof(
+  mmrSize: bigint,
+  proofLen: number,
+): number {
+  const leafCount = peaksBitmap(mmrSize);
+  const peaksMask = (1n << BigInt(proofLen + 1)) - 1n;
+  return popcount(leafCount) - popcount(leafCount & peaksMask);
+}
+
+/** Largest peak size <= size of the tree ending at index `i`. (go `mmr/peaks.go` TopPeak) */
+function topPeak(i: bigint): bigint {
+  const bl = bitLength(i + 2n);
+  return (1n << BigInt(bl - 1)) - 2n;
+}
+
+/**
+ * MMR indices of the peaks of the tree ending at `mmrIndex` (inclusive),
+ * ascending. Empty when `mmrIndex + 1` is not a valid MMR size (siblings
+ * without a parent). (go-merklelog `mmr/peaks.go` Peaks)
+ */
+export function peakMMRIndexes(mmrIndex: bigint): bigint[] {
+  let mmrSize = mmrIndex + 1n;
+  if (posHeight(mmrSize + 1n) > posHeight(mmrSize)) {
+    return [];
+  }
+  let peak = 0n;
+  const out: bigint[] = [];
+  while (mmrSize !== 0n) {
+    const peakSize = topPeak(mmrSize - 1n) + 1n;
+    peak = peak + peakSize;
+    out.push(peak - 1n);
+    mmrSize -= peakSize;
+  }
+  return out;
+}
+
+/**
+ * Smallest complete MMR size that contains the node at MMR index `mmrIndex`.
+ * (go-merklelog `mmr/firstmmrsize.go` FirstMMRSize)
+ */
+export function firstMMRSize(mmrIndex: bigint): bigint {
+  let i = mmrIndex;
+  let h0 = indexHeight(i);
+  let h1 = indexHeight(i + 1n);
+  while (h0 < h1) {
+    i += 1n;
+    h0 = h1;
+    h1 = indexHeight(i + 1n);
+  }
+  return i + 1n;
+}
+
+/**
+ * Massif index (0-based) that holds the node at MMR index `i` for a log of the
+ * given massif height. (go-merklelog `massifs/massifindex.go` MassifIndexFromMMRIndex)
+ */
+export function massifIndexFromMMRIndex(
+  massifHeight: number,
+  i: bigint,
+): bigint {
+  const size = firstMMRSize(i);
+  const leafIndex = peaksBitmap(size) - 1n;
+  const massifMaxLeaves = 1n << BigInt(massifHeight - 1);
+  return leafIndex / massifMaxLeaves;
+}
+
+/**
+ * Map from ancestor-peak MMR index to peak-stack slot for the massif whose
+ * first MMR index is `firstIndex`. Nodes below `firstIndex` resolve through the
+ * fixed peak-stack region via this map.
+ * (go-merklelog `massifs/peakstack.go` PeakStackMap)
+ */
+export function peakStackMap(
+  massifHeight: number,
+  firstIndex: bigint,
+): Map<bigint, number> {
+  const map = new Map<bigint, number>();
+  const iPeaks = peakMMRIndexes(firstIndex);
+  for (let i = 0; i < iPeaks.length; i++) {
+    const ip = iPeaks[i]!;
+    if (indexHeight(ip) < massifHeight - 1) {
+      continue;
+    }
+    map.set(ip, i);
+  }
+  return map;
+}