Give archive metadata a typed, immutable form #377

Overview

An ArchiveManifest value object gives the archive metadata typed fields, and it converts to and from the stored rows. This work is part of milestone M5.

Background & Motivation

The metadata rows hold JSON strings. Callers must not parse these strings themselves. A typed value object keeps the parsing in one place. It also gives the disk connection its peer info, in the same shape that a morango server gives.

Design: spec. Plan: implementation plan, Task 16.

Description & Expected Outcomes

ArchiveManifest has one field for each metadata key in spec §3.4. It converts to a list of ArchiveManifestEntry rows and back. If the rows contain a key that the reader does not know, the manifest keeps it. This lets metadata from a newer writer survive a read.

The manifest gives a peer info dict with the same shape as the morango info endpoint. A replace method returns a changed copy and does not change the original.

Deliverables & Contracts

The value object delivers these capabilities:

• Conversion to and from ArchiveManifestEntry rows, with JSON values.
• to_peer_info(), with the keys instance_id, instance_hash, version, and capabilities, plus the keys of instance_info.
• replace(**changes), which returns a new manifest.
• Immutable fields.

Acceptance Criteria

• A manifest converted to rows and back is equal to the original.
• to_peer_info() contains the four keys and the merged instance_info keys.
• An unknown row key survives the conversion to a manifest and back to rows.
• replace(filter="x") returns a new manifest, and the original is not changed.

Technical Pointers & Architecture

• Target Components / Context: New module morango/sync/archive.py.
• Related Patterns: The peer info shape comes from MorangoInfoViewSet at morango/api/viewsets.py:491.
• Data Model & Schema Considerations: Uses the ArchiveManifestEntry model from Store archive metadata in a morango table #376. The code must work on Python 3.6, so dataclasses is not available.
• Resilience & Failure Modes: None.

Notes & Tradeoffs

• Dependencies: Blocked by: Store archive metadata in a morango table #376 (ArchiveManifestEntry model). Blocks: Create and discard an archive database file #378, Finalize archives into a compact file at the final path #382.
• Testing Requirements: Unit tests in tests/testapp/tests/sync/test_archive.py.
• Tradeoffs & Alternatives Considered: The spec keeps the table as key and value rows, and it gives callers only the typed form.
• Compatibility & Migrations: Unknown keys survive, so an older reader does not lose data from a newer writer.

Metadata

• Complexity: Low
• Target Branch: release-v0.9.x

AI Usage

Drafted with Claude (Claude Code) from the approved design spec and implementation plan. The author reviewed the requirements, and the code references were checked against the release-v0.9.x codebase.