@bcts/provenance-mark 1.0.0-alpha.8 → 1.0.0-beta.0

package/src/mark.ts

@@ -1,3 +1,9 @@
+/**
+ * Copyright © 2023-2026 Blockchain Commons, LLC
+ * Copyright © 2025-2026 Parity Technologies
+ *
+ */
+
 // Ported from provenance-mark-rust/src/mark.rs
 
 import { toBase64, fromBase64, bytesToHex } from "./utils.js";
@@ -7,11 +13,16 @@ import {
   BytewordsStyle,
   encodeBytewords,
   decodeBytewords,
-  encodeBytewordsIdentifier,
-  encodeBytemojisIdentifier,
+  encodeToWords,
+  encodeToBytemojis,
+  encodeToMinimalBytewords,
+  UR,
 } from "@bcts/uniform-resources";
+import { Envelope } from "@bcts/envelope";
 
 import { ProvenanceMarkError, ProvenanceMarkErrorType } from "./error.js";
+import { validate as validateMarks } from "./validate.js";
+import type { ValidationIssue, ValidationReport } from "./validate.js";
 import {
   type ProvenanceMarkResolution,
   linkLength,
@@ -30,6 +41,7 @@ import {
   resolutionToCbor,
 } from "./resolution.js";
 import { sha256, sha256Prefix, obfuscate } from "./crypto-utils.js";
+import { dateToDisplay } from "./date.js";
 
 /**
  * A cryptographically-secured provenance mark.
@@ -267,30 +279,213 @@ export class ProvenanceMark {
   }
 
   /**
-   * Get the first four bytes of the hash as a hex string identifier.
+   * The 32-byte Mark ID.
+   *
+   * The first `linkLength` bytes are the mark's stored hash. The remaining
+   * bytes come from the mark's fingerprint (SHA-256 of CBOR encoding),
+   * ensuring a full 32-byte value is always available regardless of
+   * resolution.
+   */
+  id(): Uint8Array {
+    const result = new Uint8Array(32);
+    const n = this._hash.length;
+    result.set(this._hash, 0);
+    if (n < 32) {
+      const fp = this.fingerprint();
+      result.set(fp.subarray(0, 32 - n), n);
+    }
+    return result;
+  }
+
+  /**
+   * The full 32-byte Mark ID as a 64-character hex string.
+   */
+  idHex(): string {
+    return bytesToHex(this.id());
+  }
+
+  /**
+   * The first `wordCount` bytes of the Mark ID as upper-case ByteWords.
+   *
+   * @param wordCount Number of bytes to encode, must be in `4..=32`.
+   * @param prefix If `true`, prepends the provenance-mark prefix character.
+   * @throws if `wordCount` is not in the range `4..=32`.
+   */
+  idBytewords(wordCount: number, prefix: boolean): string {
+    if (!Number.isInteger(wordCount) || wordCount < 4 || wordCount > 32) {
+      throw new Error(`word_count must be 4..=32, got ${wordCount}`);
+    }
+    const s = encodeToWords(this.id().subarray(0, wordCount)).toUpperCase();
+    return prefix ? `\u{1F15F} ${s}` : s;
+  }
+
+  /**
+   * The first `wordCount` bytes of the Mark ID as Bytemoji.
+   *
+   * @param wordCount Number of bytes to encode, must be in `4..=32`.
+   * @param prefix If `true`, prepends the provenance-mark prefix character.
+   * @throws if `wordCount` is not in the range `4..=32`.
+   */
+  idBytemoji(wordCount: number, prefix: boolean): string {
+    if (!Number.isInteger(wordCount) || wordCount < 4 || wordCount > 32) {
+      throw new Error(`word_count must be 4..=32, got ${wordCount}`);
+    }
+    const s = encodeToBytemojis(this.id().subarray(0, wordCount)).toUpperCase();
+    return prefix ? `\u{1F15F} ${s}` : s;
+  }
+
+  /**
+   * The first `wordCount` bytes of the Mark ID as upper-case minimal
+   * ByteWords (2 letters per byte, concatenated without separator).
+   *
+   * @param wordCount Number of bytes to encode, must be in `4..=32`.
+   * @param prefix If `true`, prepends the provenance-mark prefix character.
+   * @throws if `wordCount` is not in the range `4..=32`.
+   */
+  idBytewordsMinimal(wordCount: number, prefix: boolean): string {
+    if (!Number.isInteger(wordCount) || wordCount < 4 || wordCount > 32) {
+      throw new Error(`word_count must be 4..=32, got ${wordCount}`);
+    }
+    const s = encodeToMinimalBytewords(this.id().subarray(0, wordCount)).toUpperCase();
+    return prefix ? `\u{1F15F} ${s}` : s;
+  }
+
+  /**
+   * Legacy 8-character hex identifier — the first 4 bytes of the Mark ID.
+   *
+   * @deprecated Use {@link idHex} for the full 64-char hex, or
+   *   `idHex().slice(0, 8)` for this legacy short form. Retained for
+   *   backwards compatibility; will be removed in a future alpha.
    */
   identifier(): string {
-    return Array.from(this._hash.slice(0, 4))
-      .map((b) => b.toString(16).padStart(2, "0"))
-      .join("");
+    return this.idHex().slice(0, 8);
   }
 
   /**
-   * Get the first four bytes of the hash as upper-case ByteWords.
+   * Legacy 4-byte upper-case ByteWords identifier.
+   *
+   * @deprecated Equivalent to `idBytewords(4, prefix)`. Retained for
+   *   backwards compatibility; will be removed in a future alpha.
    */
   bytewordsIdentifier(prefix: boolean): string {
-    const bytes = this._hash.slice(0, 4);
-    const s = encodeBytewordsIdentifier(bytes).toUpperCase();
-    return prefix ? `\u{1F151} ${s}` : s;
+    return this.idBytewords(4, prefix);
+  }
+
+  /**
+   * Legacy 8-letter minimal ByteWords identifier (first+last letter of each
+   * of the 4 ByteWords). Example: "ABLE ACID ALSO APEX" -> "AEADAOAX".
+   *
+   * @deprecated Equivalent to `idBytewordsMinimal(4, prefix)`. Retained
+   *   for backwards compatibility; will be removed in a future alpha.
+   */
+  bytewordsMinimalIdentifier(prefix: boolean): string {
+    return this.idBytewordsMinimal(4, prefix);
   }
 
   /**
-   * Get the first four bytes of the hash as Bytemoji.
+   * Legacy 4-byte upper-case Bytemoji identifier.
+   *
+   * @deprecated Equivalent to `idBytemoji(4, prefix)`. Retained for
+   *   backwards compatibility; will be removed in a future alpha.
    */
   bytemojiIdentifier(prefix: boolean): string {
-    const bytes = this._hash.slice(0, 4);
-    const s = encodeBytemojisIdentifier(bytes).toUpperCase();
-    return prefix ? `\u{1F151} ${s}` : s;
+    return this.idBytemoji(4, prefix);
+  }
+
+  /**
+   * Computes the minimum prefix length (in bytes, `4..=32`) each mark needs
+   * so that every mark in the set has a unique Mark ID prefix.
+   *
+   * Non-colliding marks get the minimum of 4. Only marks whose 4-byte
+   * prefixes collide are extended.
+   */
+  private static minimalNoncollidingPrefixLengths(ids: Uint8Array[]): number[] {
+    const n = ids.length;
+    const lengths: number[] = new Array<number>(n).fill(4);
+
+    // Group by 4-byte prefix (fast path)
+    const groups = new Map<string, number[]>();
+    for (let i = 0; i < n; i++) {
+      const key = bytesToHex(ids[i].subarray(0, 4));
+      const g = groups.get(key);
+      if (g !== undefined) g.push(i);
+      else groups.set(key, [i]);
+    }
+
+    // Resolve each collision group
+    for (const indices of groups.values()) {
+      if (indices.length <= 1) continue;
+      ProvenanceMark.resolveCollisionGroup(ids, indices, lengths);
+    }
+
+    return lengths;
+  }
+
+  private static resolveCollisionGroup(
+    ids: Uint8Array[],
+    initialIndices: number[],
+    lengths: number[],
+  ): void {
+    let unresolved: number[] = [...initialIndices];
+
+    for (let prefixLen = 5; prefixLen <= 32; prefixLen++) {
+      const subGroups = new Map<string, number[]>();
+      for (const i of unresolved) {
+        const key = bytesToHex(ids[i].subarray(0, prefixLen));
+        const g = subGroups.get(key);
+        if (g !== undefined) g.push(i);
+        else subGroups.set(key, [i]);
+      }
+
+      const nextUnresolved: number[] = [];
+      for (const subIndices of subGroups.values()) {
+        if (subIndices.length === 1) {
+          lengths[subIndices[0]] = prefixLen;
+        } else {
+          nextUnresolved.push(...subIndices);
+        }
+      }
+
+      if (nextUnresolved.length === 0) return;
+      unresolved = nextUnresolved;
+    }
+
+    // At 32 bytes, truly identical IDs remain — assign 32
+    for (const i of unresolved) {
+      lengths[i] = 32;
+    }
+  }
+
+  /**
+   * Returns disambiguated upper-case ByteWords Mark IDs for a set of marks.
+   *
+   * Non-colliding marks get 4-word identifiers. Only marks whose 4-byte
+   * prefixes collide are extended with additional words (up to 32 bytes
+   * per identifier).
+   */
+  static disambiguatedIdBytewords(marks: ProvenanceMark[], prefix: boolean): string[] {
+    const ids = marks.map((m) => m.id());
+    const lengths = ProvenanceMark.minimalNoncollidingPrefixLengths(ids);
+    return ids.map((id, i) => {
+      const s = encodeToWords(id.subarray(0, lengths[i])).toUpperCase();
+      return prefix ? `\u{1F15F} ${s}` : s;
+    });
+  }
+
+  /**
+   * Returns disambiguated Bytemoji Mark IDs for a set of marks.
+   *
+   * Non-colliding marks get 4-emoji identifiers. Only marks whose 4-byte
+   * prefixes collide are extended with additional emojis (up to 32 bytes
+   * per identifier).
+   */
+  static disambiguatedIdBytemoji(marks: ProvenanceMark[], prefix: boolean): string[] {
+    const ids = marks.map((m) => m.id());
+    const lengths = ProvenanceMark.minimalNoncollidingPrefixLengths(ids);
+    return ids.map((id, i) => {
+      const s = encodeToBytemojis(id.subarray(0, lengths[i])).toUpperCase();
+      return prefix ? `\u{1F15F} ${s}` : s;
+    });
   }
 
   /**
@@ -307,30 +502,61 @@ export class ProvenanceMark {
 
   /**
    * Check if this mark precedes another mark, throwing on validation errors.
+   * Errors carry a structured `validationIssue` in their details, matching Rust's
+   * `Error::Validation(ValidationIssue)` pattern.
    */
   precedesOpt(next: ProvenanceMark): void {
     // `next` can't be a genesis
     if (next._seq === 0) {
-      throw new ProvenanceMarkError(ProvenanceMarkErrorType.ValidationError, undefined, {
-        message: "non-genesis mark at sequence 0",
-      });
+      const issue: ValidationIssue = { type: "NonGenesisAtZero" };
+      throw new ProvenanceMarkError(
+        ProvenanceMarkErrorType.ValidationError,
+        "non-genesis mark at sequence 0",
+        { validationIssue: issue },
+      );
     }
     if (arraysEqual(next._key, next._chainId)) {
-      throw new ProvenanceMarkError(ProvenanceMarkErrorType.ValidationError, undefined, {
-        message: "genesis mark must have key equal to chain_id",
-      });
+      const issue: ValidationIssue = { type: "InvalidGenesisKey" };
+      throw new ProvenanceMarkError(
+        ProvenanceMarkErrorType.ValidationError,
+        "genesis mark must have key equal to chain_id",
+        { validationIssue: issue },
+      );
     }
     // `next` must have the next highest sequence number
     if (this._seq !== next._seq - 1) {
-      throw new ProvenanceMarkError(ProvenanceMarkErrorType.ValidationError, undefined, {
-        message: `sequence gap: expected ${this._seq + 1}, got ${next._seq}`,
-      });
+      const issue: ValidationIssue = {
+        type: "SequenceGap",
+        expected: this._seq + 1,
+        actual: next._seq,
+      };
+      throw new ProvenanceMarkError(
+        ProvenanceMarkErrorType.ValidationError,
+        `sequence gap: expected ${this._seq + 1}, got ${next._seq}`,
+        { validationIssue: issue },
+      );
     }
-    // `next` must have an equal or later date
+    // `next` must have an equal or later date.
+    //
+    // Date strings use `dateToDisplay` so the `DateOrdering` issue
+    // payload matches Rust's `Date::Display` exactly: midnight UTC
+    // dates render as `YYYY-MM-DD` (no time suffix), times render
+    // RFC 3339 with second precision. Earlier this port emitted
+    // `2023-06-20T00:00:00Z` for date-only marks, breaking parity with
+    // Rust's `2023-06-20`.
     if (this._date > next._date) {
-      throw new ProvenanceMarkError(ProvenanceMarkErrorType.ValidationError, undefined, {
-        message: `date ordering: ${this._date.toISOString()} > ${next._date.toISOString()}`,
-      });
+      const dateStr = dateToDisplay(this._date);
+      const nextDateStr = dateToDisplay(next._date);
+      const issue: ValidationIssue = {
+        type: "DateOrdering",
+        previous: dateStr,
+        next: nextDateStr,
+      };
+      throw new ProvenanceMarkError(
+        ProvenanceMarkErrorType.ValidationError,
+        `date ordering: ${dateStr} > ${nextDateStr}`,
+        { validationIssue: issue },
+      );
     }
     // `next` must reveal the key that was used to generate this mark's hash
     const expectedHash = ProvenanceMark.makeHash(
@@ -343,15 +569,16 @@ export class ProvenanceMark {
       this._infoBytes,
     );
     if (!arraysEqual(this._hash, expectedHash)) {
-      throw new ProvenanceMarkError(ProvenanceMarkErrorType.ValidationError, undefined, {
-        message: "hash mismatch",
-        expected: Array.from(expectedHash)
-          .map((b) => b.toString(16).padStart(2, "0"))
-          .join(""),
-        actual: Array.from(this._hash)
-          .map((b) => b.toString(16).padStart(2, "0"))
-          .join(""),
-      });
+      const issue: ValidationIssue = {
+        type: "HashMismatch",
+        expected: bytesToHex(expectedHash),
+        actual: bytesToHex(this._hash),
+      };
+      throw new ProvenanceMarkError(
+        ProvenanceMarkErrorType.ValidationError,
+        `hash mismatch: expected ${bytesToHex(expectedHash)}, got ${bytesToHex(this._hash)}`,
+        { validationIssue: issue },
+      );
     }
   }
 
@@ -403,7 +630,7 @@ export class ProvenanceMark {
   }
 
   /**
-   * Encode for URL (minimal bytewords of CBOR).
+   * Encode for URL (minimal bytewords of tagged CBOR).
    */
   toUrlEncoding(): string {
     return encodeBytewords(this.toCborData(), BytewordsStyle.Minimal);
@@ -418,6 +645,39 @@ export class ProvenanceMark {
     return ProvenanceMark.fromTaggedCbor(cborValue);
   }
 
+  /**
+   * Returns the {@link UR} representation of this mark (untagged CBOR
+   * with type `"provenance"`).
+   *
+   * Mirrors Rust `UREncodable::ur()` for `ProvenanceMark` — the
+   * blanket impl on `CBORTaggedEncodable` produces a UR whose
+   * payload is the *untagged* CBOR (the type name itself stands in
+   * for the tag). See `bc-ur-rust/src/ur_encodable.rs:8-18`.
+   */
+  ur(): UR {
+    return UR.new("provenance", this.untaggedCbor());
+  }
+
+  /**
+   * Get the UR string representation (e.g., "ur:provenance/...").
+   */
+  urString(): string {
+    return this.ur().string();
+  }
+
+  /**
+   * Create from a UR string.
+   */
+  static fromURString(urString: string): ProvenanceMark {
+    const ur = UR.fromURString(urString);
+    if (ur.urTypeStr() !== "provenance") {
+      throw new ProvenanceMarkError(ProvenanceMarkErrorType.CborError, undefined, {
+        message: `Expected UR type 'provenance', got '${ur.urTypeStr()}'`,
+      });
+    }
+    return ProvenanceMark.fromUntaggedCbor(ur.cbor());
+  }
+
   /**
    * Build a URL with this mark as a query parameter.
    */
@@ -511,26 +771,48 @@ export class ProvenanceMark {
 
   /**
    * Debug string representation.
+   *
+   * As of provenance-mark v0.24, this includes the full 64-character Mark ID
+   * hex (matching rust's `Display` impl). Pre-v0.24 callers that depended on
+   * the 8-character prefix should use `idHex().slice(0, 8)` directly.
    */
   toString(): string {
-    return `ProvenanceMark(${this.identifier()})`;
+    return `ProvenanceMark(${this.idHex()})`;
   }
 
   /**
    * Detailed debug representation.
+   *
+   * Mirrors Rust `Mark::Debug` exactly: every field is rendered
+   * Rust-style (hex bytes for keys/hashes/IDs, plain integer for
+   * `seq`, `Date::Display` for the date). The Low-resolution test
+   * vector in Rust `tests/mark.rs::test_low_resolution` ends with
+   * `date: 2023-06-20` — i.e. midnight-UTC dates are rendered without
+   * a time suffix. We use {@link dateToDisplay} to mirror that
+   * exactly; earlier revisions of this port stripped just the
+   * `.000Z` fractional component, which left `2023-06-20T00:00:00Z`
+   * and broke the Low-resolution debug-string parity.
    */
   toDebugString(): string {
+    const dateStr = dateToDisplay(this._date);
     const components = [
       `key: ${bytesToHex(this._key)}`,
       `hash: ${bytesToHex(this._hash)}`,
       `chainID: ${bytesToHex(this._chainId)}`,
       `seq: ${this._seq}`,
-      `date: ${this._date.toISOString()}`,
+      `date: ${dateStr}`,
     ];
 
     const info = this.info();
     if (info !== undefined) {
-      components.push(`info: ${JSON.stringify(info)}`);
+      // Format info as the underlying string value, matching Rust Debug format
+      const textValue = info.asText();
+      if (textValue !== undefined) {
+        components.push(`info: "${textValue}"`);
+      } else {
+        // For non-text values, use diagnostic format
+        components.push(`info: ${info.toDiagnostic()}`);
+      }
     }
 
     return `ProvenanceMark(${components.join(", ")})`;
@@ -544,16 +826,20 @@ export class ProvenanceMark {
   }
 
   /**
-   * JSON serialization.
+   * JSON serialization. Field order, names, and date format mirror Rust's
+   * `#[derive(Serialize)]` on `ProvenanceMark` (provenance-mark-rust/src/mark.rs):
+   * `seq, date, res, chain_id, key, hash[, info_bytes]`. The date uses
+   * `dateToDisplay()` (date-only when midnight, RFC3339-seconds with `Z`
+   * otherwise), matching Rust's `serialize_iso8601` / `Date::to_string()`.
    */
   toJSON(): Record<string, unknown> {
     const result: Record<string, unknown> = {
+      seq: this._seq,
+      date: dateToDisplay(this._date),
       res: this._res,
+      chain_id: toBase64(this._chainId),
       key: toBase64(this._key),
       hash: toBase64(this._hash),
-      chainID: toBase64(this._chainId),
-      seq: this._seq,
-      date: this._date.toISOString(),
     };
     if (this._infoBytes.length > 0) {
       result["info_bytes"] = toBase64(this._infoBytes);
@@ -568,7 +854,8 @@ export class ProvenanceMark {
     const res = json["res"] as ProvenanceMarkResolution;
     const key = fromBase64(json["key"] as string);
     const hash = fromBase64(json["hash"] as string);
-    const chainId = fromBase64(json["chainID"] as string);
+    const chainIdRaw = json["chain_id"] ?? json["chainID"]; // accept legacy `chainID` for back-compat
+    const chainId = fromBase64(chainIdRaw as string);
     const seq = json["seq"] as number;
     const dateStr = json["date"] as string;
     const date = new Date(dateStr);
@@ -579,10 +866,77 @@ export class ProvenanceMark {
     let infoBytes: Uint8Array = new Uint8Array(0);
     if (typeof json["info_bytes"] === "string") {
       infoBytes = fromBase64(json["info_bytes"]);
+      // Mirrors Rust `util::deserialize_cbor` — base64-decoded bytes
+      // must parse as well-formed CBOR before we accept them. Earlier
+      // revisions of this port accepted any base64 payload, deferring
+      // the failure to a later `info()` call. Surface bad CBOR here
+      // so the JSON deserializer reports it eagerly.
+      if (infoBytes.length > 0) {
+        try {
+          decodeCbor(infoBytes);
+        } catch (e) {
+          throw new ProvenanceMarkError(
+            ProvenanceMarkErrorType.CborError,
+            "info_bytes is not valid CBOR",
+            {
+              details: e instanceof Error ? e.message : String(e),
+            },
+          );
+        }
+      }
     }
 
     return new ProvenanceMark(res, key, hash, chainId, seqBytes, dateBytes, infoBytes, seq, date);
   }
+
+  // ============================================================================
+  // Validation (delegate to ValidationReport)
+  // ============================================================================
+
+  /**
+   * Validate a collection of provenance marks.
+   *
+   * Matches Rust: `ProvenanceMark::validate()` which delegates to
+   * `ValidationReport::validate()`.
+   */
+  static validate(marks: ProvenanceMark[]): ValidationReport {
+    return validateMarks(marks);
+  }
+
+  // ============================================================================
+  // Envelope Support (EnvelopeEncodable)
+  // ============================================================================
+
+  /**
+   * Convert this provenance mark to a Gordian Envelope.
+   *
+   * Creates a leaf envelope containing the tagged CBOR representation.
+   * Matches Rust: `Envelope::new(mark.to_cbor())` which creates a CBOR leaf.
+   */
+  intoEnvelope(): Envelope {
+    return Envelope.newLeaf(this.taggedCbor());
+  }
+
+  /**
+   * Extract a ProvenanceMark from a Gordian Envelope.
+   *
+   * Matches Rust: `envelope.subject().try_leaf()?.try_into()`
+   *
+   * @param envelope - The envelope to extract from
+   * @returns The extracted provenance mark
+   * @throws ProvenanceMarkError if extraction fails
+   */
+  static fromEnvelope(envelope: Envelope): ProvenanceMark {
+    // Extract the CBOR leaf from the envelope subject, matching Rust's try_leaf()
+    const leaf = envelope.subject().asLeaf();
+    if (leaf !== undefined) {
+      return ProvenanceMark.fromTaggedCbor(leaf);
+    }
+
+    throw new ProvenanceMarkError(ProvenanceMarkErrorType.CborError, undefined, {
+      message: "Could not extract ProvenanceMark from envelope",
+    });
+  }
 }
 
 /**

package/src/resolution.ts

@@ -1,3 +1,9 @@
+/**
+ * Copyright © 2023-2026 Blockchain Commons, LLC
+ * Copyright © 2025-2026 Parity Technologies
+ *
+ */
+
 // Ported from provenance-mark-rust/src/resolution.rs
 
 import { type Cbor, cbor, expectUnsigned } from "@bcts/dcbor";
@@ -50,7 +56,7 @@ export enum ProvenanceMarkResolution {
  * Convert a resolution to its numeric value.
  */
 export function resolutionToNumber(res: ProvenanceMarkResolution): number {
-  return res as number;
+  return res;
 }
 
 /**
@@ -217,8 +223,21 @@ export function deserializeDate(res: ProvenanceMarkResolution, data: Uint8Array)
 
 /**
  * Serialize a sequence number into bytes based on the resolution.
+ *
+ * Mirrors Rust's typed `u32` parameter (`generator.rs::serialize_seq`)
+ * — the input must be a non-negative integer in `[0, 2^32-1]` (a u32).
+ * For Low resolution the upper bound additionally narrows to `2^16-1`
+ * (a u16) per Rust `if seq > 0xFFFF`. Earlier revisions of this port
+ * accepted any JS `number` for the 4-byte branch and would silently
+ * truncate values above `2^32-1`; now we raise `ResolutionError` so
+ * the wire output never deviates from Rust's u32 contract.
  */
 export function serializeSeq(res: ProvenanceMarkResolution, seq: number): Uint8Array {
+  if (!Number.isInteger(seq) || seq < 0) {
+    throw new ProvenanceMarkError(ProvenanceMarkErrorType.ResolutionError, undefined, {
+      details: `sequence number must be a non-negative integer, got ${seq}`,
+    });
+  }
   const len = seqBytesLength(res);
   if (len === 2) {
     if (seq > 0xffff) {
@@ -230,14 +249,18 @@ export function serializeSeq(res: ProvenanceMarkResolution, seq: number): Uint8A
     buf[0] = (seq >> 8) & 0xff;
     buf[1] = seq & 0xff;
     return buf;
-  } else {
-    const buf = new Uint8Array(4);
-    buf[0] = (seq >> 24) & 0xff;
-    buf[1] = (seq >> 16) & 0xff;
-    buf[2] = (seq >> 8) & 0xff;
-    buf[3] = seq & 0xff;
-    return buf;
   }
+  if (seq > 0xffffffff) {
+    throw new ProvenanceMarkError(ProvenanceMarkErrorType.ResolutionError, undefined, {
+      details: `sequence number ${seq} out of range for 4-byte format (max ${0xffffffff})`,
+    });
+  }
+  const buf = new Uint8Array(4);
+  buf[0] = (seq >>> 24) & 0xff;
+  buf[1] = (seq >>> 16) & 0xff;
+  buf[2] = (seq >>> 8) & 0xff;
+  buf[3] = seq & 0xff;
+  return buf;
 }
 
 /**
@@ -282,7 +305,7 @@ export function resolutionToString(res: ProvenanceMarkResolution): string {
  * Convert a resolution to CBOR.
  */
 export function resolutionToCbor(res: ProvenanceMarkResolution): Cbor {
-  return cbor(res as number);
+  return cbor(res);
 }
 
 /**

package/src/rng-state.ts

@@ -1,3 +1,9 @@
+/**
+ * Copyright © 2023-2026 Blockchain Commons, LLC
+ * Copyright © 2025-2026 Parity Technologies
+ *
+ */
+
 // Ported from provenance-mark-rust/src/rng_state.rs
 
 import { type Cbor, cbor, expectBytes } from "@bcts/dcbor";

package/src/seed.ts

@@ -1,3 +1,9 @@
+/**
+ * Copyright © 2023-2026 Blockchain Commons, LLC
+ * Copyright © 2025-2026 Parity Technologies
+ *
+ */
+
 // Ported from provenance-mark-rust/src/seed.rs
 
 import { type Cbor, cbor, expectBytes } from "@bcts/dcbor";