Layer 3 Metadata Store

Layer 3 — Metadata Store

A small local file/record store carrying metadata about registrations and magazine entries. Designed to stay tiny — this is metadata, not save content.

Structure

One record per registration and one per magazine entry. The store carries a file-level schema_version (separate from per-record fields) so future field additions can be migrated rather than breaking existing stores.

Full Field Set

All fields are optional except live_path and shape.

Identity Fields

Field	Type	Description
game_id	const char*	Game identifier; NULL if unknown
rom_path	const char*	Path to ROM/disc image; NULL if unknown
rom_hash	uint8_t[20]	SHA-1 hash of ROM; zeroed if not computed
rom_hash_set	bool	Whether rom_hash has been computed

Context Fields

Field	Type	Description
platform	const char*	Target platform; NULL if unknown
emulator	const char*	Emulator name; NULL if unknown
product_version	const char*	Emulator/core/backend version; NULL if unknown

Save Content Fields

Field	Type	Description
live_path	const char*	Required. Path to the live save file/directory
shape	sv_save_shape_t	FILE / DIRECTORY / CONTAINER / ARCHIVE / UNKNOWN

Integrity & Versioning Fields

Field	Type	Description
content_hash	uint8_t[20]	SHA-1 hash of save content; zeroed if not computed
content_hash_set	bool	Whether content_hash has been computed
integrity_ok	bool	Sanity-checked at copy-out time — "is it corrupt"

Disambiguation Metadata

Field	Type	Description
mtime	int64_t	Modification time; 0 if not captured
size_bytes	uint64_t	File size; 0 if not captured
playtime_seconds	uint32_t	Play time; 0 if not supplied
label	const char*	Optional human note; NULL if unset

Magazine Bookkeeping

Field	Type	Description
entry_id	sv_id_t	8-character unique ID
parent_id	sv_id_t	Registration this entry belongs to; zeroed if orphaned
magazine_slot_path	const char*	Read-only, detached/sandboxed path; NULL until copy-out

Unset Value Convention

Every field follows the zero-default rule: unset fields are zeroed/NULL and treated as "unknown," never as an error. This ensures:

• Bare 1:1 sync works with zero metadata
• New fields can be added without breaking old callers
• ABI stability is preserved across versions

---

See also: Architecture-Overview | Layer-4-Local-Save-and-Pull | Data-Types-Reference