LATCH Finding Package Format (.latch)

1. Status

LATCH Finding Package Format, specification version 2.0 (draft).

Version 2.0 is the published target format. In the current LATCH release, files with the .latch extension are a different, legacy document bundle (see Section 13). That legacy bundle is not this format.

2. Purpose

A .latch file is a finding package. It records the result of one search or question run against a document collection:

A finding package does not contain the source documents. It refers to them by SHA-256 digest. A recipient who holds the same documents (for example in a .latchdoc package, or their own copy of a production) can check every quote independently.

The companion format for carrying documents is the .latchdoc document package, specified at /docs/formats/latchdoc. Both formats share the same envelope (Sections 4 to 7).

3. Identification

Item Value
Media type application/vnd.codynamicslab.latch
File extension .latch
Magic number 4C 41 54 43 48 32 00 00 ("LATCH2" followed by two null bytes) at offset 0
Package type (header field) "latch"
macOS UTI com.codynamicslab.latch

.latch and .latchdoc files share a magic number. Readers tell them apart by the package_type field in the cleartext header.

4. File layout

All integers are little-endian.

Offset Size Field
0 8 bytes Magic number
8 4 bytes header_len (unsigned 32-bit)
12 header_len bytes Header, UTF-8 JSON
next 16 bytes Salt
next 12 bytes Nonce
next variable Ciphertext
last 16 bytes AES-256-GCM authentication tag

The GCM associated data is magic || header_len || header bytes, so the cleartext header is authenticated together with the ciphertext.

5. Header

The header is a JSON object.

Field Description
package_type "latch"
spec_version "2.0"
package_id Lowercase hex SHA-256 of the plaintext (the zstd-compressed tar, before encryption)
created_at RFC 3339 UTC timestamp
created_by_device Ed25519 public key id of the device that created the package
kdf {"alg": "argon2id", "m": <KiB>, "t": <iterations>, "p": <parallelism>}, or {"alg": "none", "key_id": "<id>"} when a raw organization key is used
signature Base64 Ed25519 signature (Section 7)

The header never contains document content, quotes, or query text. Readers must ignore unknown header fields. Readers must reject a package whose spec_version has an unknown major version.

6. Key derivation

When kdf.alg is argon2id, the 32-byte AES key is derived with Argon2id from the passphrase and the 16-byte salt, using the parameters in the header. Recommended minimums: m = 65536 (64 MiB), t = 3, p = 1.

When kdf.alg is none, the key is a 32-byte organization key identified by key_id and shared out of band.

The key must never default to a license token or any other value the user did not choose.

7. Signature

The signature is Ed25519 over the RFC 8785 (JCS) canonical JSON of the header with the signature field removed. Because package_id is part of the signed header, the signature also covers the full archive contents.

8. Plaintext archive

The plaintext is a POSIX tar archive (pax format) compressed with Zstandard (RFC 8878).

Member Required Contents
manifest.json Yes Every member: path, size, full-file SHA-256, role
finding.json Yes The query, scope, matching rules, and corpus state
hits.json Yes Every location found
claims.json Yes The answer as claims, each with its quote and verification result
sources.json Yes The source documents referenced, by digest
model.json Yes Model and software identity, decode settings
answer.md Yes The answer text exactly as it was displayed
audit/entry.json Yes The audit log entry for this query
audit/chain.json No Chain proof: previous entry hash and daily signature

A .latch archive must not contain source/ or text/ members. Those belong in .latchdoc packages.

8.1 manifest.json

{
  "spec_version": "2.0",
  "package_type": "latch",
  "members": [
    { "path": "finding.json", "size": 1843, "sha256": "9c1e...", "role": "finding" },
    { "path": "hits.json",    "size": 52210, "sha256": "41aa...", "role": "hits" },
    { "path": "claims.json",  "size": 6120, "sha256": "e07b...", "role": "claims" }
  ]
}

8.2 finding.json

{
  "finding_id": "f_01JC4X7Q2Z",
  "created_at": "2026-11-10T18:22:04Z",
  "query": {
    "text": "Every mention of John A. Smith in the Henderson production",
    "parsed": { "entities": ["John A. Smith"], "scope": "matter:henderson-2026" }
  },
  "matching_rules": {
    "lane": "exhaustive",
    "name_variants": true,
    "phonetic": "double-metaphone",
    "max_edit_distance": 1,
    "rules_version": "1.0"
  },
  "corpus": {
    "manifest_sha256": "77d2...",
    "index_snapshot_id": "snap_2026-11-10T17:00Z",
    "document_count": 48210
  }
}

8.3 hits.json

Every location the search returned. lane is exhaustive (deterministic matching rules) or suggestion (semantic search). Suggestion hits are never part of an "all mentions" result.

{
  "hit_count": 2,
  "hits": [
    { "text_sha256": "4f1c...", "start": 18234, "end": 18247, "lane": "exhaustive", "rule": "exact" },
    { "text_sha256": "a90d...", "start": 912,   "end": 924,   "lane": "exhaustive", "rule": "name_variant" }
  ]
}

8.4 claims.json

Each claim in the answer carries a verbatim quote and the exact location of that quote.

{
  "normalization": "latch-quote-1",
  "claims": [
    {
      "claim_id": "c1",
      "text": "The lease term was extended to 2031.",
      "quote": "the Term is hereby extended through December 31, 2031",
      "text_sha256": "4f1c...",
      "start": 18234,
      "end": 18287,
      "verification": { "status": "pass", "offsets_corrected": false }
    }
  ],
  "failed_claim_count": 0,
  "unsupported_notes": ["No amendment after 2024 was found in the hit set."]
}

status is pass or fail. Claims that failed verification may be included with status: "fail" for the record, but must be shown to a reader as unverified.

8.5 sources.json

{
  "sources": [
    {
      "text_sha256": "4f1c...",
      "original_sha256": "c3b8...",
      "extractor": "docling 2.x",
      "original_name": "Henderson_Lease_Amendment_3.pdf"
    }
  ]
}

original_name is optional. Creators should leave it out when file names themselves are confidential.

8.6 model.json

{
  "model_name": "Qwen2.5-14B-Instruct",
  "weights_sha256": "b51f...",
  "server": "vllm",
  "container_image_digest": "sha256:0e9a...",
  "prompt_template_sha256": "1d3c...",
  "decode": { "temperature": 0, "do_sample": false, "batch_size": 1 }
}

9. Offsets and quote normalization

Offsets (start, end) are Unicode code point positions in the extracted text identified by text_sha256, not in the original file. The .latchdoc package for the same documents contains that extracted text under text/<sha256>.txt, along with a map from text offsets to page numbers and page coordinates.

Quote verification uses normalization latch-quote-1, applied to both the quote and the source span before comparison:

  1. Unicode NFC normalization.
  2. Remove a hyphen immediately followed by a line break (-\n or -\r\n), joining the word.
  3. Replace every run of whitespace (spaces, tabs, line breaks) with a single space.
  4. Trim leading and trailing whitespace.

A claim passes when the normalized quote equals the normalized text at [start, end). If the offsets are wrong but the normalized quote occurs exactly once in that text, a creator may correct the offsets and set offsets_corrected: true. Otherwise the claim fails.

10. Recipient verification

To verify a .latch file:

  1. Check the magic number and that header_len is within a sane limit (recommended maximum 64 KiB).
  2. Parse the header and confirm package_type is "latch".
  3. Derive the key, decrypt, and verify the GCM tag.
  4. Verify the Ed25519 signature against the creating device's public key.
  5. Check that the SHA-256 of the decrypted plaintext equals package_id.
  6. Decompress with limits on total size and member count, and apply the path safety rules in Section 12.
  7. Check that every member is listed in manifest.json and that its SHA-256 matches.
  8. For each claim, find the extracted text whose SHA-256 equals text_sha256 in your own copy of the documents, and confirm the quote using Section 9.

Steps 1 to 7 prove the package is intact and came from the stated device. Step 8 proves each quote is real and correctly located, without trusting the creator.

11. Relationship to .latchdoc

.latchdoc .latch
Carries source documents Yes No
Carries extracted text Yes No
Carries verbatim quotes No Yes, short quotes only
Typical size Large Small
Typical use Archive or transfer a document set Send a finding to a partner, co-counsel, expert, or referring physician

A recipient who has a matching .latchdoc can verify every claim in a .latch fully offline.

12. Security considerations

  1. Active content. The format contains no executable or active content. It holds JSON records and plain text. Readers must not execute or automatically render anything inside a package. Quoted text and answer text may contain instructions aimed at AI models that later read them, so systems that pass package text to a language model should treat it as untrusted data, not as instructions.

  2. Privacy and integrity. Packages do not contain source documents, but they do contain short verbatim quotes, query text, and optionally file names, any of which can be confidential (for example legal or medical information). They need both privacy and integrity protection.

  3. Services provided by the format. The archive is encrypted with AES-256-GCM. The key is derived from a passphrase or organization key using Argon2id. The GCM tag authenticates the ciphertext and the cleartext header. Each package is signed with Ed25519 by the device that created it. The manifest lists a SHA-256 digest for every member, and readers must check the tag, the signature, and every digest before using any content. The cleartext header holds only format metadata, never quotes, queries, or document content. Anyone with the passphrase or key can read the contents, so keys must be protected and shared separately from the file.

  4. Use of existing formats. The header and the archive members are JSON, and the security considerations of RFC 8259, Section 12 apply. Readers should limit header and member sizes, reject duplicate keys and malformed input, and treat all fields as untrusted until the signature and GCM tag have been verified. The format does not use JSON extensibility to carry executable content. Unknown fields must be ignored, not interpreted.

    4a. Compression. The archive is compressed with Zstandard, and the security considerations of RFC 8878, Section 7 apply. Readers should enforce limits on decompressed size and member count to protect against decompression bombs, and should check sizes listed in the manifest before extracting.

    4b. Container format. The decrypted payload is a tar archive. Readers must reject absolute paths, .. path segments, symbolic links, hard links, and device files, so that extraction cannot write outside the target directory or overwrite existing files. Readers must reject any member not listed in the signed manifest, and any member whose SHA-256 digest does not match the manifest.

  5. Links. The format does not include links that must be fetched to interpret it. Source documents are referenced by SHA-256 digest, not by URL, and the recipient verifies quotes against their own copy of those documents. Readers must not fetch remote resources while processing a package.

Additional note. A verified quote proves the quoted text exists at the stated location. It does not prove that the claim's interpretation of that text is correct. Readers should review each claim against its source.

13. Legacy version 1 files

The current LATCH release writes files with the .latch extension using the version 1 layout:

Version 1 .latch files are document bundles, not finding packages, and are superseded by this specification. Readers may support them for import only. A reader can tell the versions apart by the magic number. Unencrypted version 1 files begin with the gzip signature 1F 8B.

14. Media type registration

Type name: application
Subtype name: vnd.codynamicslab.latch
Required parameters: N/A
Optional parameters: N/A
Encoding considerations: binary
Security considerations: See Section 12 of the published specification.
Interoperability considerations: Files begin with the 8-byte magic
  number "LATCH2" followed by two null bytes, then a 4-byte
  little-endian header length and a UTF-8 JSON header. The header
  field package_type is "latch", which distinguishes this type from
  application/vnd.codynamicslab.latchdoc, which shares the same magic
  number. Readers must reject unknown major versions and ignore unknown
  fields. Version 1 files use the magic number "LATCH1" and are a
  different, legacy layout.
Published specification: https://www.codynamicslab.com/docs/formats/latch
Applications that use this media type: CoDynamics Lab document
  software, including the LATCH document appliance and its
  verification tools.
Fragment identifier considerations: N/A
Additional information:
  Deprecated alias names for this type: N/A
  Magic number(s): 4C 41 54 43 48 32 00 00 at offset 0
  File extension(s): .latch
  Macintosh file type code(s): N/A
Person & email address to contact for further information:
  mike@codynamicslab.com
Intended usage: COMMON
Restrictions on usage: None
Author: CoDynamics Lab Corporation
Change controller: CoDynamics Lab Corporation

15. Changelog