KDBX semantic field inventory

This document describes the unreleased protocol-11 KDBX synchronization model implemented in this repository. It classifies decrypted KeePass values as synchronized, file-local, or derived.

The source of truth is the record model in src/core/record.rs, the KDBX conversion code in src/kdbx/convert.rs and src/kdbx/metadata.rs, and the fail-closed XML gate in src/kdbx/mod.rs.

Synchronized values

Database metadata

KeePass value	Synchronized representation
Database name and change time	DatabaseRecord.name, name_changed
Description and change time	description, description_changed
Default username and change time	default_username, default_username_changed
Maintenance history days	maintenance_history_days
Database color	color
Master-key change recommendation and force intervals	master_key_change_recommendation, master_key_change_force
Recycle-bin enabled state, group UUID, and change time	One atomic recycle-bin metadata unit
Entry-template group UUID and change time	One atomic template metadata unit
History item and size limits	history_max_items, history_max_size
Settings change time	settings_changed
Memory-protection flags	Canonically ordered memory_protection map
Database custom data	Typed custom_data map with absent, text, or binary values, item change times, and synchronization-only per-key deletion tombstones
Custom-icon membership	custom_icons plus one IconRecord per icon

Database cursor state is synchronized separately in ViewStateRecord:

• Last selected group UUID
• Last top-visible group UUID

Groups

Each group synchronizes:

• UUID and parent group UUID
• Name, notes, and tags
• Built-in or custom icon reference
• Typed custom data and item change times
• Creation, modification, expiry, and location-change times
• Expiration enabled state
• Last-access time and usage count through ItemActivityRecord
• Default auto-type sequence
• Auto-type and searching tri-state values: inherit, enabled, or disabled
• Previous-parent group UUID, including dangling UUID references
• Mixed child group/entry ordering

Group view state is synchronized separately in ViewStateRecord:

• Expanded state
• Last top-visible entry UUID, including dangling UUID references

Entries

Each entry synchronizes:

• UUID and parent group UUID
• Every string field, including protection state
• Tags
• Foreground and background colors
• URL override
• Built-in or custom icon reference
• Auto-type enabled state, default sequence, obfuscation mode, and ordered associations
• Typed custom data and item change times
• Creation, modification, expiry, and location-change times
• Expiration enabled state
• Last-access time and usage count through ItemActivityRecord
• Attachment name, payload hash, and protected state
• Quality-check state
• Previous-parent group UUID, including dangling UUID references

Entry history

Each non-recursive historical entry synchronizes as an EntryHistoryItemRecord containing:

• Owner entry UUID
• Deterministic history item ID
• Fields and field protection state
• Tags, colors, URL override, auto-type, and icon
• Typed custom data
• KeePass times
• Attachments
• Quality-check state
• Previous-parent group UUID

History additions use set union by history item ID. History deletion and configured count/size pruning create normal tombstones. Conflict resolution does not delete a synchronized history item.

Binary resources and custom icons

Payload bytes synchronize through chunked ResourceRecord values for:

• Entry and historical attachments
• Custom icons
• Binary database, group, entry, and historical custom data

Custom-icon UUID, payload hash, name, and last-modification time synchronize through IconRecord.

File-local values

These values may differ between KDBX files without representing a synchronization difference:

• KDBX cipher selection
• Key-derivation function and parameters
• Compression configuration
• Protected-stream algorithm and stream key
• Master seed, encryption IV, header authentication values, nonces, and salts
• Composite master-key material
• Key-file paths and key-file bytes
• Credential-local master-key timestamps
• Writer Generator

Lattice does not synchronize credentials or KDBX encryption envelopes.

Derived values

These values are rebuilt from synchronized records and may use different physical identifiers:

• Numeric attachment IDs
• Attachment back-reference indexes
• Custom-icon entry, group, and history back-reference indexes
• KDBX inner-header binary ordering
• Physical XML ordering for canonical maps and sets
• KeePassXC’s reserved _LAST_MODIFIED custom-data item, which KeePassXC regenerates from its local clock
• DeletedObjects projections derived from synchronized tombstones
• Record manifests, content hashes, and history item IDs derived from canonical record bytes
• Resource chunk hashes and resource reachability sets
• Lattice conflict artifact groups and entries rebuilt from the converged active-conflict inventory. Their physical UUIDs may differ, but their visible sorted entry paths and counts must converge across replicas.

Rejected input

The KDBX gate rejects data that the parsed model cannot preserve without ambiguity, including:

• Unknown XML elements or attributes
• Duplicate entry string, attachment, or custom-data keys
• Duplicate group or metadata custom-data keys
• Duplicate custom-icon UUID definitions
• Unresolved custom-icon UUID references
• Simultaneous built-in and custom icon fields on one entry or group
• Historical entry UUIDs that differ from the owner entry UUID
• Dangling attachment Ref values
• KDBX4 Meta/Binaries XML payloads

A rejected KDBX is not rewritten. The caller receives an unsupported-feature error before materialization.