ZainoDB V2 — small-footprint DB option for Zallet users

[idky137]

Summary / motivation

Zaino’s current DbV1 is optimised for service efficiency (fast, feature-complete reads) but has a large on-disk footprint and slow initial build (chain sync). Many Zallet users prefer a small, fast-building database with fewer on-disk resources.

We will add a lightweight DbV2 backend that stores only the minimal indexes required for basic chain indexing and the additional, Zaino-specific indexes that Zebra does not provide. DbV2 trades runtime efficiency for smaller size and much faster build times so users can choose the best trade-off for their needs.

Design principles

• Capability driven. DB functionality is exposed through capability traits. A DB that doesn’t implement a capability returns a canonical FeatureUnavailable error.
• Router + abstraction. The router layer already lets multiple DB implementations be used behind the same API; callers remain unaware of which major is active.
• Major co-existence & switching. Majors live in separate directories. We support building/promoting a new major (shadow/promote) and optionally keeping the old major so users can switch back cheaply. Deleting old majors is configurable.
• Migration planning. Migrations move from a strict linear ladder to a version-graph planner so branching (e.g., v1 → v2, v1 → v1.x) is supported without fragile match logic.
• Transparent passthrough. When a capability is unavailable in DbV2, the system should fetch the requested data from the backing validator so callers remain functional.

Behavioral overview

• DbV2 implements a reduced capability set. When finalised-state returns FeatureUnavailable, finalised-state will delegate the request to the backing validator and return the validator response to callers (configurable timeout/enable flag).
• Adding new migrations requires registering version edges in the migration registry; a planner computes a path from current → target. Existing migration bodies remain usable with minimal changes.
• Operators may choose to keep old major directories after promotion (fast switch back) or remove them to conserve disk.

Acceptance criteria

• DbV2 implemented and selectable by config; builds much faster and has a smaller disk footprint than DbV1.
• Migration system uses a version-graph planner; adding new migrations does not require editing a match dispatch.
• Finalised-state passthrough delegates FeatureUnavailable requests to the backing validator transparently, with a configurable timeout and metric for passthroughs. (Possible Solution)
• Startup honours configured major selection even when multiple majors exist on disk.
• Tests exist for planner pathing, major selection, passthrough success/failure/timeouts, and the v0→v1 and v1→v1.1 behaviours are preserved.

Tasks

1. Update ZainoDB migrations to version-graph planning — #859
2. Implement DbV2 and required migrations — #860
3. Implement finalised-state passthrough for FeatureUnavailable — #861

Notes / operational considerations

• We intentionally avoid a Schemerz-style migration-ID applied-set model for now because: (a) our DbVersion triple is the canonical fingerprint, (b) patch fixes are applied as patch migrations (no hotfix branching), and (c) Schemerz does not ship an LMDB adapter — the version-graph gives the necessary flexibility at lower implementation cost. If future needs require it, we can migrate to an applied-ID model later.
• Keep FeatureUnavailable strictly separated from other DB errors (corruption, transient I/O). Passthrough should only trigger for FeatureUnavailable.