@bcts/provenance-mark 1.0.0-alpha.9 → 1.0.0-beta.1

package/dist/index.d.cts

@@ -1,7 +1,13 @@
 import { Cbor } from "@bcts/dcbor";
 import { BytewordsStyle, UR } from "@bcts/uniform-resources";
+import { Envelope, FormatContext, FormatContext as FormatContext$1 } from "@bcts/envelope";
 
 //#region src/error.d.ts
+/**
+ * Copyright © 2023-2026 Blockchain Commons, LLC
+ * Copyright © 2025-2026 Parity Technologies
+ *
+ */
 /**
  * Error types for Provenance Mark operations.
  */
@@ -52,6 +58,19 @@ declare enum ProvenanceMarkErrorType {
   IntegerConversionError = "IntegerConversionError",
   /** Validation error */
   ValidationError = "ValidationError",
+  /**
+   * Envelope serialization/deserialization error.
+   *
+   * Mirrors Rust `Error::Envelope(...)`
+   * (`provenance-mark-rust/src/error.rs`). The Rust enum surfaces
+   * envelope-format failures as their own variant; in earlier
+   * revisions of this port they collapsed into `CborError`. Both
+   * shapes are still emitted in practice (CBOR errors during envelope
+   * round-trip stay as `CborError`); this variant exists for the
+   * structural-level mismatches the Rust port tags as
+   * `Error::Envelope`.
+   */
+  EnvelopeError = "EnvelopeError"
 }
 /**
  * Error class for Provenance Mark operations.
@@ -76,7 +95,7 @@ declare enum ProvenanceMarkResolution {
   Low = 0,
   Medium = 1,
   Quartile = 2,
-  High = 3,
+  High = 3
 }
 /**
  * Convert a resolution to its numeric value.
@@ -151,6 +170,14 @@ declare function serializeDate(res: ProvenanceMarkResolution, date: Date): Uint8
 declare function deserializeDate(res: ProvenanceMarkResolution, data: Uint8Array): Date;
 /**
  * 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.
  */
 declare function serializeSeq(res: ProvenanceMarkResolution, seq: number): Uint8Array;
 /**
@@ -171,6 +198,11 @@ declare function resolutionToCbor(res: ProvenanceMarkResolution): Cbor;
 declare function resolutionFromCbor(cborValue: Cbor): ProvenanceMarkResolution;
 //#endregion
 //#region src/date.d.ts
+/**
+ * Copyright © 2023-2026 Blockchain Commons, LLC
+ * Copyright © 2025-2026 Parity Technologies
+ *
+ */
 /**
  * Interface for serializable date operations.
  */
@@ -224,8 +256,116 @@ declare function dateFromIso8601(str: string): Date;
  * Format a date as a simple date string (YYYY-MM-DD).
  */
 declare function dateToDateString(date: Date): string;
+/**
+ * Renders a `Date` the way Rust's `dcbor::Date::Display` does
+ * (`bc-dcbor-rust/src/date.rs:485-492`):
+ *
+ * - When the UTC time is exactly `00:00:00` (subsecond precision is
+ *   ignored — Rust's check is `hour == 0 && minute == 0 && second == 0`,
+ *   matching `chrono::SecondsFormat::Secs`), emit just `YYYY-MM-DD`.
+ * - Otherwise emit RFC 3339 with second precision (no fractional
+ *   seconds), e.g. `2023-02-08T15:30:45Z`.
+ *
+ * This is the canonical "Rust string" for dates across the
+ * provenance-mark public surface — `mark.toDebugString`,
+ * `mark.precedesOpt` `DateOrdering` issue, `markdownSummary`, and the
+ * validation report's `DateOrdering` payload all use it. Centralising
+ * here keeps every call site in lockstep with the Rust output.
+ *
+ * @example
+ * ```typescript
+ * dateToDisplay(new Date("2023-06-20T00:00:00Z"));   // "2023-06-20"
+ * dateToDisplay(new Date("2023-06-20T15:30:45Z"));   // "2023-06-20T15:30:45Z"
+ * dateToDisplay(new Date("2023-06-20T15:30:45.123Z")); // "2023-06-20T15:30:45Z"
+ * ```
+ */
+declare function dateToDisplay(date: Date): string;
+//#endregion
+//#region src/seed.d.ts
+declare const PROVENANCE_SEED_LENGTH = 32;
+/**
+ * A seed for generating provenance marks.
+ */
+declare class ProvenanceSeed {
+  private readonly data;
+  private constructor();
+  /**
+   * Create a new random seed using secure random number generation.
+   */
+  static new(): ProvenanceSeed;
+  /**
+   * Create a new seed using custom random data.
+   */
+  static newUsing(randomData: Uint8Array): ProvenanceSeed;
+  /**
+   * Create a new seed from a passphrase.
+   */
+  static newWithPassphrase(passphrase: string): ProvenanceSeed;
+  /**
+   * Get the raw bytes.
+   */
+  toBytes(): Uint8Array;
+  /**
+   * Create from a 32-byte array.
+   */
+  static fromBytes(bytes: Uint8Array): ProvenanceSeed;
+  /**
+   * Create from a slice (validates length).
+   */
+  static fromSlice(bytes: Uint8Array): ProvenanceSeed;
+  /**
+   * Get the hex representation.
+   */
+  hex(): string;
+  /**
+   * Convert to CBOR (byte string).
+   */
+  toCbor(): Cbor;
+  /**
+   * Create from CBOR (byte string).
+   */
+  static fromCbor(cborValue: Cbor): ProvenanceSeed;
+}
+//#endregion
+//#region src/utils.d.ts
+/**
+ * Parse a base64-encoded provenance seed.
+ *
+ * Mirrors Rust's `parse_seed` user helper
+ * (`provenance-mark-rust/src/util.rs:34-38`), which round-trips the
+ * input through serde JSON / `deserialize_block` and so requires the
+ * decoded bytes to be exactly {@link PROVENANCE_SEED_LENGTH} (32) long.
+ * The TS equivalent decodes the base64 directly and delegates to
+ * {@link ProvenanceSeed.fromBytes} for the length check.
+ *
+ * @param s - Base64-encoded 32-byte seed string.
+ * @returns The decoded {@link ProvenanceSeed}.
+ * @throws {ProvenanceMarkError} If the input is not valid base64 or the
+ *   decoded length is not exactly 32 bytes.
+ */
+declare function parseSeed(s: string): ProvenanceSeed;
+/**
+ * Parse a date string (`YYYY-MM-DD` or full RFC 3339) into a `Date`.
+ *
+ * Mirrors Rust's `parse_date` user helper
+ * (`provenance-mark-rust/src/util.rs:40-42`), which delegates to
+ * `Date::from_string` (the same parser the JSON deserializer uses).
+ * Accepts the same shapes the Rust parser does:
+ *
+ * - `YYYY-MM-DD` (interpreted as UTC midnight, matching JS spec).
+ * - Full RFC 3339, e.g. `2023-06-20T15:30:45Z` or
+ *   `2023-06-20T15:30:45.123Z`.
+ *
+ * @throws {ProvenanceMarkError} If the input fails to parse.
+ */
+declare function parseDate(s: string): Date;
 //#endregion
 //#region src/crypto-utils.d.ts
+/**
+ * Copyright © 2023-2026 Blockchain Commons, LLC
+ * Copyright © 2025-2026 Parity Technologies
+ *
+ */
 declare const SHA256_SIZE = 32;
 /**
  * Compute SHA-256 hash of data.
@@ -250,6 +390,11 @@ declare function hkdfHmacSha256(keyMaterial: Uint8Array, salt: Uint8Array, keyLe
 declare function obfuscate(key: Uint8Array, message: Uint8Array): Uint8Array;
 //#endregion
 //#region src/xoshiro256starstar.d.ts
+/**
+ * Copyright © 2023-2026 Blockchain Commons, LLC
+ * Copyright © 2025-2026 Parity Technologies
+ *
+ */
 /**
  * Xoshiro256** PRNG implementation.
  * A fast, high-quality pseudorandom number generator.
@@ -341,51 +486,91 @@ declare class RngState {
   static fromCbor(cborValue: Cbor): RngState;
 }
 //#endregion
-//#region src/seed.d.ts
-declare const PROVENANCE_SEED_LENGTH = 32;
+//#region src/validate.d.ts
 /**
- * A seed for generating provenance marks.
+ * Format for validation report output.
  */
-declare class ProvenanceSeed {
-  private readonly data;
-  private constructor();
-  /**
-   * Create a new random seed using secure random number generation.
-   */
-  static new(): ProvenanceSeed;
-  /**
-   * Create a new seed using custom random data.
-   */
-  static newUsing(randomData: Uint8Array): ProvenanceSeed;
-  /**
-   * Create a new seed from a passphrase.
-   */
-  static newWithPassphrase(passphrase: string): ProvenanceSeed;
-  /**
-   * Get the raw bytes.
-   */
-  toBytes(): Uint8Array;
-  /**
-   * Create from a 32-byte array.
-   */
-  static fromBytes(bytes: Uint8Array): ProvenanceSeed;
-  /**
-   * Create from a slice (validates length).
-   */
-  static fromSlice(bytes: Uint8Array): ProvenanceSeed;
-  /**
-   * Get the hex representation.
-   */
-  hex(): string;
-  /**
-   * Convert to CBOR (byte string).
-   */
-  toCbor(): Cbor;
-  /**
-   * Create from CBOR (byte string).
-   */
-  static fromCbor(cborValue: Cbor): ProvenanceSeed;
+declare enum ValidationReportFormat {
+  /** Human-readable text format */
+  Text = "text",
+  /** Compact JSON format (no whitespace) */
+  JsonCompact = "json-compact",
+  /** Pretty-printed JSON format (with indentation) */
+  JsonPretty = "json-pretty"
 }
+/**
+ * Issue flagged during validation.
+ */
+type ValidationIssue = {
+  type: "HashMismatch";
+  expected: string;
+  actual: string;
+} | {
+  type: "KeyMismatch";
+} | {
+  type: "SequenceGap";
+  expected: number;
+  actual: number;
+} | {
+  type: "DateOrdering";
+  previous: string;
+  next: string;
+} | {
+  type: "NonGenesisAtZero";
+} | {
+  type: "InvalidGenesisKey";
+};
+/**
+ * Format a validation issue as a string.
+ */
+declare function formatValidationIssue(issue: ValidationIssue): string;
+/**
+ * A mark with any issues flagged during validation.
+ */
+interface FlaggedMark {
+  mark: ProvenanceMark;
+  issues: ValidationIssue[];
+}
+/**
+ * Report for a contiguous sequence of marks within a chain.
+ */
+interface SequenceReport {
+  startSeq: number;
+  endSeq: number;
+  marks: FlaggedMark[];
+}
+/**
+ * Report for a chain of marks with the same chain ID.
+ */
+interface ChainReport {
+  chainId: Uint8Array;
+  hasGenesis: boolean;
+  marks: ProvenanceMark[];
+  sequences: SequenceReport[];
+}
+/**
+ * Get the chain ID as a hex string for display.
+ */
+declare function chainIdHex(report: ChainReport): string;
+/**
+ * Complete validation report.
+ */
+interface ValidationReport {
+  marks: ProvenanceMark[];
+  chains: ChainReport[];
+}
+/**
+ * Check if the validation report has any issues.
+ */
+declare function hasIssues(report: ValidationReport): boolean;
+/**
+ * Format the validation report.
+ */
+declare function formatReport(report: ValidationReport, format: ValidationReportFormat): string;
+/**
+ * Validate a collection of provenance marks.
+ */
+declare function validate(marks: ProvenanceMark[]): ValidationReport;
 //#endregion
 //#region src/mark.d.ts
 /**
@@ -428,23 +613,106 @@ declare class ProvenanceMark {
   static fromMessage(res: ProvenanceMarkResolution, message: Uint8Array): ProvenanceMark;
   private static makeHash;
   /**
-   * 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;
+  /**
+   * The full 32-byte Mark ID as a 64-character hex string.
+   */
+  idHex(): string;
+  /**
+   * 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;
+  /**
+   * 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;
+  /**
+   * 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;
+  /**
+   * 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;
   /**
-   * 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;
   /**
-   * Get the first four bytes of the hash as Bytemoji.
+   * 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;
+  /**
+   * 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;
+  /**
+   * 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;
+  private static resolveCollisionGroup;
+  /**
+   * 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[];
+  /**
+   * 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[];
   /**
    * Check if this mark precedes another mark in the chain.
    */
   precedes(next: ProvenanceMark): boolean;
   /**
    * 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;
   /**
@@ -468,13 +736,31 @@ declare class ProvenanceMark {
    */
   static fromBytewords(res: ProvenanceMarkResolution, bytewords: string): ProvenanceMark;
   /**
-   * Encode for URL (minimal bytewords of CBOR).
+   * Encode for URL (minimal bytewords of tagged CBOR).
    */
   toUrlEncoding(): string;
   /**
    * Decode from URL encoding.
    */
   static fromUrlEncoding(urlEncoding: string): ProvenanceMark;
+  /**
+   * 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;
+  /**
+   * Get the UR string representation (e.g., "ur:provenance/...").
+   */
+  urString(): string;
+  /**
+   * Create from a UR string.
+   */
+  static fromURString(urString: string): ProvenanceMark;
   /**
    * Build a URL with this mark as a query parameter.
    */
@@ -513,10 +799,24 @@ declare class ProvenanceMark {
   fingerprint(): Uint8Array;
   /**
    * 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;
   /**
    * 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;
   /**
@@ -524,13 +824,41 @@ declare class ProvenanceMark {
    */
   equals(other: ProvenanceMark): boolean;
   /**
-   * 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>;
   /**
    * Create from JSON object.
    */
   static fromJSON(json: Record<string, unknown>): ProvenanceMark;
+  /**
+   * Validate a collection of provenance marks.
+   *
+   * Matches Rust: `ProvenanceMark::validate()` which delegates to
+   * `ValidationReport::validate()`.
+   */
+  static validate(marks: ProvenanceMark[]): ValidationReport;
+  /**
+   * 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;
+  /**
+   * 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;
 }
 //#endregion
 //#region src/generator.d.ts
@@ -575,6 +903,20 @@ declare class ProvenanceMarkGenerator {
   next(date: Date, info?: Cbor): ProvenanceMark;
   /**
    * String representation.
+   *
+   * Mirrors Rust `Display for ProvenanceMarkGenerator`
+   * (`provenance-mark-rust/src/generator.rs:135-147`):
+   *
+   * ```rust
+   * write!(f, "ProvenanceMarkGenerator(chainID: {}, res: {}, seed: {}, nextSeq: {}, rngState: {:?})",
+   *     hex::encode(&self.chain_id), self.res, self.seed.hex(), self.next_seq, self.rng_state)
+   * ```
+   *
+   * The `rngState` field uses Rust's `{:?}` (Debug) format, which on a
+   * `RngState([u8; 32])` tuple struct produces `RngState([n0, n1, ...])`
+   * with each byte rendered as a decimal integer. Earlier revisions of
+   * this port omitted `rngState` entirely from `toString()`, so the
+   * output diverged from Rust's `Display`.
    */
   toString(): string;
   /**
@@ -585,94 +927,29 @@ declare class ProvenanceMarkGenerator {
    * Create from JSON object.
    */
   static fromJSON(json: Record<string, unknown>): ProvenanceMarkGenerator;
+  /**
+   * Convert this generator to a Gordian Envelope.
+   *
+   * The envelope contains structured assertions for all generator fields:
+   * - isA: "provenance-generator"
+   * - res: The resolution
+   * - seed: The seed
+   * - next-seq: The next sequence number
+   * - rng-state: The RNG state
+   *
+   * Note: Use provenanceMarkGeneratorToEnvelope() for a standalone function alternative.
+   */
+  intoEnvelope(): Envelope;
+  /**
+   * Extract a ProvenanceMarkGenerator from a Gordian Envelope.
+   *
+   * @param envelope - The envelope to extract from
+   * @returns The extracted generator
+   * @throws ProvenanceMarkError if extraction fails
+   */
+  static fromEnvelope(envelope: Envelope): ProvenanceMarkGenerator;
 }
 //#endregion
-//#region src/validate.d.ts
-/**
- * Format for validation report output.
- */
-declare enum ValidationReportFormat {
-  /** Human-readable text format */
-  Text = "text",
-  /** Compact JSON format (no whitespace) */
-  JsonCompact = "json-compact",
-  /** Pretty-printed JSON format (with indentation) */
-  JsonPretty = "json-pretty",
-}
-/**
- * Issue flagged during validation.
- */
-type ValidationIssue = {
-  type: "HashMismatch";
-  expected: string;
-  actual: string;
-} | {
-  type: "KeyMismatch";
-} | {
-  type: "SequenceGap";
-  expected: number;
-  actual: number;
-} | {
-  type: "DateOrdering";
-  previous: string;
-  next: string;
-} | {
-  type: "NonGenesisAtZero";
-} | {
-  type: "InvalidGenesisKey";
-};
-/**
- * Format a validation issue as a string.
- */
-declare function formatValidationIssue(issue: ValidationIssue): string;
-/**
- * A mark with any issues flagged during validation.
- */
-interface FlaggedMark {
-  mark: ProvenanceMark;
-  issues: ValidationIssue[];
-}
-/**
- * Report for a contiguous sequence of marks within a chain.
- */
-interface SequenceReport {
-  startSeq: number;
-  endSeq: number;
-  marks: FlaggedMark[];
-}
-/**
- * Report for a chain of marks with the same chain ID.
- */
-interface ChainReport {
-  chainId: Uint8Array;
-  hasGenesis: boolean;
-  marks: ProvenanceMark[];
-  sequences: SequenceReport[];
-}
-/**
- * Get the chain ID as a hex string for display.
- */
-declare function chainIdHex(report: ChainReport): string;
-/**
- * Complete validation report.
- */
-interface ValidationReport {
-  marks: ProvenanceMark[];
-  chains: ChainReport[];
-}
-/**
- * Check if the validation report has any issues.
- */
-declare function hasIssues(report: ValidationReport): boolean;
-/**
- * Format the validation report.
- */
-declare function formatReport(report: ValidationReport, format: ValidationReportFormat): string;
-/**
- * Validate a collection of provenance marks.
- */
-declare function validate(marks: ProvenanceMark[]): ValidationReport;
-//#endregion
 //#region src/mark-info.d.ts
 /**
  * Wrapper for a provenance mark with additional display information.
@@ -686,6 +963,16 @@ declare class ProvenanceMarkInfo {
   private constructor();
   /**
    * Create a new ProvenanceMarkInfo from a mark.
+   *
+   * Mirrors Rust `ProvenanceMarkInfo::new`
+   * (`provenance-mark-rust/src/mark_info.rs`), which calls
+   * `mark.ur()` — i.e. the `UREncodable` implementation, whose
+   * payload is the **untagged** CBOR with type `"provenance"`. Earlier
+   * revisions of this port called `decodeCbor(mark.toCborData())` and
+   * wrapped the resulting *tagged* CBOR in `UR.new("provenance", ...)`,
+   * which prepended the CBOR tag to the UR bytewords and broke
+   * cross-impl interop (UR strings produced by Rust would not parse,
+   * and vice versa).
    */
   static new(mark: ProvenanceMark, comment?: string): ProvenanceMarkInfo;
   mark(): ProvenanceMark;
@@ -695,17 +982,83 @@ declare class ProvenanceMarkInfo {
   comment(): string;
   /**
    * Generate a markdown summary of the mark.
+   *
+   * Date rendering uses {@link dateToDisplay} so midnight-UTC dates
+   * appear as `YYYY-MM-DD` (matching Rust `format!("{}",
+   * self.mark.date())`), not as `YYYY-MM-DDT00:00:00Z`.
    */
   markdownSummary(): string;
   /**
-   * JSON serialization.
+   * JSON serialization. Field order mirrors Rust's `#[derive(Serialize)]`
+   * on `ProvenanceMarkInfo` (provenance-mark-rust/src/mark_info.rs):
+   * `ur, bytewords, bytemoji, [comment,] mark` — `comment` (when present)
+   * comes BEFORE `mark`. Rust uses `skip_serializing_if = "String::is_empty"`,
+   * matched here by the `if (...length > 0)` guard.
    */
   toJSON(): Record<string, unknown>;
   /**
    * Create from JSON object.
+   *
+   * Decodes the UR string through {@link ProvenanceMark.fromURString},
+   * which correctly handles the **untagged** CBOR payload that
+   * `mark.ur()` produces — symmetric with the constructor.
    */
   static fromJSON(json: Record<string, unknown>): ProvenanceMarkInfo;
 }
 //#endregion
-export { type ChainReport, type FlaggedMark, PROVENANCE_SEED_LENGTH, ProvenanceMark, ProvenanceMarkError, ProvenanceMarkErrorType, ProvenanceMarkGenerator, ProvenanceMarkInfo, ProvenanceMarkResolution, type ProvenanceMarkResult, ProvenanceSeed, RNG_STATE_LENGTH, RngState, SHA256_SIZE, type SequenceReport, type SerializableDate, type ValidationIssue, type ValidationReport, ValidationReportFormat, Xoshiro256StarStar, chainIdHex, chainIdRange, dateBytesLength, dateBytesRange, dateFromIso8601, dateToDateString, dateToIso8601, deserialize2Bytes, deserialize4Bytes, deserialize6Bytes, deserializeDate, deserializeSeq, extendKey, fixedLength, formatReport, formatValidationIssue, hasIssues, hashRange, hkdfHmacSha256, infoRangeStart, keyRange, linkLength, obfuscate, rangeOfDaysInMonth, resolutionFromCbor, resolutionFromNumber, resolutionToCbor, resolutionToNumber, resolutionToString, seqBytesLength, seqBytesRange, serialize2Bytes, serialize4Bytes, serialize6Bytes, serializeDate, serializeSeq, sha256, sha256Prefix, validate };
+//#region src/envelope.d.ts
+/**
+ * Registers provenance mark tags in the global format context.
+ *
+ * Matches Rust: register_tags()
+ */
+declare function registerTags(): void;
+/**
+ * Registers provenance mark tags in a specific format context.
+ *
+ * Matches Rust: register_tags_in()
+ *
+ * @param context - The format context to register tags in
+ */
+declare function registerTagsIn(context: FormatContext$1): void;
+/**
+ * Convert a ProvenanceMark to an Envelope.
+ *
+ * Delegates to ProvenanceMark.intoEnvelope() — single source of truth.
+ *
+ * @param mark - The provenance mark to convert
+ * @returns An envelope containing the mark
+ */
+declare function provenanceMarkToEnvelope(mark: ProvenanceMark): Envelope;
+/**
+ * Extract a ProvenanceMark from an Envelope.
+ *
+ * Delegates to ProvenanceMark.fromEnvelope() — single source of truth.
+ *
+ * @param envelope - The envelope to extract from
+ * @returns The extracted provenance mark
+ * @throws ProvenanceMarkError if extraction fails
+ */
+declare function provenanceMarkFromEnvelope(envelope: Envelope): ProvenanceMark;
+/**
+ * Convert a ProvenanceMarkGenerator to an Envelope.
+ *
+ * Delegates to ProvenanceMarkGenerator.intoEnvelope() — single source of truth.
+ *
+ * @param generator - The generator to convert
+ * @returns An envelope containing the generator
+ */
+declare function provenanceMarkGeneratorToEnvelope(generator: ProvenanceMarkGenerator): Envelope;
+/**
+ * Extract a ProvenanceMarkGenerator from an Envelope.
+ *
+ * Delegates to ProvenanceMarkGenerator.fromEnvelope() — single source of truth.
+ *
+ * @param envelope - The envelope to extract from
+ * @returns The extracted generator
+ * @throws ProvenanceMarkError if extraction fails
+ */
+declare function provenanceMarkGeneratorFromEnvelope(envelope: Envelope): ProvenanceMarkGenerator;
+//#endregion
+export { type ChainReport, type FlaggedMark, FormatContext, PROVENANCE_SEED_LENGTH, ProvenanceMark, ProvenanceMarkError, ProvenanceMarkErrorType, ProvenanceMarkGenerator, ProvenanceMarkInfo, ProvenanceMarkResolution, type ProvenanceMarkResult, ProvenanceSeed, RNG_STATE_LENGTH, RngState, SHA256_SIZE, type SequenceReport, type SerializableDate, type ValidationIssue, type ValidationReport, ValidationReportFormat, Xoshiro256StarStar, chainIdHex, chainIdRange, dateBytesLength, dateBytesRange, dateFromIso8601, dateToDateString, dateToDisplay, dateToIso8601, deserialize2Bytes, deserialize4Bytes, deserialize6Bytes, deserializeDate, deserializeSeq, extendKey, fixedLength, formatReport, formatValidationIssue, hasIssues, hashRange, hkdfHmacSha256, infoRangeStart, keyRange, linkLength, obfuscate, parseDate, parseSeed, provenanceMarkFromEnvelope, provenanceMarkGeneratorFromEnvelope, provenanceMarkGeneratorToEnvelope, provenanceMarkToEnvelope, rangeOfDaysInMonth, registerTags, registerTagsIn, resolutionFromCbor, resolutionFromNumber, resolutionToCbor, resolutionToNumber, resolutionToString, seqBytesLength, seqBytesRange, serialize2Bytes, serialize4Bytes, serialize6Bytes, serializeDate, serializeSeq, sha256, sha256Prefix, validate };
 //# sourceMappingURL=index.d.cts.map