@forestrie/merklelog 0.4.0 → 0.6.0

package/dist/index.d.ts

@@ -11,7 +11,7 @@ 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 { openMassifNodeStore } from "./massifs/nodestore.js";
 export type { MassifNodeStore } from "./massifs/nodestore.js";
 export { openMassifLeafIndex, MissingIndexError } from "./massifs/leafindex.js";
@@ -19,7 +19,7 @@ export type { MassifLeafIndex, LocatedLeaf } 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, consistentRoots, consistentRootsForSizes, indexConsistencyProof, type ConsistencyProof, } from "./mmr/algorithms.js";
-export { ConsistencyShapeError, IncompleteTreeSize, ConsistencyPeakCountMismatch, ConsistencyPathLengthMismatch, ConsistencyRootMismatch, SizeMustIncrease, } from "./mmr/errors.js";
+export { ConsistencyShapeError, IncompleteTreeSize, ConsistencyPeakCountMismatch, ConsistencyPathLengthMismatch, ConsistencyPathMalformed, ConsistencyRootMismatch, SizeMustIncrease, SizeNotUint64, } from "./mmr/errors.js";
 export { createSyncHasher } from "./mmr/algorithms-sync.js";
 export type { Proof, Peak } from "./mmr/types.js";
 export type { Hasher } from "./mmr/types.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,uBAAuB,EACvB,gBAAgB,GACjB,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,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,7 +12,7 @@ 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 { openMassifNodeStore } from "./massifs/nodestore.js";
 // Content-hash leaf lookup over the massif index region (FOR-373)
@@ -23,7 +23,7 @@ export { heightIndex, height, mmrIndexFromLeafIndex, leafIndex, mmrPosition, mmr
 export { bagPeaks, calculateRoot, verifyInclusion, verifyConsistency, consistentRoots, consistentRootsForSizes, indexConsistencyProof, } from "./mmr/algorithms.js";
 // Typed proof-shape rejections raised by consistentRootsForSizes (names
 // mirror the Solidity IUnivocityErrors members) — plan-2609-10 s4.3, FOR-568.
-export { ConsistencyShapeError, IncompleteTreeSize, ConsistencyPeakCountMismatch, ConsistencyPathLengthMismatch, ConsistencyRootMismatch, SizeMustIncrease, } from "./mmr/errors.js";
+export { ConsistencyShapeError, IncompleteTreeSize, ConsistencyPeakCountMismatch, ConsistencyPathLengthMismatch, ConsistencyPathMalformed, ConsistencyRootMismatch, SizeMustIncrease, SizeNotUint64, } from "./mmr/errors.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, inclusionProofPath, inclusionProofLocalExtend, peakMMRIndexes, peaksBitmap, peakIndexForLeafProof, mmrSizeForLeafCount, indexHeight, firstMMRSize, massifIndexFromMMRIndex, peakStackMap, } from "./mmr/proof.js";

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/algorithms.d.ts

@@ -129,10 +129,13 @@ export declare function consistentRoots(hasher: Hasher, ifrom: bigint, accumulat
  *   any), and `expectedRight`, the number of MMR(sizeTo) peaks the prover must
  *   supply as right peaks. `roots` followed by those right peaks is the
  *   accumulator of MMR(sizeTo).
+ * @throws {SizeNotUint64} if either size is outside `[0, 2^64 - 1]`
  * @throws {SizeMustIncrease} if `sizeTo <= sizeFrom`
  * @throws {IncompleteTreeSize} if `sizeTo` is not a complete MMR size
  * @throws {ConsistencyPeakCountMismatch} if `accumulatorFrom` or `paths` does
  *   not have one entry per origin peak
+ * @throws {ConsistencyPathMalformed} if `paths` is not a dense array of
+ *   `Uint8Array[]`
  * @throws {ConsistencyPathLengthMismatch} if a path length differs from the
  *   length the two sizes imply
  * @throws {ConsistencyRootMismatch} if two paths under one target peak produce

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

@@ -1 +1 @@
-{"version":3,"file":"algorithms.d.ts","sourceRoot":"","sources":["../../src/mmr/algorithms.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,EAAE,MAAM,YAAY,CAAC;AAChD,OAAO,EAOL,KAAK,UAAU,EAChB,MAAM,YAAY,CAAC;AA4BpB;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAsB,QAAQ,CAC5B,MAAM,EAAE,MAAM,EACd,KAAK,EAAE,UAAU,EAAE,GAClB,OAAO,CAAC,UAAU,CAAC,CAwBrB;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAsB,aAAa,CACjC,MAAM,EAAE,MAAM,EACd,QAAQ,EAAE,UAAU,EACpB,KAAK,EAAE,KAAK,EACZ,SAAS,EAAE,MAAM,GAChB,OAAO,CAAC,UAAU,CAAC,CAkCrB;AAED;;;;;;;;GAQG;AACH,wBAAsB,eAAe,CACnC,MAAM,EAAE,MAAM,EACd,QAAQ,EAAE,UAAU,EACpB,KAAK,EAAE,KAAK,EACZ,IAAI,EAAE,UAAU,GACf,OAAO,CAAC,OAAO,CAAC,CAUlB;AAED;;;;GAIG;AACH,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,EAAE,MAAM,CAAC;IACjB,QAAQ,EAAE,MAAM,CAAC;IACjB,mEAAmE;IACnE,KAAK,EAAE,UAAU,EAAE,EAAE,CAAC;CACvB;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAsB,eAAe,CACnC,MAAM,EAAE,MAAM,EACd,KAAK,EAAE,MAAM,EACb,eAAe,EAAE,UAAU,EAAE,EAC7B,KAAK,EAAE,UAAU,EAAE,EAAE,GACpB,OAAO,CAAC,UAAU,EAAE,CAAC,CA0BvB;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+CG;AACH,wBAAsB,uBAAuB,CAC3C,MAAM,EAAE,MAAM,EACd,QAAQ,EAAE,MAAM,EAChB,MAAM,EAAE,MAAM,EACd,eAAe,EAAE,UAAU,EAAE,EAC7B,KAAK,EAAE,UAAU,EAAE,EAAE,GACpB,OAAO,CAAC;IAAE,KAAK,EAAE,UAAU,EAAE,CAAC;IAAC,aAAa,EAAE,MAAM,CAAA;CAAE,CAAC,CA+EzD;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2CG;AACH,wBAAsB,iBAAiB,CACrC,MAAM,EAAE,MAAM,EACd,QAAQ,EAAE,MAAM,EAChB,MAAM,EAAE,MAAM,EACd,SAAS,EAAE,UAAU,EAAE,EACvB,KAAK,EAAE,UAAU,EAAE,EAAE,EACrB,OAAO,EAAE,UAAU,EAAE,GACpB,OAAO,CAAC;IAAE,EAAE,EAAE,OAAO,CAAC;IAAC,WAAW,EAAE,UAAU,EAAE,CAAA;CAAE,CAAC,CAqBrD;AAED;;;;;GAKG;AACH,wBAAgB,qBAAqB,CACnC,GAAG,EAAE,UAAU,EACf,SAAS,EAAE,MAAM,EACjB,SAAS,EAAE,MAAM,GAChB,gBAAgB,CAMlB"}
+{"version":3,"file":"algorithms.d.ts","sourceRoot":"","sources":["../../src/mmr/algorithms.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,EAAE,MAAM,YAAY,CAAC;AAChD,OAAO,EAOL,KAAK,UAAU,EAChB,MAAM,YAAY,CAAC;AAsCpB;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAsB,QAAQ,CAC5B,MAAM,EAAE,MAAM,EACd,KAAK,EAAE,UAAU,EAAE,GAClB,OAAO,CAAC,UAAU,CAAC,CAwBrB;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAsB,aAAa,CACjC,MAAM,EAAE,MAAM,EACd,QAAQ,EAAE,UAAU,EACpB,KAAK,EAAE,KAAK,EACZ,SAAS,EAAE,MAAM,GAChB,OAAO,CAAC,UAAU,CAAC,CAkCrB;AAED;;;;;;;;GAQG;AACH,wBAAsB,eAAe,CACnC,MAAM,EAAE,MAAM,EACd,QAAQ,EAAE,UAAU,EACpB,KAAK,EAAE,KAAK,EACZ,IAAI,EAAE,UAAU,GACf,OAAO,CAAC,OAAO,CAAC,CAUlB;AAED;;;;GAIG;AACH,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,EAAE,MAAM,CAAC;IACjB,QAAQ,EAAE,MAAM,CAAC;IACjB,mEAAmE;IACnE,KAAK,EAAE,UAAU,EAAE,EAAE,CAAC;CACvB;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAsB,eAAe,CACnC,MAAM,EAAE,MAAM,EACd,KAAK,EAAE,MAAM,EACb,eAAe,EAAE,UAAU,EAAE,EAC7B,KAAK,EAAE,UAAU,EAAE,EAAE,GACpB,OAAO,CAAC,UAAU,EAAE,CAAC,CA0BvB;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkDG;AACH,wBAAsB,uBAAuB,CAC3C,MAAM,EAAE,MAAM,EACd,QAAQ,EAAE,MAAM,EAChB,MAAM,EAAE,MAAM,EACd,eAAe,EAAE,UAAU,EAAE,EAC7B,KAAK,EAAE,UAAU,EAAE,EAAE,GACpB,OAAO,CAAC;IAAE,KAAK,EAAE,UAAU,EAAE,CAAC;IAAC,aAAa,EAAE,MAAM,CAAA;CAAE,CAAC,CA2FzD;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2CG;AACH,wBAAsB,iBAAiB,CACrC,MAAM,EAAE,MAAM,EACd,QAAQ,EAAE,MAAM,EAChB,MAAM,EAAE,MAAM,EACd,SAAS,EAAE,UAAU,EAAE,EACvB,KAAK,EAAE,UAAU,EAAE,EAAE,EACrB,OAAO,EAAE,UAAU,EAAE,GACpB,OAAO,CAAC;IAAE,EAAE,EAAE,OAAO,CAAC;IAAC,WAAW,EAAE,UAAU,EAAE,CAAA;CAAE,CAAC,CAqBrD;AAED;;;;;GAKG;AACH,wBAAgB,qBAAqB,CACnC,GAAG,EAAE,UAAU,EACf,SAAS,EAAE,MAAM,EACjB,SAAS,EAAE,MAAM,GAChB,gBAAgB,CAMlB"}

package/dist/mmr/algorithms.js

@@ -11,10 +11,17 @@
  * https://raw.githubusercontent.com/robinbryce/draft-bryce-cose-receipts-mmr-profile/refs/heads/main/draft-bryce-cose-receipts-mmr-profile.md
  */
 import { inclusionProof, peakMMRIndexes, bitLength, popcount, peaksBitmap, mmrSizeForLeafCount, } from "./proof.js";
-import { ConsistencyPathLengthMismatch, ConsistencyPeakCountMismatch, ConsistencyRootMismatch, IncompleteTreeSize, SizeMustIncrease, } from "./errors.js";
+import { ConsistencyPathLengthMismatch, ConsistencyPathMalformed, ConsistencyPeakCountMismatch, ConsistencyRootMismatch, IncompleteTreeSize, SizeMustIncrease, SizeNotUint64, } from "./errors.js";
 import { Uint64 } from "../uint64/index.js";
 import { heightIndex } from "./math.js";
 import { arraysEqual } from "../utils/arrays.js";
+/**
+ * Upper bound of the uint64 domain the MMR profile's sizes live in: Solidity
+ * and Go take every size as `uint64`, and a CBOR unsigned integer caps here
+ * too. `bigint` carries no such bound, so {@link consistentRootsForSizes}
+ * states it.
+ */
+const MAX_UINT64 = (1n << 64n) - 1n;
 /**
  * Encodes a Uint64 as 8 bytes big-endian.
  *
@@ -208,16 +215,27 @@ export async function consistentRoots(hasher, ifrom, accumulatorFrom, paths) {
  *   any), and `expectedRight`, the number of MMR(sizeTo) peaks the prover must
  *   supply as right peaks. `roots` followed by those right peaks is the
  *   accumulator of MMR(sizeTo).
+ * @throws {SizeNotUint64} if either size is outside `[0, 2^64 - 1]`
  * @throws {SizeMustIncrease} if `sizeTo <= sizeFrom`
  * @throws {IncompleteTreeSize} if `sizeTo` is not a complete MMR size
  * @throws {ConsistencyPeakCountMismatch} if `accumulatorFrom` or `paths` does
  *   not have one entry per origin peak
+ * @throws {ConsistencyPathMalformed} if `paths` is not a dense array of
+ *   `Uint8Array[]`
  * @throws {ConsistencyPathLengthMismatch} if a path length differs from the
  *   length the two sizes imply
  * @throws {ConsistencyRootMismatch} if two paths under one target peak produce
  *   different roots
  */
 export async function consistentRootsForSizes(hasher, sizeFrom, sizeTo, accumulatorFrom, paths) {
+    // The sizes are uint64 in Solidity and Go; `bigint` carries no such bound,
+    // so it is stated here before any arithmetic reads them.
+    if (sizeFrom < 0n || sizeFrom > MAX_UINT64) {
+        throw new SizeNotUint64("sizeFrom", sizeFrom);
+    }
+    if (sizeTo < 0n || sizeTo > MAX_UINT64) {
+        throw new SizeNotUint64("sizeTo", sizeTo);
+    }
     if (sizeTo <= sizeFrom) {
         throw new SizeMustIncrease(sizeFrom, sizeTo);
     }
@@ -234,9 +252,13 @@ export async function consistentRootsForSizes(hasher, sizeFrom, sizeTo, accumula
     if (accumulatorFrom.length !== n) {
         throw new ConsistencyPeakCountMismatch(n, accumulatorFrom.length);
     }
+    if (!Array.isArray(paths)) {
+        throw new ConsistencyPathMalformed(`not an array (got ${typeName(paths)})`);
+    }
     if (paths.length !== n) {
         throw new ConsistencyPeakCountMismatch(n, paths.length);
     }
+    assertDensePaths(paths);
     const nto = popcount(to);
     if (n === 0) {
         return { roots: [], expectedRight: nto };
@@ -364,3 +386,34 @@ export function indexConsistencyProof(get, mmrIndexA, mmrIndexB) {
     }
     return { mmrSizeA: mmrIndexA + 1n, mmrSizeB: mmrIndexB + 1n, paths };
 }
+/** Name the value found where a path or a path element was required. */
+function typeName(value) {
+    if (value === null)
+        return "null";
+    if (Array.isArray(value))
+        return "an array";
+    return typeof value;
+}
+/**
+ * Require `paths` to be a DENSE array of `Uint8Array[]`: no holes, and every
+ * element an array of `Uint8Array`. A hole and an out-of-type entry both
+ * survive the peak COUNT check and would otherwise reach the hashing loop,
+ * where they surface as a bare `TypeError` outside the
+ * `ConsistencyShapeError` family (review finding C6).
+ */
+function assertDensePaths(paths) {
+    for (let i = 0; i < paths.length; i++) {
+        if (!(i in paths)) {
+            throw new ConsistencyPathMalformed("missing (the array is sparse)", i);
+        }
+        const path = paths[i];
+        if (!Array.isArray(path)) {
+            throw new ConsistencyPathMalformed(`not an array (got ${typeName(path)})`, i);
+        }
+        for (let j = 0; j < path.length; j++) {
+            if (!(j in path) || !(path[j] instanceof Uint8Array)) {
+                throw new ConsistencyPathMalformed(`element ${j} is not a Uint8Array (got ${typeName(path[j])})`, i);
+            }
+        }
+    }
+}

package/dist/mmr/errors.d.ts

@@ -66,4 +66,35 @@ export declare class SizeMustIncrease extends ConsistencyShapeError {
     readonly sizeTo: bigint;
     constructor(sizeFrom: bigint, sizeTo: bigint);
 }
+/**
+ * A size is outside the uint64 domain the MMR profile's sizes live in.
+ *
+ * Solidity and Go take these sizes as `uint64`, so the domain is part of
+ * their signatures; TypeScript's `bigint` has no bound of its own. Without
+ * this check a size at or above 2^64 folds here and nowhere else: the
+ * position prefix `hash_pospair64` writes is truncated to eight bytes, so
+ * the hashes computed above the bound are not the ones the other two
+ * implementations would compute, and a size that large is not one a CBOR
+ * unsigned integer can carry or the contract can store either.
+ */
+export declare class SizeNotUint64 extends ConsistencyShapeError {
+    readonly which: "sizeFrom" | "sizeTo";
+    readonly size: bigint;
+    constructor(which: "sizeFrom" | "sizeTo", size: bigint);
+}
+/**
+ * `paths` is not a dense array of `Uint8Array[]`.
+ *
+ * A hole (a sparse array), a `null`/`undefined` entry, a path that is not an
+ * array, or a path element that is not a `Uint8Array` all survive the peak
+ * COUNT check and then surface as a bare `TypeError` out of the fold, which
+ * escapes the {@link ConsistencyShapeError} family callers are told to
+ * switch on. The shape of the proof material is a proof-shape condition like
+ * any other, so it is reported as one.
+ */
+export declare class ConsistencyPathMalformed extends ConsistencyShapeError {
+    readonly detail: string;
+    readonly index?: number | undefined;
+    constructor(detail: string, index?: number | undefined);
+}
 //# sourceMappingURL=errors.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../../src/mmr/errors.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,8DAA8D;AAC9D,qBAAa,qBAAsB,SAAQ,KAAK;gBAClC,OAAO,EAAE,MAAM;CAI5B;AAED;;;;;;;GAOG;AACH,qBAAa,kBAAmB,SAAQ,qBAAqB;IAC/C,QAAQ,CAAC,IAAI,EAAE,MAAM;gBAAZ,IAAI,EAAE,MAAM;CAIlC;AAED;;;GAGG;AACH,qBAAa,4BAA6B,SAAQ,qBAAqB;IAEnE,QAAQ,CAAC,QAAQ,EAAE,MAAM;IACzB,QAAQ,CAAC,MAAM,EAAE,MAAM;gBADd,QAAQ,EAAE,MAAM,EAChB,MAAM,EAAE,MAAM;CAK1B;AAED;;;GAGG;AACH,qBAAa,6BAA8B,SAAQ,qBAAqB;IAEpE,QAAQ,CAAC,KAAK,EAAE,MAAM;IACtB,QAAQ,CAAC,QAAQ,EAAE,MAAM;IACzB,QAAQ,CAAC,MAAM,EAAE,MAAM;gBAFd,KAAK,EAAE,MAAM,EACb,QAAQ,EAAE,MAAM,EAChB,MAAM,EAAE,MAAM;CAK1B;AAED;;;;GAIG;AACH,qBAAa,uBAAwB,SAAQ,qBAAqB;IACpD,QAAQ,CAAC,KAAK,EAAE,MAAM;gBAAb,KAAK,EAAE,MAAM;CAInC;AAED;;;GAGG;AACH,qBAAa,gBAAiB,SAAQ,qBAAqB;IAEvD,QAAQ,CAAC,QAAQ,EAAE,MAAM;IACzB,QAAQ,CAAC,MAAM,EAAE,MAAM;gBADd,QAAQ,EAAE,MAAM,EAChB,MAAM,EAAE,MAAM;CAK1B"}
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../../src/mmr/errors.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,8DAA8D;AAC9D,qBAAa,qBAAsB,SAAQ,KAAK;gBAClC,OAAO,EAAE,MAAM;CAI5B;AAED;;;;;;;GAOG;AACH,qBAAa,kBAAmB,SAAQ,qBAAqB;IAC/C,QAAQ,CAAC,IAAI,EAAE,MAAM;gBAAZ,IAAI,EAAE,MAAM;CAIlC;AAED;;;GAGG;AACH,qBAAa,4BAA6B,SAAQ,qBAAqB;IAEnE,QAAQ,CAAC,QAAQ,EAAE,MAAM;IACzB,QAAQ,CAAC,MAAM,EAAE,MAAM;gBADd,QAAQ,EAAE,MAAM,EAChB,MAAM,EAAE,MAAM;CAK1B;AAED;;;GAGG;AACH,qBAAa,6BAA8B,SAAQ,qBAAqB;IAEpE,QAAQ,CAAC,KAAK,EAAE,MAAM;IACtB,QAAQ,CAAC,QAAQ,EAAE,MAAM;IACzB,QAAQ,CAAC,MAAM,EAAE,MAAM;gBAFd,KAAK,EAAE,MAAM,EACb,QAAQ,EAAE,MAAM,EAChB,MAAM,EAAE,MAAM;CAK1B;AAED;;;;GAIG;AACH,qBAAa,uBAAwB,SAAQ,qBAAqB;IACpD,QAAQ,CAAC,KAAK,EAAE,MAAM;gBAAb,KAAK,EAAE,MAAM;CAInC;AAED;;;GAGG;AACH,qBAAa,gBAAiB,SAAQ,qBAAqB;IAEvD,QAAQ,CAAC,QAAQ,EAAE,MAAM;IACzB,QAAQ,CAAC,MAAM,EAAE,MAAM;gBADd,QAAQ,EAAE,MAAM,EAChB,MAAM,EAAE,MAAM;CAK1B;AAED;;;;;;;;;;GAUG;AACH,qBAAa,aAAc,SAAQ,qBAAqB;IAEpD,QAAQ,CAAC,KAAK,EAAE,UAAU,GAAG,QAAQ;IACrC,QAAQ,CAAC,IAAI,EAAE,MAAM;gBADZ,KAAK,EAAE,UAAU,GAAG,QAAQ,EAC5B,IAAI,EAAE,MAAM;CAKxB;AAED;;;;;;;;;GASG;AACH,qBAAa,wBAAyB,SAAQ,qBAAqB;IAE/D,QAAQ,CAAC,MAAM,EAAE,MAAM;IACvB,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM;gBADd,MAAM,EAAE,MAAM,EACd,KAAK,CAAC,EAAE,MAAM,YAAA;CAO1B"}

package/dist/mmr/errors.js

@@ -93,3 +93,44 @@ export class SizeMustIncrease extends ConsistencyShapeError {
         this.name = "SizeMustIncrease";
     }
 }
+/**
+ * A size is outside the uint64 domain the MMR profile's sizes live in.
+ *
+ * Solidity and Go take these sizes as `uint64`, so the domain is part of
+ * their signatures; TypeScript's `bigint` has no bound of its own. Without
+ * this check a size at or above 2^64 folds here and nowhere else: the
+ * position prefix `hash_pospair64` writes is truncated to eight bytes, so
+ * the hashes computed above the bound are not the ones the other two
+ * implementations would compute, and a size that large is not one a CBOR
+ * unsigned integer can carry or the contract can store either.
+ */
+export class SizeNotUint64 extends ConsistencyShapeError {
+    which;
+    size;
+    constructor(which, size) {
+        super(`${which} (${size}) is outside the uint64 range [0, 2^64 - 1]`);
+        this.which = which;
+        this.size = size;
+        this.name = "SizeNotUint64";
+    }
+}
+/**
+ * `paths` is not a dense array of `Uint8Array[]`.
+ *
+ * A hole (a sparse array), a `null`/`undefined` entry, a path that is not an
+ * array, or a path element that is not a `Uint8Array` all survive the peak
+ * COUNT check and then surface as a bare `TypeError` out of the fold, which
+ * escapes the {@link ConsistencyShapeError} family callers are told to
+ * switch on. The shape of the proof material is a proof-shape condition like
+ * any other, so it is reported as one.
+ */
+export class ConsistencyPathMalformed extends ConsistencyShapeError {
+    detail;
+    index;
+    constructor(detail, index) {
+        super(index === undefined ? `paths: ${detail}` : `path ${index}: ${detail}`);
+        this.detail = detail;
+        this.index = index;
+        this.name = "ConsistencyPathMalformed";
+    }
+}

package/package.json

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

package/src/index.ts

@@ -43,7 +43,14 @@ 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 { openMassifNodeStore } from "./massifs/nodestore.js";
@@ -82,8 +89,10 @@ export {
   IncompleteTreeSize,
   ConsistencyPeakCountMismatch,
   ConsistencyPathLengthMismatch,
+  ConsistencyPathMalformed,
   ConsistencyRootMismatch,
   SizeMustIncrease,
+  SizeNotUint64,
 } from "./mmr/errors.js";
 export { createSyncHasher } from "./mmr/algorithms-sync.js";
 export type { Proof, Peak } from "./mmr/types.js";

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/algorithms.ts

@@ -23,15 +23,25 @@ import {
 } from "./proof.js";
 import {
   ConsistencyPathLengthMismatch,
+  ConsistencyPathMalformed,
   ConsistencyPeakCountMismatch,
   ConsistencyRootMismatch,
   IncompleteTreeSize,
   SizeMustIncrease,
+  SizeNotUint64,
 } from "./errors.js";
 import { Uint64 } from "../uint64/index.js";
 import { heightIndex } from "./math.js";
 import { arraysEqual } from "../utils/arrays.js";
 
+/**
+ * Upper bound of the uint64 domain the MMR profile's sizes live in: Solidity
+ * and Go take every size as `uint64`, and a CBOR unsigned integer caps here
+ * too. `bigint` carries no such bound, so {@link consistentRootsForSizes}
+ * states it.
+ */
+const MAX_UINT64 = (1n << 64n) - 1n;
+
 /**
  * Encodes a Uint64 as 8 bytes big-endian.
  *
@@ -282,10 +292,13 @@ export async function consistentRoots(
  *   any), and `expectedRight`, the number of MMR(sizeTo) peaks the prover must
  *   supply as right peaks. `roots` followed by those right peaks is the
  *   accumulator of MMR(sizeTo).
+ * @throws {SizeNotUint64} if either size is outside `[0, 2^64 - 1]`
  * @throws {SizeMustIncrease} if `sizeTo <= sizeFrom`
  * @throws {IncompleteTreeSize} if `sizeTo` is not a complete MMR size
  * @throws {ConsistencyPeakCountMismatch} if `accumulatorFrom` or `paths` does
  *   not have one entry per origin peak
+ * @throws {ConsistencyPathMalformed} if `paths` is not a dense array of
+ *   `Uint8Array[]`
  * @throws {ConsistencyPathLengthMismatch} if a path length differs from the
  *   length the two sizes imply
  * @throws {ConsistencyRootMismatch} if two paths under one target peak produce
@@ -298,6 +311,14 @@ export async function consistentRootsForSizes(
   accumulatorFrom: Uint8Array[],
   paths: Uint8Array[][],
 ): Promise<{ roots: Uint8Array[]; expectedRight: number }> {
+  // The sizes are uint64 in Solidity and Go; `bigint` carries no such bound,
+  // so it is stated here before any arithmetic reads them.
+  if (sizeFrom < 0n || sizeFrom > MAX_UINT64) {
+    throw new SizeNotUint64("sizeFrom", sizeFrom);
+  }
+  if (sizeTo < 0n || sizeTo > MAX_UINT64) {
+    throw new SizeNotUint64("sizeTo", sizeTo);
+  }
   if (sizeTo <= sizeFrom) {
     throw new SizeMustIncrease(sizeFrom, sizeTo);
   }
@@ -314,9 +335,13 @@ export async function consistentRootsForSizes(
   if (accumulatorFrom.length !== n) {
     throw new ConsistencyPeakCountMismatch(n, accumulatorFrom.length);
   }
+  if (!Array.isArray(paths)) {
+    throw new ConsistencyPathMalformed(`not an array (got ${typeName(paths)})`);
+  }
   if (paths.length !== n) {
     throw new ConsistencyPeakCountMismatch(n, paths.length);
   }
+  assertDensePaths(paths);
   const nto = popcount(to);
   if (n === 0) {
     return { roots: [], expectedRight: nto };
@@ -469,3 +494,40 @@ export function indexConsistencyProof(
   }
   return { mmrSizeA: mmrIndexA + 1n, mmrSizeB: mmrIndexB + 1n, paths };
 }
+
+/** Name the value found where a path or a path element was required. */
+function typeName(value: unknown): string {
+  if (value === null) return "null";
+  if (Array.isArray(value)) return "an array";
+  return typeof value;
+}
+
+/**
+ * Require `paths` to be a DENSE array of `Uint8Array[]`: no holes, and every
+ * element an array of `Uint8Array`. A hole and an out-of-type entry both
+ * survive the peak COUNT check and would otherwise reach the hashing loop,
+ * where they surface as a bare `TypeError` outside the
+ * `ConsistencyShapeError` family (review finding C6).
+ */
+function assertDensePaths(paths: Uint8Array[][]): void {
+  for (let i = 0; i < paths.length; i++) {
+    if (!(i in paths)) {
+      throw new ConsistencyPathMalformed("missing (the array is sparse)", i);
+    }
+    const path = paths[i] as unknown;
+    if (!Array.isArray(path)) {
+      throw new ConsistencyPathMalformed(
+        `not an array (got ${typeName(path)})`,
+        i,
+      );
+    }
+    for (let j = 0; j < path.length; j++) {
+      if (!(j in path) || !((path[j] as unknown) instanceof Uint8Array)) {
+        throw new ConsistencyPathMalformed(
+          `element ${j} is not a Uint8Array (got ${typeName(path[j])})`,
+          i,
+        );
+      }
+    }
+  }
+}

package/src/mmr/errors.ts

@@ -91,3 +91,46 @@ export class SizeMustIncrease extends ConsistencyShapeError {
     this.name = "SizeMustIncrease";
   }
 }
+
+/**
+ * A size is outside the uint64 domain the MMR profile's sizes live in.
+ *
+ * Solidity and Go take these sizes as `uint64`, so the domain is part of
+ * their signatures; TypeScript's `bigint` has no bound of its own. Without
+ * this check a size at or above 2^64 folds here and nowhere else: the
+ * position prefix `hash_pospair64` writes is truncated to eight bytes, so
+ * the hashes computed above the bound are not the ones the other two
+ * implementations would compute, and a size that large is not one a CBOR
+ * unsigned integer can carry or the contract can store either.
+ */
+export class SizeNotUint64 extends ConsistencyShapeError {
+  constructor(
+    readonly which: "sizeFrom" | "sizeTo",
+    readonly size: bigint,
+  ) {
+    super(`${which} (${size}) is outside the uint64 range [0, 2^64 - 1]`);
+    this.name = "SizeNotUint64";
+  }
+}
+
+/**
+ * `paths` is not a dense array of `Uint8Array[]`.
+ *
+ * A hole (a sparse array), a `null`/`undefined` entry, a path that is not an
+ * array, or a path element that is not a `Uint8Array` all survive the peak
+ * COUNT check and then surface as a bare `TypeError` out of the fold, which
+ * escapes the {@link ConsistencyShapeError} family callers are told to
+ * switch on. The shape of the proof material is a proof-shape condition like
+ * any other, so it is reported as one.
+ */
+export class ConsistencyPathMalformed extends ConsistencyShapeError {
+  constructor(
+    readonly detail: string,
+    readonly index?: number,
+  ) {
+    super(
+      index === undefined ? `paths: ${detail}` : `path ${index}: ${detail}`,
+    );
+    this.name = "ConsistencyPathMalformed";
+  }
+}