urna validate

urna validate checks the integrity of a .urna file and prints its file_hash and content_hash. It stops at the first failure with a typed error. It needs no Python and no embedder.

UsageCopy Anchor Link

urna validate <FILE>

ArgumentsCopy Anchor Link

OptionsCopy Anchor Link

BehaviorCopy Anchor Link

validate reads the whole file into memory and runs, in order:

1. The reader's parse and integrity check: file length, magic (URNA, or the legacy NEST), version 1.0, header checksum, file size, and for every section a legal encoding, 64-byte alignment, bounds and payload checksum; then the manifest parse and validation, the footer hash, header and manifest agreement, the six required sections, the embeddings size for the declared dtype, the size of every named space band, and the search_contract against the manifest. The full list is in what the reader checks on open.
2. A walk over the embeddings section for NaN and Inf.
3. A decode of the search_contract section.
4. When the file has inlined media (blob_data, 0x17): a SHA-256 of every inlined blob, compared with the hash recorded for it in blob_refs (0x14).

The checks it does not run:

• It does not decode the hnsw_index, bm25_index or graph_adjacency payloads, or the blob span overlay. Their checksums are verified, their contents are not.
• It does not check named space bands for NaN or Inf.

A file with a well-formed checksum over a malformed index payload therefore passes validate and fails when a search opens it. To run the full open as well, follow validate with a command that opens the file for search, such as urna inspect --json.

The checksums are unkeyed. A passing validate proves the file is consistent with itself, not who built it. See Security.

OutputCopy Anchor Link

On success, to stdout:

OK: <file> is a valid .urna v1 file
  Header checksum:    valid
  Section checksums:  <n> sections OK
  Footer hash:        valid
  Manifest:           valid (contract enforced)
  Required sections:  all present
  Embedding values:   no NaN/Inf
  Inlined blobs:      <n> verified against blob_refs
  File hash:          sha256:<64 hex>
  Content hash:       sha256:<64 hex>

The Inlined blobs line appears only when the file has a blob_data section. File hash is the SHA-256 of the whole file, the same value sha256sum prints. Content hash is the first half of every citation into the file (see Citations and hashes).

On failure, the first error goes to stderr as Error: <message>. For every check except the inlined-blob proof, nothing reaches stdout. The blob proof runs after the OK: line and the lines up to Embedding values are printed, so a blob failure leaves those lines on stdout: in scripts, test the exit code, not the OK: line. Section ids in these messages are decimal: section 2 is chunks_canonical (0x02).

The complete list is in Typed errors.

Exit codesCopy Anchor Link

ExamplesCopy Anchor Link

Validate the quickstart corpus:

urna validate examples/quickstart/out/quickstart.urna

OK: examples/quickstart/out/quickstart.urna is a valid .urna v1 file
  Header checksum:    valid
  Section checksums:  9 sections OK
  Footer hash:        valid
  Manifest:           valid (contract enforced)
  Required sections:  all present
  Embedding values:   no NaN/Inf
  File hash:          sha256:e4d5f8907faad38c192dc6929e36dbf16db558410b2dae5abb4d65f10f508832
  Content hash:       sha256:1147b2560863331b21bd9d60fe6bdd99507dc34e17108444dc38194f8e6f09df

A copy with one bit flipped inside chunks_canonical:

Error: section 2 checksum mismatch

A copy with one bit flipped inside the manifest, which only the footer hash covers:

Error: footer hash mismatch

Use it in a script:

urna validate corpus.urna > /dev/null && echo "corpus ok"