LATCH Finding Package Format (.latch)
1. Status
LATCH Finding Package Format, specification version 2.0 (draft).
- Change controller: CoDynamics Lab Corporation
- Contact: mike@codynamicslab.com
- Last updated: November 10, 2026
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:
- what was asked, and the exact matching rules used
- every location that was found
- the answer that was shown, broken into claims
- for each claim, the verbatim quote that supports it and where that quote sits in its source
- which model and software produced the answer
- the audit log entry for the query
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:
- Unicode NFC normalization.
- Remove a hyphen immediately followed by a line break (
-\nor-\r\n), joining the word. - Replace every run of whitespace (spaces, tabs, line breaks) with a single space.
- 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:
- Check the magic number and that
header_lenis within a sane limit (recommended maximum 64 KiB). - Parse the header and confirm
package_typeis"latch". - Derive the key, decrypt, and verify the GCM tag.
- Verify the Ed25519 signature against the creating device's public key.
- Check that the SHA-256 of the decrypted plaintext equals
package_id. - Decompress with limits on total size and member count, and apply the path safety rules in Section 12.
- Check that every member is listed in
manifest.jsonand that its SHA-256 matches. - For each claim, find the extracted text whose SHA-256 equals
text_sha256in 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
-
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.
-
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.
-
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.
-
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. -
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:
- Magic
LATCH1\0\0(8 bytes), salt (16 bytes), nonce (12 bytes), ciphertext, GCM tag (16 bytes). The GCM associated data is empty. - Key from PBKDF2-HMAC-SHA256 with 600,000 iterations. If no passphrase is given, version 1 derives the key from the instance license token. If no license token is configured either, version 1 writes an unencrypted tar.gz file with no magic number.
- tar.gz payload containing
manifest.json,documents.json, and per-document compressed memory caches, with no verbatim source text.
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
- 2.0 (draft), November 10, 2026: Initial public specification of the finding package.