feat(store): iaf migrate-store + dual-store contract suite (epic #540 phase 3d)

Closes the open Phase 3 deliverables that turn the new store
abstraction into something users can actually move data through:

- iaf migrate-store --from <kind> --src <path> --to <kind> --dst <path>
  delegates to dst.copy_from(src), so it is incremental, restartable,
  and tier-aware: when the destination is a local-tiered store,
  identical OHLCV chunks are written exactly once across the
  destination regardless of how many bundles reference them
  (Phase 3c invariant). Optional --handles subset selector for
  partial migrations.
- migrate_store() programmatic helper for in-process pipelines.
- BacktestStoreContractTest: a parameterised conformance suite
  that runs identical scenarios against every concrete store
  implementation (LocalDirStore, LocalTieredStore today, future
  remote stores tomorrow). Catches divergence as a failing subTest
  with the store class name in the label. Covers Protocol +
  SupportsCopyFrom conformance, write/open round-trip, summary_only,
  exists, idempotent delete, missing-handle errors, listing,
  iter_index_rows, and copy_from with both full and subset handle
  selection.
- bug fix in LazyOhlcvDict: items() and values() were inheriting
  the empty backing dict's iteration, so any code path that did
  'for k, v in bt.ohlcv.items()' silently dropped every blob after
  a tiered round-trip. Now both methods walk the manifest and
  materialise lazily on access. Caught by the migration dedup
  test.

Note on what is *not* in this PR: byte-identical Tier-2 -> Backtest
reassembly (so .iafbt could become export-only) is intentionally
deferred. The current model where the bundle is canonical and
Tier-1/2/3 are derived is simpler, preserves the existing
round-trip contract bit-for-bit, and is what every test in the
contract suite already exercises against both stores.

Targeted suite (backtest_store + backtest_index + cli): 128 / 128
passing + 26 subTests. Full non-scenario suite: 1705 / 1705 passing
with no regressions from the LazyOhlcvDict fix.

Author: MDUYN

investing_algorithm_framework/cli/cli.py

@@ -322,6 +322,78 @@ def migrate_backtests_cmd(
 cli.add_command(migrate_backtests_cmd)
 
 
+_STORE_KINDS = ["local-dir", "local-tiered"]
+
+
+@click.command(name="migrate-store")
+@click.option(
+    "--from", "src_kind",
+    type=click.Choice(_STORE_KINDS),
+    required=True,
+    help="Source store kind.",
+)
+@click.option(
+    "--src",
+    type=click.Path(exists=True, file_okay=False, dir_okay=True),
+    required=True,
+    help="Path to the source store root.",
+)
+@click.option(
+    "--to", "dst_kind",
+    type=click.Choice(_STORE_KINDS),
+    required=True,
+    help="Destination store kind.",
+)
+@click.option(
+    "--dst",
+    type=click.Path(file_okay=False, dir_okay=True),
+    required=True,
+    help="Path to the destination store root (created if missing).",
+)
+@click.option(
+    "--handles",
+    default=None,
+    help=(
+        "Optional comma-separated subset of source handles to copy. "
+        "When omitted, every handle is copied."
+    ),
+)
+def migrate_store_cmd(src_kind, src, dst_kind, dst, handles):
+    """Copy backtests between two :class:`BacktestStore` implementations.
+
+    Uses the destination's :class:`SupportsCopyFrom` capability so the
+    operation is incremental, restartable, and tier-aware: when copying
+    into a ``local-tiered`` store, identical OHLCV chunks are written
+    exactly once across the entire destination, regardless of how many
+    bundles reference them (epic #540 phase 3c).
+
+    Example::
+
+        iaf migrate-store --from local-dir --src ./bt-old \\
+                          --to local-tiered --dst ./bt-new
+    """
+    from .migrate_store_command import migrate_store
+
+    handle_list = (
+        [h.strip() for h in handles.split(",") if h.strip()]
+        if handles else None
+    )
+    n = migrate_store(
+        src_kind=src_kind,
+        src_root=src,
+        dst_kind=dst_kind,
+        dst_root=dst,
+        handles=handle_list,
+    )
+    click.echo(
+        f"Migrated {n} backtest(s) from {src_kind}:{src} "
+        f"to {dst_kind}:{dst}"
+    )
+
+
+cli.add_command(migrate_store_cmd)
+
+
 @click.command(name="index")
 @click.argument(
     "directory",

investing_algorithm_framework/cli/migrate_store_command.py

@@ -0,0 +1,67 @@
+"""``iaf migrate-store`` — copy backtests between :class:`BacktestStore`
+implementations using the :class:`SupportsCopyFrom` capability.
+
+Phase 3d of epic #540.
+"""
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Optional
+
+from investing_algorithm_framework.services.backtest_store import (
+    BacktestStore,
+    LocalDirStore,
+    LocalTieredStore,
+    SupportsCopyFrom,
+)
+
+
+_STORE_FACTORIES = {
+    "local-dir": lambda root: LocalDirStore(root),
+    "local-tiered": lambda root: LocalTieredStore(root),
+}
+
+
+def _build_store(kind: str, root: str) -> BacktestStore:
+    if kind not in _STORE_FACTORIES:
+        raise ValueError(
+            f"unknown store kind {kind!r}; expected one of "
+            f"{sorted(_STORE_FACTORIES)}"
+        )
+    return _STORE_FACTORIES[kind](root)
+
+
+def migrate_store(
+    *,
+    src_kind: str,
+    src_root: str,
+    dst_kind: str,
+    dst_root: str,
+    handles: Optional[list] = None,
+) -> int:
+    """Copy backtests from one store to another.
+
+    Args:
+        src_kind: One of ``"local-dir"``, ``"local-tiered"``.
+        src_root: Path to the source store root.
+        dst_kind: Same vocabulary as ``src_kind``.
+        dst_root: Path to the destination store root.
+        handles: Optional subset of source handles to copy. When
+            ``None`` every handle in the source is copied.
+
+    Returns:
+        The number of backtests written to the destination.
+
+    Raises:
+        TypeError: When the destination store does not implement
+            :class:`SupportsCopyFrom`.
+    """
+    src = _build_store(src_kind, src_root)
+    Path(dst_root).mkdir(parents=True, exist_ok=True)
+    dst = _build_store(dst_kind, dst_root)
+    if not isinstance(dst, SupportsCopyFrom):
+        raise TypeError(
+            f"destination store {dst_kind!r} does not implement "
+            f"SupportsCopyFrom"
+        )
+    return dst.copy_from(src, handles=handles)

investing_algorithm_framework/domain/backtesting/bundle.py

@@ -318,6 +318,14 @@ def __len__(self) -> int:
     def keys(self):  # type: ignore[override]
         return self._manifest.keys()
 
+    def values(self):  # type: ignore[override]
+        for k in self._manifest:
+            yield self[k]
+
+    def items(self):  # type: ignore[override]
+        for k in self._manifest:
+            yield k, self[k]
+
     def __getitem__(self, key: str):
         if key in self._cache:
             return self._cache[key]

tests/cli/test_migrate_store_command.py

@@ -0,0 +1,184 @@
+"""Tests for ``iaf migrate-store`` (epic #540 phase 3d)."""
+from __future__ import annotations
+
+import os
+import shutil
+import tempfile
+from copy import deepcopy
+from pathlib import Path
+from unittest import TestCase
+
+import pandas as pd
+from click.testing import CliRunner
+
+from investing_algorithm_framework.cli.cli import migrate_store_cmd
+from investing_algorithm_framework.cli.migrate_store_command import (
+    migrate_store,
+)
+from investing_algorithm_framework.domain import Backtest
+from investing_algorithm_framework.services.backtest_store import (
+    LocalDirStore,
+    LocalTieredStore,
+)
+
+
+_FIXTURE = os.path.join(
+    os.path.dirname(os.path.dirname(__file__)),
+    "resources",
+    "backtest_reports_for_testing",
+    "test_algorithm_backtest",
+)
+
+
+def _make_ohlcv(symbol: str, *, n: int = 4, base: float = 100.0) -> dict:
+    idx = pd.date_range("2024-01-01", periods=n, freq="h")
+    df = pd.DataFrame(
+        {
+            "Datetime": idx,
+            "Open": [base + i for i in range(n)],
+            "High": [base + i + 0.5 for i in range(n)],
+            "Low": [base + i - 0.5 for i in range(n)],
+            "Close": [base + i + 0.25 for i in range(n)],
+            "Volume": [1000 + i for i in range(n)],
+        }
+    )
+    return {f"{symbol}:1h": df}
+
+
+class TestMigrateStore(TestCase):
+
+    @classmethod
+    def setUpClass(cls):
+        cls.fixture = Backtest.open(_FIXTURE)
+
+    def setUp(self):
+        self.src_dir = tempfile.mkdtemp()
+        self.dst_dir = tempfile.mkdtemp()
+
+    def tearDown(self):
+        shutil.rmtree(self.src_dir, ignore_errors=True)
+        shutil.rmtree(self.dst_dir, ignore_errors=True)
+
+    # ------------------------------------------------------------------
+    # Programmatic API
+    # ------------------------------------------------------------------
+    def test_local_dir_to_local_tiered(self):
+        src = LocalDirStore(self.src_dir)
+        src.write(self.fixture, handle="a")
+        src.write(self.fixture, handle="b")
+
+        n = migrate_store(
+            src_kind="local-dir", src_root=self.src_dir,
+            dst_kind="local-tiered", dst_root=self.dst_dir,
+        )
+        self.assertEqual(n, 2)
+
+        dst = LocalTieredStore(self.dst_dir)
+        self.assertEqual(len(dst), 2)
+        self.assertTrue(dst.exists("a"))
+        self.assertTrue(dst.exists("b"))
+        # Tier-1 was populated.
+        self.assertTrue((Path(self.dst_dir) / "index.sqlite").is_file())
+
+    def test_handles_subset(self):
+        src = LocalDirStore(self.src_dir)
+        src.write(self.fixture, handle="a")
+        src.write(self.fixture, handle="b")
+        src.write(self.fixture, handle="c")
+
+        n = migrate_store(
+            src_kind="local-dir", src_root=self.src_dir,
+            dst_kind="local-tiered", dst_root=self.dst_dir,
+            handles=["a", "c"],
+        )
+        self.assertEqual(n, 2)
+        dst = LocalTieredStore(self.dst_dir)
+        self.assertSetEqual(
+            set(dst.iter_handles()), {"a", "c"},
+        )
+
+    def test_ohlcv_dedup_during_migration(self):
+        # Source is a tiered store (preserves OHLCV); destination is
+        # a fresh tiered store. After migration, identical OHLCV must
+        # collapse to a single chunk on the destination too.
+        src = LocalTieredStore(self.src_dir)
+        bt1 = deepcopy(self.fixture)
+        bt1.ohlcv = _make_ohlcv("BTC/EUR")
+        bt2 = deepcopy(self.fixture)
+        bt2.ohlcv = _make_ohlcv("BTC/EUR")
+        src.write(bt1, handle="a")
+        src.write(bt2, handle="b")
+        # Sanity: src already deduped to one chunk.
+        self.assertEqual(src.ohlcv_stats()["stored_blobs"], 1)
+
+        n = migrate_store(
+            src_kind="local-tiered", src_root=self.src_dir,
+            dst_kind="local-tiered", dst_root=self.dst_dir,
+        )
+        self.assertEqual(n, 2)
+
+        # Phase 3c invariant: identical OHLCV stored once even though
+        # two bundles reference it.
+        dst = LocalTieredStore(self.dst_dir)
+        self.assertEqual(dst.ohlcv_stats()["stored_blobs"], 1)
+        self.assertEqual(dst.ohlcv_stats()["referenced_blobs"], 1)
+
+    def test_unknown_kind_raises(self):
+        with self.assertRaises(ValueError):
+            migrate_store(
+                src_kind="local-dir", src_root=self.src_dir,
+                dst_kind="bogus", dst_root=self.dst_dir,
+            )
+
+    # ------------------------------------------------------------------
+    # CLI
+    # ------------------------------------------------------------------
+    def test_cli_round_trip(self):
+        src = LocalDirStore(self.src_dir)
+        src.write(self.fixture, handle="cli_a")
+        src.write(self.fixture, handle="cli_b")
+
+        runner = CliRunner()
+        result = runner.invoke(
+            migrate_store_cmd,
+            [
+                "--from", "local-dir", "--src", self.src_dir,
+                "--to", "local-tiered", "--dst", self.dst_dir,
+            ],
+        )
+        self.assertEqual(result.exit_code, 0, result.output)
+        self.assertIn("Migrated 2 backtest(s)", result.output)
+
+        dst = LocalTieredStore(self.dst_dir)
+        self.assertEqual(len(dst), 2)
+
+    def test_cli_handles_subset(self):
+        src = LocalDirStore(self.src_dir)
+        for h in ("h1", "h2", "h3"):
+            src.write(self.fixture, handle=h)
+
+        runner = CliRunner()
+        result = runner.invoke(
+            migrate_store_cmd,
+            [
+                "--from", "local-dir", "--src", self.src_dir,
+                "--to", "local-tiered", "--dst", self.dst_dir,
+                "--handles", "h1,h3",
+            ],
+        )
+        self.assertEqual(result.exit_code, 0, result.output)
+        self.assertIn("Migrated 2 backtest(s)", result.output)
+        dst = LocalTieredStore(self.dst_dir)
+        self.assertSetEqual(set(dst.iter_handles()), {"h1", "h3"})
+
+    def test_cli_rejects_unknown_kind(self):
+        runner = CliRunner()
+        result = runner.invoke(
+            migrate_store_cmd,
+            [
+                "--from", "bogus", "--src", self.src_dir,
+                "--to", "local-tiered", "--dst", self.dst_dir,
+            ],
+        )
+        # Click choice validation rejects with non-zero exit.
+        self.assertNotEqual(result.exit_code, 0)