@forestrie/merklelog 0.5.0 → 0.7.0

package/dist/index.d.ts

@@ -11,7 +11,8 @@ export { Massif } from "./massifs/massif.js";
 export type { MassifStart, LeafComponent, LeafEnumeratorSpec, LeafEntry, } from "./massifs/types.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";
+export { formatMassifObjectIndex, MASSIF_OBJECT_INDEX_DIGITS, MAX_MASSIF_INDEX, parseV2StorageObjectPath, v2CheckpointObjectKey, v2MassifObjectKey, } from "./massifs/v2storagepaths.js";
+export { massifIndexFromLeafIndex } from "./massifs/massifindex.js";
 export { openMassifNodeStore } from "./massifs/nodestore.js";
 export type { MassifNodeStore } from "./massifs/nodestore.js";
 export { openMassifLeafIndex, MissingIndexError } from "./massifs/leafindex.js";

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,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,WAAW,EAAE,MAAM,wBAAwB,CAAC;AAG3E,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,EACjB,eAAe,EACf,uBAAuB,EACvB,qBAAqB,EACrB,KAAK,gBAAgB,GACtB,MAAM,qBAAqB,CAAC;AAG7B,OAAO,EACL,qBAAqB,EACrB,kBAAkB,EAClB,4BAA4B,EAC5B,6BAA6B,EAC7B,wBAAwB,EACxB,uBAAuB,EACvB,gBAAgB,EAChB,aAAa,GACd,MAAM,iBAAiB,CAAC;AACzB,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,kBAAkB,EAClB,yBAAyB,EACzB,cAAc,EACd,WAAW,EACX,qBAAqB,EACrB,mBAAmB,EACnB,WAAW,EACX,YAAY,EACZ,uBAAuB,EACvB,YAAY,GACb,MAAM,gBAAgB,CAAC;AACxB,YAAY,EAAE,UAAU,EAAE,qBAAqB,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,EACL,uBAAuB,EACvB,0BAA0B,EAC1B,gBAAgB,EAChB,wBAAwB,EACxB,qBAAqB,EACrB,iBAAiB,GAClB,MAAM,6BAA6B,CAAC;AAGrC,OAAO,EAAE,wBAAwB,EAAE,MAAM,0BAA0B,CAAC;AACpE,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,WAAW,EAAE,MAAM,wBAAwB,CAAC;AAG3E,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,EACjB,eAAe,EACf,uBAAuB,EACvB,qBAAqB,EACrB,KAAK,gBAAgB,GACtB,MAAM,qBAAqB,CAAC;AAG7B,OAAO,EACL,qBAAqB,EACrB,kBAAkB,EAClB,4BAA4B,EAC5B,6BAA6B,EAC7B,wBAAwB,EACxB,uBAAuB,EACvB,gBAAgB,EAChB,aAAa,GACd,MAAM,iBAAiB,CAAC;AACzB,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,kBAAkB,EAClB,yBAAyB,EACzB,cAAc,EACd,WAAW,EACX,qBAAqB,EACrB,mBAAmB,EACnB,WAAW,EACX,YAAY,EACZ,uBAAuB,EACvB,YAAY,GACb,MAAM,gBAAgB,CAAC;AACxB,YAAY,EAAE,UAAU,EAAE,qBAAqB,EAAE,MAAM,gBAAgB,CAAC"}

package/dist/index.js

@@ -12,8 +12,9 @@ export { Uint64 } from "./uint64/index.js";
 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";
+export { formatMassifObjectIndex, MASSIF_OBJECT_INDEX_DIGITS, MAX_MASSIF_INDEX, parseV2StorageObjectPath, v2CheckpointObjectKey, v2MassifObjectKey, } from "./massifs/v2storagepaths.js";
 // Massif blob node access for MMR proof building (plan-2607-15 §4)
+export { massifIndexFromLeafIndex } from "./massifs/massifindex.js";
 export { openMassifNodeStore } from "./massifs/nodestore.js";
 // Content-hash leaf lookup over the massif index region (FOR-373)
 export { openMassifLeafIndex, MissingIndexError } from "./massifs/leafindex.js";

package/dist/massifs/massifindex.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Which massif holds a leaf. A massif of one-based height h holds
+ * 2^(h-1) leaves; see {@link leafCountForMassifHeight} and the
+ * go-merklelog notation in
+ * [mmr-math-cheatsheet.md](https://github.com/forestrie/go-merklelog/blob/main/mmr-math-cheatsheet.md).
+ * Mirrors go-merklelog `massifs/massifindex.go` MassifIndexFromLeafIndex,
+ * which arbor's ranger uses when it commits massifs.
+ */
+/**
+ * Returns the zero-based index of the massif that holds the leaf at
+ * `leafIndex` (zero-based, counting leaves only).
+ *
+ * @param massifHeight - One-based massif height (h >= 1)
+ * @throws RangeError when massifHeight is 0, which holds no leaves
+ */
+export declare function massifIndexFromLeafIndex(massifHeight: number, leafIndex: bigint | number): bigint;
+//# sourceMappingURL=massifindex.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"massifindex.d.ts","sourceRoot":"","sources":["../../src/massifs/massifindex.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAIH;;;;;;GAMG;AACH,wBAAgB,wBAAwB,CACtC,YAAY,EAAE,MAAM,EACpB,SAAS,EAAE,MAAM,GAAG,MAAM,GACzB,MAAM,CAMR"}

package/dist/massifs/massifindex.js

@@ -0,0 +1,23 @@
+/**
+ * Which massif holds a leaf. A massif of one-based height h holds
+ * 2^(h-1) leaves; see {@link leafCountForMassifHeight} and the
+ * go-merklelog notation in
+ * [mmr-math-cheatsheet.md](https://github.com/forestrie/go-merklelog/blob/main/mmr-math-cheatsheet.md).
+ * Mirrors go-merklelog `massifs/massifindex.go` MassifIndexFromLeafIndex,
+ * which arbor's ranger uses when it commits massifs.
+ */
+import { leafCountForMassifHeight } from "./indexformat.js";
+/**
+ * Returns the zero-based index of the massif that holds the leaf at
+ * `leafIndex` (zero-based, counting leaves only).
+ *
+ * @param massifHeight - One-based massif height (h >= 1)
+ * @throws RangeError when massifHeight is 0, which holds no leaves
+ */
+export function massifIndexFromLeafIndex(massifHeight, leafIndex) {
+    const leavesPerMassif = leafCountForMassifHeight(massifHeight);
+    if (leavesPerMassif === 0n) {
+        throw new RangeError("massifHeight must be at least 1");
+    }
+    return BigInt(leafIndex) / leavesPerMassif;
+}

package/dist/massifs/v2storagepaths.d.ts

@@ -1,17 +1,57 @@
 /**
- * Parse an R2 object path to extract log ID, massif height, and massif index.
+ * Merklelog v2 R2 object layout:
  *
  * - v2/merklelog/massifs/{massifHeight}/{logId}/{massifIndex}.log
  * - v2/merklelog/checkpoints/{massifHeight}/{logId}/{massifIndex}.sth
  *
- * @param path - The object path path from the R2 notification
+ * `{massifIndex}` is a zero-padded, 16-digit DECIMAL integer. The Go writer
+ * owns this convention: go-merklelog
+ * [massifs/storage/const.go](https://github.com/forestrie/go-merklelog/blob/main/massifs/storage/const.go)
+ * (`V1MMRBlobNameFmt = "%016d.log"`, `V1MMRSignedTreeHeadBlobNameFmt =
+ * "%016d.sth"`) and its reader
+ * [objectindexfrompath.go](https://github.com/forestrie/go-merklelog/blob/main/massifs/storage/objectindexfrompath.go)
+ * (`strconv.Atoi`). canopy-api builds its R2 keys through the functions
+ * here (FOR-621: an earlier reader parsed hex, which agrees with the writer
+ * only for indices 0-9). Code outside this package that spells a key by hand
+ * (delegation-coordinator `seal-hint.ts`, test fixtures, demos) uses only
+ * index 0, which reads the same in any radix; anything that needs another
+ * index must use these helpers.
+ */
+/** Width of the massif index segment in an object key. */
+export declare const MASSIF_OBJECT_INDEX_DIGITS = 16;
+/**
+ * Largest massif index the Go side can represent. go-merklelog
+ * `FmtMassifPath(prefix, massifIndex uint32)` and arbor's publisher
+ * (`strconv.ParseUint(base, 10, 32)`) use `uint32`; a larger index would be
+ * silently truncated by `ObjectIndexFromPath`, so it is rejected here.
+ */
+export declare const MAX_MASSIF_INDEX = 4294967295n;
+/**
+ * Parse an R2 object path to extract log ID, massif height, and massif index.
+ *
+ * @param path - The object path from the R2 notification
  * @returns Parsed components including logId, massifHeight, and massifIndex
  * @throws Error if the path doesn't match expected format or if parsing fails
  */
 export declare function parseV2StorageObjectPath(path: string): {
     logId: string;
     massifHeight: number;
-    massifIndex: number;
+    massifIndex: bigint;
     type: string;
 };
+/**
+ * Build the massif `.log` object key for a log.
+ */
+export declare function v2MassifObjectKey(massifHeight: number, logId: string, massifIndex: bigint | number): string;
+/**
+ * Build the signed checkpoint `.sth` object key for a log.
+ */
+export declare function v2CheckpointObjectKey(massifHeight: number, logId: string, massifIndex: bigint | number): string;
+/**
+ * Format a massif index as the 16-digit decimal key segment (Go `%016d`).
+ *
+ * @throws Error if the index is negative, not an integer, not a safe integer
+ *   (number input), or exceeds {@link MAX_MASSIF_INDEX}.
+ */
+export declare function formatMassifObjectIndex(massifIndex: bigint | number): string;
 //# sourceMappingURL=v2storagepaths.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"v2storagepaths.d.ts","sourceRoot":"","sources":["../../src/massifs/v2storagepaths.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AACH,wBAAgB,wBAAwB,CAAC,IAAI,EAAE,MAAM;;;;;EAkDpD"}
+{"version":3,"file":"v2storagepaths.d.ts","sourceRoot":"","sources":["../../src/massifs/v2storagepaths.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAEH,0DAA0D;AAC1D,eAAO,MAAM,0BAA0B,KAAK,CAAC;AAE7C;;;;;GAKG;AACH,eAAO,MAAM,gBAAgB,cAAc,CAAC;AAiB5C;;;;;;GAMG;AACH,wBAAgB,wBAAwB,CAAC,IAAI,EAAE,MAAM;;;;;EAyDpD;AAED;;GAEG;AACH,wBAAgB,iBAAiB,CAC/B,YAAY,EAAE,MAAM,EACpB,KAAK,EAAE,MAAM,EACb,WAAW,EAAE,MAAM,GAAG,MAAM,GAC3B,MAAM,CAGR;AAED;;GAEG;AACH,wBAAgB,qBAAqB,CACnC,YAAY,EAAE,MAAM,EACpB,KAAK,EAAE,MAAM,EACb,WAAW,EAAE,MAAM,GAAG,MAAM,GAC3B,MAAM,CAGR;AAED;;;;;GAKG;AACH,wBAAgB,uBAAuB,CAAC,WAAW,EAAE,MAAM,GAAG,MAAM,GAAG,MAAM,CAW5E"}

package/dist/massifs/v2storagepaths.js

@@ -1,42 +1,84 @@
 /**
- * Parse an R2 object path to extract log ID, massif height, and massif index.
+ * Merklelog v2 R2 object layout:
  *
  * - v2/merklelog/massifs/{massifHeight}/{logId}/{massifIndex}.log
  * - v2/merklelog/checkpoints/{massifHeight}/{logId}/{massifIndex}.sth
  *
- * @param path - The object path path from the R2 notification
+ * `{massifIndex}` is a zero-padded, 16-digit DECIMAL integer. The Go writer
+ * owns this convention: go-merklelog
+ * [massifs/storage/const.go](https://github.com/forestrie/go-merklelog/blob/main/massifs/storage/const.go)
+ * (`V1MMRBlobNameFmt = "%016d.log"`, `V1MMRSignedTreeHeadBlobNameFmt =
+ * "%016d.sth"`) and its reader
+ * [objectindexfrompath.go](https://github.com/forestrie/go-merklelog/blob/main/massifs/storage/objectindexfrompath.go)
+ * (`strconv.Atoi`). canopy-api builds its R2 keys through the functions
+ * here (FOR-621: an earlier reader parsed hex, which agrees with the writer
+ * only for indices 0-9). Code outside this package that spells a key by hand
+ * (delegation-coordinator `seal-hint.ts`, test fixtures, demos) uses only
+ * index 0, which reads the same in any radix; anything that needs another
+ * index must use these helpers.
+ */
+/** Width of the massif index segment in an object key. */
+export const MASSIF_OBJECT_INDEX_DIGITS = 16;
+/**
+ * Largest massif index the Go side can represent. go-merklelog
+ * `FmtMassifPath(prefix, massifIndex uint32)` and arbor's publisher
+ * (`strconv.ParseUint(base, 10, 32)`) use `uint32`; a larger index would be
+ * silently truncated by `ObjectIndexFromPath`, so it is rejected here.
+ */
+export const MAX_MASSIF_INDEX = 0xffffffffn;
+/**
+ * Massif height bounds. Go writes height as `%d` of a `uint8` and arbor's
+ * publisher `ParseCheckpointKey` rejects 0, so valid heights are 1..255 with
+ * no leading zeros.
+ */
+const MIN_MASSIF_HEIGHT = 1;
+const MAX_MASSIF_HEIGHT = 255;
+const MASSIF_OBJECT_INDEX_RE = /^[0-9]{16}$/;
+const MASSIF_HEIGHT_RE = /^[1-9][0-9]{0,2}$/;
+const OBJECT_EXTENSIONS = {
+    massifs: ".log",
+    checkpoints: ".sth",
+};
+/**
+ * Parse an R2 object path to extract log ID, massif height, and massif index.
+ *
+ * @param path - The object path from the R2 notification
  * @returns Parsed components including logId, massifHeight, and massifIndex
  * @throws Error if the path doesn't match expected format or if parsing fails
  */
 export function parseV2StorageObjectPath(path) {
     const parts = path.split("/");
-    if (parts.length < 6 || parts[0] !== "v2" || parts[1] !== "merklelog")
+    if (parts.length !== 6 || parts[0] !== "v2" || parts[1] !== "merklelog")
         throw new Error(`Unrecognized path format: ${path}`);
-    // Check for new v2 format: v2/merklelog/massifs/{massifHeight}/{logId}/{index}.log
-    // or v2/merklelog/checkpoints/{massifHeight}/{logId}/{index}.sth
-    const typePart = parts[2]; // "massifs" or "checkpoints"
+    const typePart = parts[2];
     const massifHeightStr = parts[3];
     const logId = parts[4];
     const filename = parts[5];
-    // Validate extension
-    const expectedExt = typePart === "massifs" ? ".log" : ".sth";
+    const expectedExt = Object.hasOwn(OBJECT_EXTENSIONS, typePart)
+        ? OBJECT_EXTENSIONS[typePart]
+        : undefined;
+    if (expectedExt === undefined) {
+        throw new Error(`Object type must be massifs or checkpoints, got: ${typePart}`);
+    }
+    if (logId.length === 0) {
+        throw new Error(`Log id segment is empty: ${path}`);
+    }
     if (!filename.endsWith(expectedExt)) {
         throw new Error(`Expected ${expectedExt} extension for ${typePart}, got: ${filename}`);
     }
-    // Parse massif index (hex, 16 digits)
     const massifIndexStr = filename.slice(0, -expectedExt.length);
-    if (massifIndexStr.length !== 16) {
-        throw new Error(`Massif index must be 16 hex digits, got ${massifIndexStr.length}: ${massifIndexStr}`);
+    if (!MASSIF_OBJECT_INDEX_RE.test(massifIndexStr)) {
+        throw new Error(`Massif index must be 16 decimal digits, got: ${massifIndexStr}`);
     }
-    const massifIndex = Number.parseInt(massifIndexStr, 16);
-    if (!Number.isFinite(massifIndex)) {
-        throw new Error(`Failed to parse massif index as hex number: ${massifIndexStr}`);
+    const massifIndex = BigInt(massifIndexStr);
+    if (massifIndex > MAX_MASSIF_INDEX) {
+        throw new Error(`Massif index must be 0..${MAX_MASSIF_INDEX}, got ${massifIndex}`);
     }
-    // Parse massifHeight
-    const massifHeight = Number.parseInt(massifHeightStr, 10);
-    if (!Number.isFinite(massifHeight)) {
+    if (!MASSIF_HEIGHT_RE.test(massifHeightStr) ||
+        Number(massifHeightStr) > MAX_MASSIF_HEIGHT) {
         throw new Error(`Failed to parse massif height as number: ${massifHeightStr}`);
     }
+    const massifHeight = Number(massifHeightStr);
     return {
         logId,
         massifHeight,
@@ -44,3 +86,48 @@ export function parseV2StorageObjectPath(path) {
         type: typePart,
     };
 }
+/**
+ * Build the massif `.log` object key for a log.
+ */
+export function v2MassifObjectKey(massifHeight, logId, massifIndex) {
+    assertKeyHeightAndLogId(massifHeight, logId);
+    return `v2/merklelog/massifs/${massifHeight}/${logId}/${formatMassifObjectIndex(massifIndex)}.log`;
+}
+/**
+ * Build the signed checkpoint `.sth` object key for a log.
+ */
+export function v2CheckpointObjectKey(massifHeight, logId, massifIndex) {
+    assertKeyHeightAndLogId(massifHeight, logId);
+    return `v2/merklelog/checkpoints/${massifHeight}/${logId}/${formatMassifObjectIndex(massifIndex)}.sth`;
+}
+/**
+ * Format a massif index as the 16-digit decimal key segment (Go `%016d`).
+ *
+ * @throws Error if the index is negative, not an integer, not a safe integer
+ *   (number input), or exceeds {@link MAX_MASSIF_INDEX}.
+ */
+export function formatMassifObjectIndex(massifIndex) {
+    if (typeof massifIndex === "number" && !Number.isSafeInteger(massifIndex)) {
+        throw new Error(`Massif index must be a safe integer, got ${massifIndex}`);
+    }
+    const index = BigInt(massifIndex);
+    if (index < 0n || index > MAX_MASSIF_INDEX) {
+        throw new Error(`Massif index must be 0..${MAX_MASSIF_INDEX}, got ${index}`);
+    }
+    return index.toString(10).padStart(MASSIF_OBJECT_INDEX_DIGITS, "0");
+}
+/**
+ * Reject a massif height or log id that would build a key Go cannot read:
+ * height outside 1..255 or non-integer, or a log id that is empty or would
+ * add path segments.
+ */
+function assertKeyHeightAndLogId(massifHeight, logId) {
+    if (!Number.isInteger(massifHeight) ||
+        massifHeight < MIN_MASSIF_HEIGHT ||
+        massifHeight > MAX_MASSIF_HEIGHT) {
+        throw new Error(`Massif height must be an integer ${MIN_MASSIF_HEIGHT}..${MAX_MASSIF_HEIGHT}, got ${massifHeight}`);
+    }
+    if (logId.length === 0 || logId.includes("/")) {
+        throw new Error(`Log id must be a non-empty path segment, got: ${JSON.stringify(logId)}`);
+    }
+}

package/dist/mmr/index.d.ts

@@ -21,7 +21,7 @@ export declare function leafMinusSpurSum(leafIndex: bigint): bigint;
  *
  * Translated from go-merklelog/massifs/massifstart.go MassifFirstLeaf
  */
-export declare function massifFirstLeaf(massifHeight: number, massifIndex: number): bigint;
+export declare function massifFirstLeaf(massifHeight: number, massifIndex: number | bigint): bigint;
 /**
  * Returns the node index for the leaf e
  *

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

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/mmr/index.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH;;;;;;;;GAQG;AACH,wBAAgB,gBAAgB,CAAC,SAAS,EAAE,MAAM,GAAG,MAAM,CAQ1D;AAED;;;;GAIG;AACH,wBAAgB,eAAe,CAC7B,YAAY,EAAE,MAAM,EACpB,WAAW,EAAE,MAAM,GAClB,MAAM,CAYR;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,QAAQ,CAAC,SAAS,EAAE,MAAM,GAAG,MAAM,CAalD"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/mmr/index.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH;;;;;;;;GAQG;AACH,wBAAgB,gBAAgB,CAAC,SAAS,EAAE,MAAM,GAAG,MAAM,CAQ1D;AAED;;;;GAIG;AACH,wBAAgB,eAAe,CAC7B,YAAY,EAAE,MAAM,EACpB,WAAW,EAAE,MAAM,GAAG,MAAM,GAC3B,MAAM,CAaR;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,QAAQ,CAAC,SAAS,EAAE,MAAM,GAAG,MAAM,CAalD"}

package/dist/mmr/index.js

@@ -30,8 +30,9 @@ export function leafMinusSpurSum(leafIndex) {
  * Translated from go-merklelog/massifs/massifstart.go MassifFirstLeaf
  */
 export function massifFirstLeaf(massifHeight, massifIndex) {
-    // The number of nodes 'm' in a massif is: m = (1 << h) - 1
-    const m = BigInt((1 << massifHeight) - 1);
+    // The number of nodes 'm' in a massif is: m = (1 << h) - 1. BigInt shift:
+    // a JS number `1 << h` is negative at h=31 and wraps at h=32.
+    const m = (1n << BigInt(massifHeight)) - 1n;
     // The number of leaves 'f' in every massif: f = (m + 1) / 2
     const f = (m + 1n) >> 1n;
     // The first leaf index is then: leafIndex = f * massifIndex

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@forestrie/merklelog",
-  "version": "0.5.0",
+  "version": "0.7.0",
   "license": "MIT",
   "type": "module",
   "description": "MMR (merkle mountain range) proofs and massif storage format for Forestrie transparency logs",

package/src/index.ts

@@ -43,9 +43,17 @@ export {
   isMassifFull,
 } from "./massifs/types.js";
 
-export { parseV2StorageObjectPath } from "./massifs/v2storagepaths.js";
+export {
+  formatMassifObjectIndex,
+  MASSIF_OBJECT_INDEX_DIGITS,
+  MAX_MASSIF_INDEX,
+  parseV2StorageObjectPath,
+  v2CheckpointObjectKey,
+  v2MassifObjectKey,
+} from "./massifs/v2storagepaths.js";
 
 // Massif blob node access for MMR proof building (plan-2607-15 §4)
+export { massifIndexFromLeafIndex } from "./massifs/massifindex.js";
 export { openMassifNodeStore } from "./massifs/nodestore.js";
 export type { MassifNodeStore } from "./massifs/nodestore.js";
 

package/src/massifs/massifindex.ts

@@ -0,0 +1,28 @@
+/**
+ * Which massif holds a leaf. A massif of one-based height h holds
+ * 2^(h-1) leaves; see {@link leafCountForMassifHeight} and the
+ * go-merklelog notation in
+ * [mmr-math-cheatsheet.md](https://github.com/forestrie/go-merklelog/blob/main/mmr-math-cheatsheet.md).
+ * Mirrors go-merklelog `massifs/massifindex.go` MassifIndexFromLeafIndex,
+ * which arbor's ranger uses when it commits massifs.
+ */
+
+import { leafCountForMassifHeight } from "./indexformat.js";
+
+/**
+ * Returns the zero-based index of the massif that holds the leaf at
+ * `leafIndex` (zero-based, counting leaves only).
+ *
+ * @param massifHeight - One-based massif height (h >= 1)
+ * @throws RangeError when massifHeight is 0, which holds no leaves
+ */
+export function massifIndexFromLeafIndex(
+  massifHeight: number,
+  leafIndex: bigint | number,
+): bigint {
+  const leavesPerMassif = leafCountForMassifHeight(massifHeight);
+  if (leavesPerMassif === 0n) {
+    throw new RangeError("massifHeight must be at least 1");
+  }
+  return BigInt(leafIndex) / leavesPerMassif;
+}

package/src/massifs/v2storagepaths.ts

@@ -1,56 +1,106 @@
 /**
- * Parse an R2 object path to extract log ID, massif height, and massif index.
+ * Merklelog v2 R2 object layout:
  *
  * - v2/merklelog/massifs/{massifHeight}/{logId}/{massifIndex}.log
  * - v2/merklelog/checkpoints/{massifHeight}/{logId}/{massifIndex}.sth
  *
- * @param path - The object path path from the R2 notification
+ * `{massifIndex}` is a zero-padded, 16-digit DECIMAL integer. The Go writer
+ * owns this convention: go-merklelog
+ * [massifs/storage/const.go](https://github.com/forestrie/go-merklelog/blob/main/massifs/storage/const.go)
+ * (`V1MMRBlobNameFmt = "%016d.log"`, `V1MMRSignedTreeHeadBlobNameFmt =
+ * "%016d.sth"`) and its reader
+ * [objectindexfrompath.go](https://github.com/forestrie/go-merklelog/blob/main/massifs/storage/objectindexfrompath.go)
+ * (`strconv.Atoi`). canopy-api builds its R2 keys through the functions
+ * here (FOR-621: an earlier reader parsed hex, which agrees with the writer
+ * only for indices 0-9). Code outside this package that spells a key by hand
+ * (delegation-coordinator `seal-hint.ts`, test fixtures, demos) uses only
+ * index 0, which reads the same in any radix; anything that needs another
+ * index must use these helpers.
+ */
+
+/** Width of the massif index segment in an object key. */
+export const MASSIF_OBJECT_INDEX_DIGITS = 16;
+
+/**
+ * Largest massif index the Go side can represent. go-merklelog
+ * `FmtMassifPath(prefix, massifIndex uint32)` and arbor's publisher
+ * (`strconv.ParseUint(base, 10, 32)`) use `uint32`; a larger index would be
+ * silently truncated by `ObjectIndexFromPath`, so it is rejected here.
+ */
+export const MAX_MASSIF_INDEX = 0xffffffffn;
+
+/**
+ * Massif height bounds. Go writes height as `%d` of a `uint8` and arbor's
+ * publisher `ParseCheckpointKey` rejects 0, so valid heights are 1..255 with
+ * no leading zeros.
+ */
+const MIN_MASSIF_HEIGHT = 1;
+const MAX_MASSIF_HEIGHT = 255;
+
+const MASSIF_OBJECT_INDEX_RE = /^[0-9]{16}$/;
+const MASSIF_HEIGHT_RE = /^[1-9][0-9]{0,2}$/;
+const OBJECT_EXTENSIONS: Readonly<Record<string, string>> = {
+  massifs: ".log",
+  checkpoints: ".sth",
+};
+
+/**
+ * Parse an R2 object path to extract log ID, massif height, and massif index.
+ *
+ * @param path - The object path from the R2 notification
  * @returns Parsed components including logId, massifHeight, and massifIndex
  * @throws Error if the path doesn't match expected format or if parsing fails
  */
 export function parseV2StorageObjectPath(path: string) {
   const parts = path.split("/");
 
-  if (parts.length < 6 || parts[0] !== "v2" || parts[1] !== "merklelog")
+  if (parts.length !== 6 || parts[0] !== "v2" || parts[1] !== "merklelog")
     throw new Error(`Unrecognized path format: ${path}`);
 
-  // Check for new v2 format: v2/merklelog/massifs/{massifHeight}/{logId}/{index}.log
-  // or v2/merklelog/checkpoints/{massifHeight}/{logId}/{index}.sth
-  const typePart = parts[2]; // "massifs" or "checkpoints"
+  const typePart = parts[2];
   const massifHeightStr = parts[3];
   const logId = parts[4];
   const filename = parts[5];
 
-  // Validate extension
-  const expectedExt = typePart === "massifs" ? ".log" : ".sth";
+  const expectedExt = Object.hasOwn(OBJECT_EXTENSIONS, typePart)
+    ? OBJECT_EXTENSIONS[typePart]
+    : undefined;
+  if (expectedExt === undefined) {
+    throw new Error(
+      `Object type must be massifs or checkpoints, got: ${typePart}`,
+    );
+  }
+  if (logId.length === 0) {
+    throw new Error(`Log id segment is empty: ${path}`);
+  }
   if (!filename.endsWith(expectedExt)) {
     throw new Error(
       `Expected ${expectedExt} extension for ${typePart}, got: ${filename}`,
     );
   }
 
-  // Parse massif index (hex, 16 digits)
   const massifIndexStr = filename.slice(0, -expectedExt.length);
-  if (massifIndexStr.length !== 16) {
+  if (!MASSIF_OBJECT_INDEX_RE.test(massifIndexStr)) {
     throw new Error(
-      `Massif index must be 16 hex digits, got ${massifIndexStr.length}: ${massifIndexStr}`,
+      `Massif index must be 16 decimal digits, got: ${massifIndexStr}`,
     );
   }
-
-  const massifIndex = Number.parseInt(massifIndexStr, 16);
-  if (!Number.isFinite(massifIndex)) {
+  const massifIndex = BigInt(massifIndexStr);
+  if (massifIndex > MAX_MASSIF_INDEX) {
     throw new Error(
-      `Failed to parse massif index as hex number: ${massifIndexStr}`,
+      `Massif index must be 0..${MAX_MASSIF_INDEX}, got ${massifIndex}`,
     );
   }
 
-  // Parse massifHeight
-  const massifHeight = Number.parseInt(massifHeightStr, 10);
-  if (!Number.isFinite(massifHeight)) {
+  if (
+    !MASSIF_HEIGHT_RE.test(massifHeightStr) ||
+    Number(massifHeightStr) > MAX_MASSIF_HEIGHT
+  ) {
     throw new Error(
       `Failed to parse massif height as number: ${massifHeightStr}`,
     );
   }
+  const massifHeight = Number(massifHeightStr);
 
   return {
     logId,
@@ -59,3 +109,68 @@ export function parseV2StorageObjectPath(path: string) {
     type: typePart,
   };
 }
+
+/**
+ * Build the massif `.log` object key for a log.
+ */
+export function v2MassifObjectKey(
+  massifHeight: number,
+  logId: string,
+  massifIndex: bigint | number,
+): string {
+  assertKeyHeightAndLogId(massifHeight, logId);
+  return `v2/merklelog/massifs/${massifHeight}/${logId}/${formatMassifObjectIndex(massifIndex)}.log`;
+}
+
+/**
+ * Build the signed checkpoint `.sth` object key for a log.
+ */
+export function v2CheckpointObjectKey(
+  massifHeight: number,
+  logId: string,
+  massifIndex: bigint | number,
+): string {
+  assertKeyHeightAndLogId(massifHeight, logId);
+  return `v2/merklelog/checkpoints/${massifHeight}/${logId}/${formatMassifObjectIndex(massifIndex)}.sth`;
+}
+
+/**
+ * Format a massif index as the 16-digit decimal key segment (Go `%016d`).
+ *
+ * @throws Error if the index is negative, not an integer, not a safe integer
+ *   (number input), or exceeds {@link MAX_MASSIF_INDEX}.
+ */
+export function formatMassifObjectIndex(massifIndex: bigint | number): string {
+  if (typeof massifIndex === "number" && !Number.isSafeInteger(massifIndex)) {
+    throw new Error(`Massif index must be a safe integer, got ${massifIndex}`);
+  }
+  const index = BigInt(massifIndex);
+  if (index < 0n || index > MAX_MASSIF_INDEX) {
+    throw new Error(
+      `Massif index must be 0..${MAX_MASSIF_INDEX}, got ${index}`,
+    );
+  }
+  return index.toString(10).padStart(MASSIF_OBJECT_INDEX_DIGITS, "0");
+}
+
+/**
+ * Reject a massif height or log id that would build a key Go cannot read:
+ * height outside 1..255 or non-integer, or a log id that is empty or would
+ * add path segments.
+ */
+function assertKeyHeightAndLogId(massifHeight: number, logId: string): void {
+  if (
+    !Number.isInteger(massifHeight) ||
+    massifHeight < MIN_MASSIF_HEIGHT ||
+    massifHeight > MAX_MASSIF_HEIGHT
+  ) {
+    throw new Error(
+      `Massif height must be an integer ${MIN_MASSIF_HEIGHT}..${MAX_MASSIF_HEIGHT}, got ${massifHeight}`,
+    );
+  }
+  if (logId.length === 0 || logId.includes("/")) {
+    throw new Error(
+      `Log id must be a non-empty path segment, got: ${JSON.stringify(logId)}`,
+    );
+  }
+}

package/src/mmr/index.ts

@@ -33,10 +33,11 @@ export function leafMinusSpurSum(leafIndex: bigint): bigint {
  */
 export function massifFirstLeaf(
   massifHeight: number,
-  massifIndex: number,
+  massifIndex: number | bigint,
 ): bigint {
-  // The number of nodes 'm' in a massif is: m = (1 << h) - 1
-  const m = BigInt((1 << massifHeight) - 1);
+  // The number of nodes 'm' in a massif is: m = (1 << h) - 1. BigInt shift:
+  // a JS number `1 << h` is negative at h=31 and wraps at h=32.
+  const m = (1n << BigInt(massifHeight)) - 1n;
 
   // The number of leaves 'f' in every massif: f = (m + 1) / 2
   const f = (m + 1n) >> 1n;