"""Fetch path — wire_fetch_presign, wire_fetch_mpack, wire_fetch, process_mpack_gc_job."""

import asyncio
import hashlib
import logging
import msgpack as _msgpack
import time as _time_module
from collections import deque
from datetime import datetime, timezone
from typing import TypedDict

from sqlalchemy import func, select, text as _sa_text
from sqlalchemy.dialects.postgresql import insert as _pg_insert
from sqlalchemy.ext.asyncio import AsyncSession

from musehub.db.musehub_repo_models import (
    MusehubBranch,
    MusehubCommit,
    MusehubCommitGraph,
    MusehubFetchMPackCache,
    MusehubMPackIndex,
    MusehubObject,
    MusehubObjectRef,
    MusehubRepo,
    MusehubSnapshot,
)
from musehub.models.wire import WireFetchRequest
from muse.core.types import blob_id
from musehub.storage import get_backend

from musehub.services.musehub_wire_shared import (
    FetchMPackResult,
    FetchNotIndexedError,
    MPackNotReadyError,
    FetchPresignResult,
    MPackValidationError,
    _reconstruct_manifest,
    _snap_row_to_wire_s3,
    _commit_to_wire_s3,
    _to_wire_commit,
    _utc_now,
    logger,
)
from musehub.services.musehub_wire_push import _enqueue_repair_prebuild, repair_corrupt_commit_generations


type _CommitDeltaMap = dict[str, MusehubCommitGraph | MusehubCommit]


async def _walk_commit_delta_dag(
    session: AsyncSession,
    starts: list[str],
    have_set: frozenset[str],
) -> _CommitDeltaMap:
    """Authoritative DAG walk over MusehubCommit.parent_ids.

    Called when the graph fast-path detects an incomplete BFS (a missing or
    wrong-generation graph row). Walks the source-of-truth ``musehub_commits``
    table directly and returns the full ancestor closure of ``starts`` minus
    ``have_set``, in parents-first topological order. Bounded by ``max_nodes``
    so a pathological corrupt graph cannot drive an unbounded scan.
    """
    from musehub.graph.walk import walk_dag_async

    _row_cache: dict[str, MusehubCommit] = {}
    _db_calls = 0

    async def _adj(cid: str) -> list[str]:
        nonlocal _db_calls
        _db_calls += 1
        row = await session.get(MusehubCommit, cid)
        if row is not None:
            _row_cache[cid] = row
        return row.parent_ids or [] if row else []

    reachable: list[str] = []
    async for cid in walk_dag_async(starts, _adj, exclude=have_set, max_nodes=100_000):
        reachable.append(cid)

    if len(reachable) >= 100_000:
        logger.warning(
            "[MWP2] _walk_commit_delta_dag: max_nodes cap hit at %d — "
            "history may be truncated; starts=%s",
            100_000, [s[:16] for s in starts[:3]],
        )

    # Kahn's topo-sort — parents-first so every commit precedes its children.
    # walk_dag_async BFS order is children-before-parents; the client applies
    # commits sequentially and skips any whose parent is not yet applied, so
    # ascending topological order avoids redundant skips.
    reachable_set = set(reachable)
    in_degree: dict[str, int] = {cid: 0 for cid in reachable}
    children_map: dict[str, list[str]] = {cid: [] for cid in reachable}
    for cid in reachable:
        row = _row_cache.get(cid)
        for pid in (row.parent_ids or [] if row else []):
            if pid in reachable_set:
                in_degree[cid] += 1
                children_map[pid].append(cid)

    queue: deque[str] = deque(cid for cid, deg in in_degree.items() if deg == 0)
    sorted_cids: list[str] = []
    while queue:
        node = queue.popleft()
        sorted_cids.append(node)
        for child in children_map[node]:
            in_degree[child] -= 1
            if in_degree[child] == 0:
                queue.append(child)

    result: _CommitDeltaMap = {}
    for cid in sorted_cids:
        row = _row_cache.get(cid)
        if row is not None:
            result[cid] = row

    logger.info(
        "[_walk_commit_delta_dag] DONE commits=%d db_calls=%d reachable=%d",
        len(result), _db_calls, len(reachable),
    )
    return result


async def _walk_commit_delta(
    session: AsyncSession,
    want: list[str] | set[str],
    have: list[str] | set[str],
) -> _CommitDeltaMap:
    _wcd_t0 = _time_module.perf_counter()
    _want_list = list(want)
    _have_list = list(have)
    logger.info("[_walk_commit_delta] START want=%d have=%d want_ids=%s",
                len(_want_list), len(_have_list),
                [cid[:16] for cid in _want_list[:5]])

    have_set: frozenset[str] = frozenset(_have_list)
    starts = [cid for cid in _want_list if cid not in have_set]
    if not starts:
        logger.info("[_walk_commit_delta] SKIP — all want in have, 0ms")
        return {}

    from sqlalchemy import func as _func

    want_gen_q = await session.execute(
        select(_func.max(MusehubCommitGraph.generation))
        .where(MusehubCommitGraph.commit_id.in_(starts))
    )
    _want_gen_raw = want_gen_q.scalar()
    max_want_gen: int = _want_gen_raw or 0

    _missing_from_graph: list[str] = []
    _found_in_graph: list[tuple[str, int]] = []
    for _scid in starts[:10]:
        _sg = await session.execute(
            select(MusehubCommitGraph.generation)
            .where(MusehubCommitGraph.commit_id == _scid)
        )
        _sg_val = _sg.scalar_one_or_none()
        if _sg_val is None:
            _missing_from_graph.append(_scid[:16])
        else:
            _found_in_graph.append((_scid[:16], _sg_val))
    logger.info(
        "[_walk_commit_delta] want_gen_raw=%s max_want_gen=%d "
        "starts_in_graph=%s starts_missing_from_graph=%s",
        _want_gen_raw, max_want_gen, _found_in_graph, _missing_from_graph,
    )

    min_have_gen: int = -1
    if have_set:
        have_gen_q = await session.execute(
            select(_func.max(MusehubCommitGraph.generation))
            .where(MusehubCommitGraph.commit_id.in_(list(have_set)))
        )
        min_have_gen = have_gen_q.scalar() or -1

    range_q = await session.execute(
        select(
            MusehubCommitGraph.commit_id,
            MusehubCommitGraph.parent_ids,
            MusehubCommitGraph.snapshot_id,
            MusehubCommitGraph.generation,
        )
        .where(MusehubCommitGraph.generation > min_have_gen)
        .where(MusehubCommitGraph.generation <= max_want_gen)
    )
    graph_map: dict[str, tuple[list[str], str | None, int]] = {
        cid: (pids or [], sid, gen) for cid, pids, sid, gen in range_q
    }
    logger.info(
        "[_walk_commit_delta] range_scan gen=(%d,%d] returned %d rows "
        "starts_in_map=%s",
        min_have_gen, max_want_gen, len(graph_map),
        [cid[:16] for cid in starts if cid in graph_map],
    )

    # [MWP2] Start detection: any want tip absent from graph_map means the range
    # scan was starved (its generation was None/0) or the row was never written.
    graph_incomplete: bool = any(s not in graph_map for s in starts)

    visited_mem: set[str] = set(have_set)
    frontier_mem = [cid for cid in starts if cid not in visited_mem]
    reachable_cids: set[str] = set()
    while frontier_mem:
        next_mem: list[str] = []
        for cid in frontier_mem:
            if cid in visited_mem:
                continue
            visited_mem.add(cid)
            reachable_cids.add(cid)
            # [MWP2] BFS dead-end detection: a commit not in graph_map has no
            # known parents — the walk cannot follow the true ancestry chain.
            _entry = graph_map.get(cid)
            if _entry is None:
                graph_incomplete = True
                pids_for_cid: list[str] = []
            else:
                pids_for_cid, _, _gen = _entry
            for p in pids_for_cid:
                if p not in visited_mem and p not in have_set:
                    next_mem.append(p)
        frontier_mem = next_mem

    # [MWP2] If any dead-end was detected, the fast-path result is incomplete.
    # Fall back to the authoritative MusehubCommit DAG walk so the current
    # response is always correct regardless of graph state.
    if graph_incomplete:
        logger.error(
            "[MWP2] fast-path BFS incomplete — missing_starts=%d want=%d have=%d; "
            "falling back to authoritative MusehubCommit DAG walk",
            sum(1 for s in starts if s not in graph_map),
            len(starts), len(have_set),
        )
        return await _walk_commit_delta_dag(session, starts, have_set)

    from types import SimpleNamespace as _SN
    # Sort by generation ASC so parents appear before children in the dict.
    # reachable_cids is a set — iteration order is undefined — and the client
    # applies commits sequentially, skipping any whose parent hasn't been applied
    # yet.  Ascending generation = topological order = every parent precedes its
    # children in the mpack.
    sorted_cids = sorted(reachable_cids, key=lambda c: graph_map.get(c, ([], None, 0))[2])
    needed_graph: dict[str, _SN] = {}
    for cid in sorted_cids:
        pids_ns, sid_ns, _ = graph_map.get(cid, ([], None, 0))
        needed_graph[cid] = _SN(commit_id=cid, snapshot_id=sid_ns, parent_ids=pids_ns)

    _wcd_elapsed = (_time_module.perf_counter() - _wcd_t0) * 1000
    logger.info(
        "[_walk_commit_delta] DONE (graph) commits=%d elapsed=%.1fms (%.3fms/commit) "
        "gen_range=(%d,%d] graph_rows=%d reachable=%d",
        len(needed_graph), _wcd_elapsed, _wcd_elapsed / max(len(needed_graph), 1),
        min_have_gen, max_want_gen, len(graph_map), len(reachable_cids),
    )
    return needed_graph  # type: ignore[return-value]


async def wire_fetch_presign(
    session: AsyncSession,
    repo_id: str,
    req: WireFetchRequest,
    ttl_seconds: int = 3600,
) -> FetchPresignResult:
    import asyncio
    from datetime import timedelta

    _empty: FetchPresignResult = {
        "presign": False,
        "blob_urls": {},
        "commits": [],
        "snapshots": [],
        "branch_heads": {},
        "repo_id": repo_id,
        "domain": "",
        "default_branch": "main",
        "expires_at": None,
        "commit_count": 0,
        "blob_count": 0,
    }

    if not req.want:
        return _empty

    repo_row = await session.get(MusehubRepo, repo_id)
    if repo_row is None:
        return _empty
    _domain: str = repo_row.domain_id or ""
    _default_branch: str = repo_row.default_branch if repo_row.default_branch else "main"
    _empty["domain"] = _domain
    _empty["default_branch"] = _default_branch
    _empty["repo_id"] = repo_id

    have_set = set(req.have)
    needed_rows = await _walk_commit_delta(session, req.want, have_set)

    if not needed_rows:
        return {**_empty, "domain": _domain, "default_branch": _default_branch}

    _presign_commit_rows: dict[str, MusehubCommit] = {}
    _presign_any = next(iter(needed_rows.values()))
    if not isinstance(_presign_any, MusehubCommit):
        _PRESIGN_WIRE_BATCH = 2000
        _presign_cids = list(needed_rows.keys())
        for _pi in range(0, len(_presign_cids), _PRESIGN_WIRE_BATCH):
            _pq = await session.execute(
                select(MusehubCommit).where(MusehubCommit.commit_id.in_(_presign_cids[_pi : _pi + _PRESIGN_WIRE_BATCH]))
            )
            for _pr in _pq.scalars():
                _presign_commit_rows[_pr.commit_id] = _pr
    else:
        _presign_commit_rows = needed_rows  # type: ignore[assignment]

    snap_ids = [r.snapshot_id for r in needed_rows.values() if r.snapshot_id]
    all_oids: set[str] = set()
    if snap_ids:
        snaps_q = await session.execute(
            select(MusehubSnapshot).where(MusehubSnapshot.snapshot_id.in_(snap_ids))
        )
        for snap in snaps_q.scalars().all():
            manifest = (
                _msgpack.unpackb(snap.manifest_blob, raw=False)
                if snap.manifest_blob
                else await _reconstruct_manifest(session, snap.snapshot_id)
            )
            all_oids.update(v for v in manifest.values() if v)

    have_snap_ids: list[str] = []
    if have_set:
        have_commits_q = await session.execute(
            select(MusehubCommit).where(MusehubCommit.commit_id.in_(have_set))
        )
        have_snap_ids = [r.snapshot_id for r in have_commits_q.scalars().all() if r.snapshot_id]
    have_oids: set[str] = set()
    if have_snap_ids:
        have_snaps_q = await session.execute(
            select(MusehubSnapshot).where(MusehubSnapshot.snapshot_id.in_(have_snap_ids))
        )
        for snap in have_snaps_q.scalars().all():
            manifest = (
                _msgpack.unpackb(snap.manifest_blob, raw=False)
                if snap.manifest_blob
                else await _reconstruct_manifest(session, snap.snapshot_id)
            )
            have_oids.update(v for v in manifest.values() if v)

    new_oids = all_oids - have_oids
    n_objects = len(new_oids)
    n_commits = len(needed_rows)

    total_size = 0
    if new_oids:
        size_q = await session.execute(
            select(func.coalesce(func.sum(MusehubObject.size_bytes), 0)).where(
                MusehubObject.object_id.in_(list(new_oids))
            )
        )
        total_size = int(size_q.scalar() or 0)

    backend = get_backend()

    wire_commits = [
        (await _commit_to_wire_s3(row, backend)).model_dump()
        for row in _presign_commit_rows.values()
    ]

    snap_rows_q = await session.execute(
        select(MusehubSnapshot).where(MusehubSnapshot.snapshot_id.in_(snap_ids))
    )
    wire_snaps = [
        await _snap_row_to_wire_s3(snap, backend, session=session)
        for snap in snap_rows_q.scalars().all()
    ]

    branch_rows_q = await session.execute(
        select(MusehubBranch).where(MusehubBranch.repo_id == repo_id)
    )
    branch_heads = {
        b.name: b.head_commit_id
        for b in branch_rows_q.scalars().all()
        if b.head_commit_id
    }

    sem = asyncio.Semaphore(50)

    logger.info(
        "fetch/presign: generating %d presigned GET URLs repo=%s/%s",
        len(new_oids), repo_row.owner, repo_row.slug,
    )

    async def _presign_one(oid: str) -> tuple[str, str]:
        async with sem:
            url = await backend.presign_get(oid, ttl_seconds)
            logger.debug("fetch/presign: presigned oid=%s", oid)
            return oid, url

    pairs = await asyncio.gather(*(_presign_one(oid) for oid in new_oids))
    blob_urls = {oid: url for oid, url in pairs}
    expires_at = (_utc_now() + timedelta(seconds=ttl_seconds)).isoformat()

    return {
        "presign": True,
        "blob_urls": blob_urls,
        "commits": wire_commits,
        "snapshots": wire_snaps,
        "branch_heads": branch_heads,
        "repo_id": repo_id,
        "domain": _domain,
        "default_branch": _default_branch,
        "expires_at": expires_at,
        "commit_count": n_commits,
        "blob_count": n_objects,
    }

async def wire_fetch_mpack(
    session: AsyncSession,
    repo_id: str,
    want: list[str],
    have: list[str],
    ttl_seconds: int = 3600,
    force_build: bool = False,
) -> FetchMPackResult:
    import msgpack as _msgpack_local

    _t0 = _time_module.perf_counter()
    def _ms() -> float:
        return (_time_module.perf_counter() - _t0) * 1000

    logger.info("[wire_fetch_mpack] START repo_id=%s want=%d have=%d want_ids=%s",
                repo_id, len(want), len(have), [cid[:16] for cid in want[:5]])

    _up_to_date: FetchMPackResult = {
        "mpack_url": None,
        "mpack_id": None,
        "commit_count": 0,
        "blob_count": 0,
    }

    if not want:
        logger.info("[wire_fetch_mpack] SKIP — want is empty")
        return _up_to_date

    backend = get_backend()

    # FMC_09 / FMC_10 / FMC_12 — cache lookup for fresh clones (have=[]).
    # For multi-tip requests, all tips must map to the same mpack_id (built by
    # the prebuild as one combined mpack).
    if not have:
        _cache_t0 = _time_module.perf_counter()
        _cached_rows = (await session.execute(
            select(MusehubFetchMPackCache)
            .where(MusehubFetchMPackCache.repo_id == repo_id)
            .where(MusehubFetchMPackCache.tip_commit_id.in_(want))
            .where(MusehubFetchMPackCache.expires_at > _utc_now())
        )).scalars().all()
        _cache_ms = (_time_module.perf_counter() - _cache_t0) * 1000
        _cached_tips = {r.tip_commit_id: r.mpack_id for r in _cached_rows}
        _mpack_ids = set(_cached_tips.values())
        if len(_cached_tips) == len(want) and len(_mpack_ids) == 1:
            _hit_mpack_id = next(iter(_mpack_ids))
            _cached_url = await backend.presign_mpack_get(_hit_mpack_id, ttl_seconds)
            logger.warning(
                "[wire_fetch_mpack] cache=HIT tips=%d mpack_id=%s t=%.1fms",
                len(want), _hit_mpack_id[:20], _cache_ms,
            )
            return {
                "mpack_url": _cached_url,
                "mpack_id": _hit_mpack_id,
                "commit_count": 0,
                "blob_count": 0,
            }
        if not force_build:
            # Self-heal: a MISS can mean "never built" OR "built, then expired"
            # (musehub_fetch_mpack_cache rows carry a TTL). Either way, nothing
            # else re-triggers a rebuild for a repo that isn't actively being
            # pushed to — without this, a dormant repo's cache expires once and
            # clone is permanently broken until someone happens to push again.
            # _enqueue_repair_prebuild is idempotent (enqueue_job skips the
            # insert when a job of this type is already pending for this repo),
            # so it's safe to call on every MISS.
            await _enqueue_repair_prebuild(session, repo_id)
            await session.commit()
            logger.warning(
                "[wire_fetch_mpack] cache=MISS tips=%d cached_tips=%d t=%.1fms — "
                "enqueued fetch.mpack.prebuild, raising MPackNotReadyError",
                len(want), len(_cached_tips), _cache_ms,
            )
            raise MPackNotReadyError()
        logger.warning(
            "[wire_fetch_mpack] cache=MISS tips=%d cached_tips=%d t=%.1fms — force_build=True, continuing",
            len(want), len(_cached_tips), _cache_ms,
        )

    have_set = set(have)
    logger.info("[wire_fetch_mpack] step=1 DAG walk starting t=%.1fms", _ms())
    needed_rows = await _walk_commit_delta(session, want, have_set)
    logger.info("[wire_fetch_mpack] step=1 DAG walk done commits=%d t=%.1fms", len(needed_rows), _ms())

    if not needed_rows:
        logger.info("[wire_fetch_mpack] SKIP — client already up-to-date (needed_rows empty)")
        return _up_to_date

    commit_rows: dict[str, MusehubCommit] = {}
    _any = next(iter(needed_rows.values()))
    _is_proxy = not isinstance(_any, MusehubCommit)
    logger.info("[wire_fetch_mpack] step=1b needed_rows=%d is_proxy=%s t=%.1fms",
                len(needed_rows), _is_proxy, _ms())
    if _is_proxy:
        _cids = list(needed_rows.keys())
        _q = await session.execute(
            select(MusehubCommit).where(
                _sa_text("commit_id = ANY(:ids)").bindparams(ids=_cids)
            )
        )
        for _row in _q.scalars():
            commit_rows[_row.commit_id] = _row
        _missing_from_db = set(_cids) - set(commit_rows.keys())
        logger.info(
            "[wire_fetch_mpack] step=1b bulk fetch done commits_in_db=%d missing_from_db=%d "
            "missing_ids=%s t=%.1fms",
            len(commit_rows), len(_missing_from_db),
            [cid[:16] for cid in list(_missing_from_db)[:5]], _ms(),
        )
    else:
        commit_rows = needed_rows  # type: ignore[assignment]
        logger.info("[wire_fetch_mpack] step=1b using MusehubCommit rows directly commits=%d t=%.1fms",
                    len(commit_rows), _ms())

    _proxy_snap_ids_raw = [r.snapshot_id for r in needed_rows.values()]
    _graph_snap_ids = [sid for sid in _proxy_snap_ids_raw if sid]
    _proxy_snap_none_count = sum(1 for s in _proxy_snap_ids_raw if not s)
    _commit_row_snap_ids = [r.snapshot_id for r in commit_rows.values() if r.snapshot_id]
    # Defensive fallback: CommitGraph rows from server-side merges may have snapshot_id=None
    # (pre-fix state). The MusehubCommit row always has the correct snapshot_id — merge both.
    snap_ids = list({*_graph_snap_ids, *_commit_row_snap_ids})
    logger.info(
        "[wire_fetch_mpack] step=2 snap_ids_from_graph=%d snap_ids_none_in_graph=%d "
        "snap_ids_from_commit_rows=%d snap_ids_total=%d t=%.1fms",
        len(_graph_snap_ids), _proxy_snap_none_count, len(_commit_row_snap_ids), len(snap_ids), _ms(),
    )

    snap_map: dict[str, dict] = {}
    if snap_ids:
        snaps_q = await session.execute(
            select(MusehubSnapshot).where(
                _sa_text("snapshot_id = ANY(:ids)").bindparams(ids=snap_ids)
            )
        )
        for snap in snaps_q.scalars().all():
            snap_map[snap.snapshot_id] = await _snap_row_to_wire_s3(snap, backend, session=session)
    logger.info("[wire_fetch_mpack] step=2 snap_map loaded=%d t=%.1fms", len(snap_map), _ms())

    all_oids: set[str] = set()
    _needed_cids = list(needed_rows.keys())
    logger.warning("[GRAPH-DEBUG] wire_fetch_mpack: needed_rows=%d needed_cids_sample=%s",
                   len(_needed_cids), [c[:16] for c in _needed_cids[:3]])
    _debug_graph_q = await session.execute(
        select(MusehubCommitGraph.commit_id, MusehubCommitGraph.generation, MusehubCommitGraph.snapshot_id)
        .where(MusehubCommitGraph.commit_id.in_(_needed_cids))
        .order_by(MusehubCommitGraph.generation.desc())
        .limit(5)
    )
    _debug_graph_rows = _debug_graph_q.all()
    logger.warning("[GRAPH-DEBUG] wire_fetch_mpack: CommitGraph has %d rows for needed_cids (top 5 by gen): %s",
                   len(_debug_graph_rows),
                   [(r[1], r[0][:16]) for r in _debug_graph_rows])
    want_tip_snap_q = await session.execute(
        select(MusehubCommitGraph.snapshot_id)
        .where(MusehubCommitGraph.commit_id.in_(_needed_cids))
        .order_by(MusehubCommitGraph.generation.desc())
        .limit(1)
    )
    want_tip_snap_id = want_tip_snap_q.scalar_one_or_none()
    logger.warning("[GRAPH-DEBUG] wire_fetch_mpack: want_tip_snap_id=%s",
                   want_tip_snap_id[:20] if want_tip_snap_id else "NONE")
    logger.info("[wire_fetch_mpack] step=2 want_tip_snap_id=%s (from CommitGraph) t=%.1fms",
                want_tip_snap_id[:16] if want_tip_snap_id else None, _ms())
    # [BLOB-DEBUG] Compare want_tip_snap_id (from CommitGraph) vs actual want commits'
    # snapshot IDs (from commit_rows). A mismatch means CommitGraph is stale for the
    # newest push — the old snapshot's manifest_blob would be missing new blobs.
    _want_snap_ids_from_commit_rows = {
        commit_rows[cid].snapshot_id
        for cid in want
        if cid in commit_rows and commit_rows[cid].snapshot_id
    }
    logger.warning(
        "[BLOB-DEBUG] want_tip_snap_id (CommitGraph max-gen)=%s "
        "want_snap_ids_from_commit_rows=%s  MATCH=%s",
        want_tip_snap_id[:20] if want_tip_snap_id else "NONE",
        [s[:20] for s in _want_snap_ids_from_commit_rows],
        want_tip_snap_id in _want_snap_ids_from_commit_rows if want_tip_snap_id else False,
    )

    # [MWP1_13] Fetch-side guard: if the CommitGraph's max-gen snapshot disagrees
    # with the authoritative MusehubCommit snapshot, the graph has a corrupt
    # generation (RC-1 artefact). Repair in-place before assembling the mpack so
    # a stale clone is never shipped. Full DAG-walk fallback is MWP-2.
    if (
        want_tip_snap_id is not None
        and _want_snap_ids_from_commit_rows
        and want_tip_snap_id not in _want_snap_ids_from_commit_rows
    ):
        logger.error(
            "[MWP1] fetch-side guard: want_tip_snap_id=%s not in "
            "commit_rows snapshot_ids=%s — repairing corrupt commit generations",
            want_tip_snap_id[:20],
            [s[:20] for s in _want_snap_ids_from_commit_rows],
        )
        _repair_result = await repair_corrupt_commit_generations(session)
        logger.error("[MWP1] fetch-side repair complete: %s", _repair_result)
        # Re-query to pick up the corrected tip snapshot after repair.
        _requery = await session.execute(
            select(MusehubCommitGraph.snapshot_id)
            .where(MusehubCommitGraph.commit_id.in_(_needed_cids))
            .order_by(MusehubCommitGraph.generation.desc())
            .limit(1)
        )
        want_tip_snap_id = _requery.scalar_one_or_none()
        logger.error(
            "[MWP1] fetch-side guard: want_tip_snap_id after repair=%s",
            want_tip_snap_id[:20] if want_tip_snap_id else "NONE",
        )

    if want_tip_snap_id:
        wt_blob_q = await session.execute(
            select(MusehubSnapshot.manifest_blob, MusehubSnapshot.entry_count)
            .where(MusehubSnapshot.snapshot_id == want_tip_snap_id)
        )
        wt_row = wt_blob_q.one_or_none()
        wt_blob = wt_row[0] if wt_row else None
        wt_entry_count_db = wt_row[1] if wt_row else None
        if wt_blob:
            wt_manifest = _msgpack_local.unpackb(wt_blob, raw=False)
            wt_entry_count_blob = len(wt_manifest)
        else:
            wt_entry_count_blob = 0
        # Use the snap_map manifest (validated/reconstructed via _snap_row_to_wire_s3) instead
        # of raw manifest_blob to populate all_oids. manifest_blob may have null OIDs for files
        # pushed after the snapshot was indexed, causing those blobs to be silently omitted from
        # the mpack. snap_map['manifest'] is always complete — rebuilt from delta chain if needed.
        _tip_snap_entry = snap_map.get(want_tip_snap_id)
        if _tip_snap_entry:
            all_oids.update(v for v in (_tip_snap_entry.get("manifest") or {}).values() if v)
        # [BLOB-DEBUG] Log discrepancy between manifest_blob and snap_map to confirm the fix.
        # entry_count_blob vs snap_map_manifest_size should now match; all_oids should equal
        # snap_map_manifest_size (minus any genuinely null entries).
        logger.warning(
            "[BLOB-DEBUG] want_tip_snap=%s manifest_blob=%s "
            "entry_count_db=%s entry_count_blob=%d all_oids=%d  "
            "snap_map_has_tip=%s snap_map_manifest_size=%d",
            want_tip_snap_id[:20] if want_tip_snap_id else "NONE",
            "present" if wt_blob else "ABSENT",
            wt_entry_count_db,
            wt_entry_count_blob,
            len(all_oids),
            want_tip_snap_id in snap_map,
            len((snap_map.get(want_tip_snap_id) or {}).get("manifest") or {}),
        )
        logger.info("[wire_fetch_mpack] step=2 want_tip manifest all_oids=%d wt_blob_present=%s t=%.1fms",
                    len(all_oids), wt_blob is not None, _ms())
    else:
        logger.warning(
            "[wire_fetch_mpack] step=2 WARN want_tip_snap_id=None — CommitGraph missing tip "
            "needed_cids=%s commit_rows_snap_ids=%s",
            [cid[:16] for cid in list(needed_rows.keys())[:5]],
            [sid[:16] for sid in _commit_row_snap_ids[:5]],
        )

    # musehub#113 fix: the block above only ever consults ONE snapshot —
    # whichever commit has the single globally-highest generation across ALL
    # walked commits (`_needed_cids`, which includes ancestors, not just the
    # requested tips). That is correct only when `want` contains a single
    # tip. A `want` set spanning multiple branch tips — which every real
    # clone/fetch request does, since the client always requests every known
    # branch tip regardless of `--branch` — needs the UNION of every
    # requested tip's own manifest, not just one. A tie at the same
    # generation (two sibling branches cut from the same base) picks one
    # arbitrarily; a genuine depth difference picks the deeper one
    # deterministically — either way every other tip's unique blobs were
    # silently absent from the response. Resolve each want-tip's own
    # snapshot from its authoritative `MusehubCommit` row (`commit_rows`,
    # never from the generation-ranked pick above) so ties and depth
    # differences can no longer drop content.
    _pre_union_oids = len(all_oids)
    for _want_cid in want:
        _want_commit_row = commit_rows.get(_want_cid)
        if _want_commit_row is None or not _want_commit_row.snapshot_id:
            continue
        _want_snap_entry = snap_map.get(_want_commit_row.snapshot_id)
        if _want_snap_entry:
            all_oids.update(v for v in (_want_snap_entry.get("manifest") or {}).values() if v)
    logger.info(
        "[wire_fetch_mpack] step=2b multi-tip manifest union: want=%d all_oids %d -> %d t=%.1fms",
        len(want), _pre_union_oids, len(all_oids), _ms(),
    )

    # musehub#113 fix (mirror of the all_oids union above): the old
    # implementation picked a single have-tip's manifest via the same
    # generation-ranked query used for all_oids, and read it from the raw
    # `manifest_blob` column rather than the safe snap_map reconstruction
    # (`_snap_row_to_wire_s3` — the same class of gap the BLOB-DEBUG comment
    # above already documented for all_oids: "manifest_blob may have null
    # OIDs for files pushed after the snapshot was indexed"). A `have` set
    # spanning multiple tips (any client tracking more than one branch) had
    # everything but the single winning tip's content silently excluded
    # from `have_oids`. Unlike the all_oids bug this cannot drop content —
    # `new_oids = all_oids - have_oids` only grows when have_oids is
    # undercounted — but it does mean the server redundantly re-sends
    # objects the client explicitly reported already having, for every
    # push/branch beyond whichever one wins the generation pick.
    have_oids: set[str] = set()
    if have_set:
        have_commit_rows_q = await session.execute(
            select(MusehubCommit).where(MusehubCommit.commit_id.in_(list(have_set)))
        )
        have_commit_rows = {r.commit_id: r for r in have_commit_rows_q.scalars().all()}
        have_snap_ids = {r.snapshot_id for r in have_commit_rows.values() if r.snapshot_id}
        if have_snap_ids:
            have_snaps_q = await session.execute(
                select(MusehubSnapshot).where(MusehubSnapshot.snapshot_id.in_(list(have_snap_ids)))
            )
            for _have_snap in have_snaps_q.scalars().all():
                _have_snap_entry = await _snap_row_to_wire_s3(_have_snap, backend, session=session)
                have_oids.update(v for v in (_have_snap_entry.get("manifest") or {}).values() if v)

    new_oids = all_oids - have_oids
    logger.info(
        "[wire_fetch_mpack] step=2 done snap_map=%d all_oids=%d have_oids=%d new_oids=%d t=%.1fms",
        len(snap_map), len(all_oids), len(have_oids), len(new_oids), _ms(),
    )

    if new_oids:
        indexed_q = await session.execute(
            select(MusehubMPackIndex.entity_id)
            .where(MusehubMPackIndex.entity_id.in_(list(new_oids)))
            .where(MusehubMPackIndex.entity_type == "object")
        )
        indexed_oids = {row[0] for row in indexed_q}
        missing = new_oids - indexed_oids
        if missing:
            logger.warning(
                "[wire_fetch_mpack] step=3 NOT INDEXED %d/%d objects — raising FetchNotIndexedError t=%.1fms",
                len(missing), len(new_oids), _ms(),
            )
            raise FetchNotIndexedError(len(missing))
        logger.info("[wire_fetch_mpack] step=3 index coverage OK oids=%d t=%.1fms", len(new_oids), _ms())

    cache_hits: dict[str, bytes] = {}
    if new_oids:
        _CACHE_CHUNK = 10000
        _new_oid_list = list(new_oids)
        for _ci in range(0, len(_new_oid_list), _CACHE_CHUNK):
            _chunk = _new_oid_list[_ci : _ci + _CACHE_CHUNK]
            _cache_q = await session.execute(
                select(MusehubObject.object_id, MusehubObject.content_cache)
                .where(MusehubObject.object_id.in_(_chunk))
                .where(MusehubObject.content_cache.isnot(None))
            )
            for _oid, _cached in _cache_q:
                if _cached:
                    cache_hits[_oid] = bytes(_cached)

    cache_miss_oids = [oid for oid in new_oids if oid not in cache_hits]

    oid_to_mpack: dict[str, str] = {}
    if cache_miss_oids:
        _MIDX_CHUNK = 10000
        for _ci in range(0, len(cache_miss_oids), _MIDX_CHUNK):
            _chunk = cache_miss_oids[_ci : _ci + _MIDX_CHUNK]
            _midx_q = await session.execute(
                select(MusehubMPackIndex.entity_id, MusehubMPackIndex.mpack_id)
                .where(MusehubMPackIndex.entity_id.in_(_chunk))
                .where(MusehubMPackIndex.entity_type == "object")
            )
            for _oid, _mid in _midx_q:
                oid_to_mpack[_oid] = _mid

    mpack_to_oids: dict[str, list[str]] = {}
    no_mpack_oids: list[str] = []
    for oid in cache_miss_oids:
        mid = oid_to_mpack.get(oid)
        if mid:
            mpack_to_oids.setdefault(mid, []).append(oid)
        else:
            no_mpack_oids.append(oid)

    mpack_hits: dict[str, bytes] = {}
    mpack_miss_oids: list[str] = []
    _sem_mpack = asyncio.Semaphore(8)

    async def _extract_from_mpack(mpack_id: str, oids: list[str]) -> None:
        async with _sem_mpack:
            raw = await backend.get_mpack(mpack_id)
            if raw is None:
                mpack_miss_oids.extend(oids)
                return
            import zstandard as _zstd_phase1
            _dctx_phase1 = _zstd_phase1.ZstdDecompressor()
            try:
                if raw[:4] == b"MUSE":
                    from muse.core.mpack import parse_wire_mpack as _parse_wire_fetch
                    payload = _parse_wire_fetch(raw)
                else:
                    payload = _msgpack_local.unpackb(raw, raw=False)
            except Exception as _parse_err:
                logger.warning(
                    "[_extract_from_mpack] failed to parse mpack=%s: %s",
                    mpack_id[:20], _parse_err,
                )
                mpack_miss_oids.extend(oids)
                return
            obj_index: dict[str, bytes] = {}
            for o in payload.get("blobs", []):
                oid_entry = o.get("object_id", "")
                content = o.get("content") or b""
                if not isinstance(content, bytes):
                    content = bytes(content)
                _ZSTD_MAGIC = b"\x28\xb5\x2f\xfd"
                if (o.get("encoding") == "zstd" or content[:4] == _ZSTD_MAGIC) and content:
                    try:
                        content = _dctx_phase1.decompress(content)
                    except Exception as _decomp_err:
                        logger.warning(
                            "[_extract_from_mpack] zstd decompress failed oid=%s: %s",
                            oid_entry[:20], _decomp_err,
                        )
                        continue
                obj_index[oid_entry] = content
            for oid in oids:
                content = obj_index.get(oid)
                if content is not None:
                    mpack_hits[oid] = content
                else:
                    mpack_miss_oids.append(oid)

    if mpack_to_oids:
        await asyncio.gather(
            *(_extract_from_mpack(mid, oids) for mid, oids in mpack_to_oids.items())
        )

    legacy_hits: dict[str, bytes] = {}
    _fallback_oids = no_mpack_oids + mpack_miss_oids
    if _fallback_oids:
        _sem_legacy = asyncio.Semaphore(50)

        async def _get_legacy(oid: str) -> None:
            async with _sem_legacy:
                data = await backend.get(oid)
                if data:
                    legacy_hits[oid] = data

        await asyncio.gather(*(_get_legacy(oid) for oid in _fallback_oids))

    _all_blob_bytes: dict[str, bytes] = {**legacy_hits, **mpack_hits, **cache_hits}
    blob_pairs = [(oid, _all_blob_bytes[oid]) for oid in new_oids if oid in _all_blob_bytes]
    logger.info(
        "[wire_fetch_mpack] step=4 fetched %d blobs (cache=%d mpack=%d legacy=%d) t=%.1fms",
        len(blob_pairs), len(cache_hits), len(mpack_hits), len(legacy_hits), _ms(),
    )

    wire_commits = [
        (await _commit_to_wire_s3(commit_rows[cid], backend)).model_dump()
        for cid in needed_rows.keys()
        if cid in commit_rows
    ]
    wire_snaps = [snap_map[sid] for sid in snap_ids if sid in snap_map]
    wire_blobs = [
        {"object_id": oid, "content": data}
        for oid, data in blob_pairs
        if data
    ]
    logger.info(
        "[wire_fetch_mpack] step=5 assembly: wire_commits=%d wire_snaps=%d wire_blobs=%d "
        "snap_ids_total=%d snap_ids_in_map=%d commit_rows=%d t=%.1fms",
        len(wire_commits), len(wire_snaps), len(wire_blobs),
        len(snap_ids), sum(1 for sid in snap_ids if sid in snap_map),
        len(commit_rows), _ms(),
    )

    from muse.core.mpack import build_wire_mpack as _build_wire_mpack
    _head_commit_id = want[0] if want else ""
    mpack_bytes = _build_wire_mpack(
        {
            "commits":   wire_commits,
            "snapshots": wire_snaps,
            "blobs":     wire_blobs,
            "tags":      [],
        },
        meta={"repo_id": repo_id, "head_commit_id": _head_commit_id},
    )
    mpack_id = blob_id(mpack_bytes)

    n_commits = len(wire_commits)
    n_blobs = len(wire_blobs)
    logger.info(
        "[wire_fetch_mpack] step=5 assembled commits=%d snapshots=%d blobs=%d bytes=%d t=%.1fms",
        n_commits, len(wire_snaps), n_blobs, len(mpack_bytes), _ms(),
    )

    await backend.put_mpack(mpack_id, mpack_bytes)
    mpack_url = await backend.presign_mpack_get(mpack_id, ttl_seconds)
    logger.info(
        "[wire_fetch_mpack] step=6 mpack_id=%s mpack_url=%s t=%.1fms",
        mpack_id[:20], mpack_url[:80] if mpack_url else None, _ms(),
    )
    logger.info("[wire_fetch_mpack] RETURN commits=%d blobs=%d TOTAL=%.1fms", n_commits, n_blobs, _ms())

    # FMC_11 — on a fresh-clone miss, write a cache row per tip so the next clone is a hit.
    # For multi-tip requests all tips get the same mpack_id so the multi-tip cache
    # check (len(cached_tips)==len(want) and single mpack_id) will fire on the next request.
    if not have:
        from datetime import timedelta as _timedelta
        _miss_expires = _utc_now() + _timedelta(days=7)
        for _tip in want:
            _miss_cache_id = blob_id((repo_id + _tip).encode()).replace("sha256:", "")
            await session.execute(
                _pg_insert(MusehubFetchMPackCache)
                .values(
                    cache_id=_miss_cache_id,
                    repo_id=repo_id,
                    tip_commit_id=_tip,
                    mpack_id=mpack_id,
                    created_at=_utc_now(),
                    expires_at=_miss_expires,
                )
                .on_conflict_do_update(
                    index_elements=["repo_id", "tip_commit_id"],
                    set_={"mpack_id": mpack_id, "expires_at": _miss_expires},
                )
            )

    return {
        "mpack_url":    mpack_url,
        "mpack_id":     mpack_id,
        "commit_count": n_commits,
        "blob_count":   n_blobs,
    }

async def _check_missing_objects(
    session: AsyncSession,
    needs_check: set[str],
) -> set[str]:
    if not needs_check:
        return set()
    from musehub.db.musehub_repo_models import MusehubObject
    registered: set[str] = set(
        (await session.execute(
            select(MusehubObject.object_id).where(
                MusehubObject.object_id.in_(list(needs_check)),
                MusehubObject.deleted_at.is_(None),
            )
        )).scalars().all()
    )
    return needs_check - registered


class MPackGCResult(TypedDict):
    skipped: bool
    packs_before: int
    packs_after: int
    consolidated_key: str


async def process_mpack_gc_job(session: AsyncSession, repo_id: str) -> MPackGCResult:
    import msgpack as _mp

    _skipped: MPackGCResult = {
        "skipped": True,
        "packs_before": 0,
        "packs_after": 0,
        "consolidated_key": "",
    }

    repo_oids_q = await session.execute(
        select(MusehubObjectRef.object_id)
        .where(MusehubObjectRef.repo_id == repo_id)
    )
    repo_oid_set = {row[0] for row in repo_oids_q}
    mpack_q = await session.execute(
        select(MusehubMPackIndex.mpack_id)
        .where(MusehubMPackIndex.entity_id.in_(list(repo_oid_set)))
        .where(MusehubMPackIndex.entity_type == "object")
        .distinct()
    )
    mpack_ids = [row[0] for row in mpack_q]
    packs_before = len(mpack_ids)

    if packs_before <= 1:
        _skipped["packs_before"] = packs_before
        if mpack_ids:
            _skipped["consolidated_key"] = mpack_ids[0]
        return _skipped

    import musehub.storage.backends as _backends_mod
    backend = _backends_mod.get_backend()

    merged_objects: dict[str, bytes] = {}

    async def _download(pid: str) -> None:
        raw = await backend.get_mpack(pid)
        if not raw:
            logger.warning("[mpack_gc] mpack not found in storage: %s", pid)
            return
        if raw[:4] == b"MUSE":
            from muse.core.mpack import parse_wire_mpack as _parse_gc
            _parsed = _parse_gc(raw)
        else:
            _parsed = _mp.unpackb(raw, raw=False)
        for obj in _parsed.get("blobs", []):
            oid = obj.get("object_id", "")
            content = obj.get("content", b"")
            if oid and oid not in merged_objects:
                merged_objects[oid] = content

    await asyncio.gather(*(_download(pid) for pid in mpack_ids))

    from muse.core.mpack import build_wire_mpack as _build_gc_mpack
    consolidated_bytes = _build_gc_mpack({
        "commits": [],
        "snapshots": [],
        "blobs": [
            {"object_id": oid, "content": merged_objects[oid]}
            for oid in sorted(merged_objects)
        ],
        "tags": [],
    })
    consolidated_key = "sha256:" + hashlib.sha256(consolidated_bytes).hexdigest()

    await backend.put_mpack(consolidated_key, consolidated_bytes)

    old_mpack_ids = [p for p in mpack_ids if p != consolidated_key]
    if old_mpack_ids:
        from sqlalchemy import delete as sa_delete
        await session.execute(
            sa_delete(MusehubMPackIndex)
            .where(MusehubMPackIndex.mpack_id.in_(old_mpack_ids))
            .where(MusehubMPackIndex.entity_type == "object")
        )
    _gc_now = datetime.now(timezone.utc)
    new_rows = [
        {
            "entity_id": oid,
            "mpack_id": consolidated_key,
            "entity_type": "object",
            "created_at": _gc_now,
        }
        for oid in merged_objects
    ]
    if new_rows:
        _GC_MIDX_CHUNK = 5000
        for _gmi in range(0, len(new_rows), _GC_MIDX_CHUNK):
            await session.execute(
                _pg_insert(MusehubMPackIndex)
                .values(new_rows[_gmi : _gmi + _GC_MIDX_CHUNK])
                .on_conflict_do_nothing(index_elements=["entity_id", "mpack_id"])
            )

    logger.info(
        "[mpack_gc] repo=%s consolidated %d mpacks → 1 (objects=%d key=%s)",
        repo_id, packs_before, len(merged_objects), consolidated_key,
    )

    return {
        "skipped": False,
        "packs_before": packs_before,
        "packs_after": 1,
        "consolidated_key": consolidated_key,
    }


class FetchResult(TypedDict):
    mpack_id:     str
    mpack_url:    str | None
    commit_count: int
    blob_count: int


class FetchMPackPrebuildResult(TypedDict):
    tips_requested: int
    tips_built: int
    tips_skipped: int
    elapsed_ms: float


async def process_fetch_mpack_prebuild_job(
    session: AsyncSession,
    job_id: str,
) -> FetchMPackPrebuildResult:
    """Build and cache a fetch mpack for every current branch tip.

    Called by the background worker after every push.  Reads branch tips from
    ``MusehubBranch`` at run time (authoritative — not from the payload) so the
    job is self-coalescing: any number of pushes deduped into one pending job are
    all covered because we read live state here.  ``payload["tip_commit_ids"]``
    is retained only for observability and is never used as the source of truth.

    For each live tip, checks whether a fresh cache entry already exists in
    ``musehub_fetch_mpack_cache``; skips tips that are cached and builds the
    rest in one combined call to ``wire_fetch_mpack``.  The returned mpack_id is
    written (or upserted) for every live tip so the multi-tip clone cache-hit
    check (``len(mpack_ids)==1``) fires on the next clone.
    """
    from datetime import timedelta

    from musehub.db.musehub_jobs_models import MusehubBackgroundJob
    from sqlalchemy.dialects.postgresql import insert as _upsert

    _t0 = _time_module.monotonic()

    def _ms() -> float:
        return (_time_module.monotonic() - _t0) * 1000

    job_row = (await session.execute(
        select(MusehubBackgroundJob).where(MusehubBackgroundJob.job_id == job_id)
    )).scalar_one_or_none()
    if job_row is None:
        raise ValueError(f"fetch.mpack.prebuild job not found: {job_id}")

    repo_id: str = job_row.repo_id
    payload = job_row.payload or {}

    # Re-read branch tips from the DB at run time — authoritative, not the
    # captured payload.  This makes the job self-coalescing: any number of
    # pushes deduped into one pending job are all covered because we read
    # live state here rather than whatever was current at enqueue time.
    branch_tips_q = await session.execute(
        select(MusehubBranch.head_commit_id)
        .where(MusehubBranch.repo_id == repo_id)
        .where(MusehubBranch.head_commit_id.isnot(None))
    )
    tip_commit_ids: list[str] = [str(row[0]) for row in branch_tips_q]

    # payload["tip_commit_ids"] is retained for observability only — log if stale.
    _payload_tips = [str(t) for t in (payload.get("tip_commit_ids") or [])]
    if set(_payload_tips) != set(tip_commit_ids):
        logger.info(
            "[fetch.mpack.prebuild] job=%s payload tips=%d differ from live tips=%d "
            "(coalesced pushes) — using live tips",
            job_id[:16], len(_payload_tips), len(tip_commit_ids),
        )

    if not tip_commit_ids:
        logger.warning("[fetch.mpack.prebuild] job=%s repo=%s no branch tips in DB", job_id[:16], repo_id)
        return {"tips_requested": 0, "tips_built": 0, "tips_skipped": 0, "elapsed_ms": 0.0}

    # Find which tips already have a fresh (non-expired) cache entry.
    now = _utc_now()
    cached_q = await session.execute(
        select(MusehubFetchMPackCache.tip_commit_id, MusehubFetchMPackCache.mpack_id)
        .where(MusehubFetchMPackCache.repo_id == repo_id)
        .where(MusehubFetchMPackCache.tip_commit_id.in_(tip_commit_ids))
        .where(MusehubFetchMPackCache.expires_at > now)
    )
    cached_tip_to_mpack: dict[str, str] = {row[0]: row[1] for row in cached_q}
    cached_mpack_ids = set(cached_tip_to_mpack.values())

    # Skip the build only when ALL tips are cached AND they all share one mpack_id.
    # If mpack_ids differ (e.g. main cached from an older build, dev just pushed),
    # we must rebuild with ALL tips so every tip points to the same combined mpack —
    # the clone cache-hit check requires len(mpack_ids) == 1 across all want tips.
    all_tips_same_mpack = (
        len(cached_tip_to_mpack) == len(tip_commit_ids) and len(cached_mpack_ids) == 1
    )
    tips_skipped = len(cached_tip_to_mpack) if all_tips_same_mpack else 0
    tips_to_build = [] if all_tips_same_mpack else tip_commit_ids

    logger.warning(
        "[fetch.mpack.prebuild] job=%s repo=%s tips=%d cached=%d mpack_ids=%d to_build=%d t=%.1fms",
        job_id[:16], repo_id, len(tip_commit_ids), len(cached_tip_to_mpack),
        len(cached_mpack_ids), len(tips_to_build), _ms(),
    )

    tips_built = 0
    if tips_to_build:
        _build_t0 = _time_module.monotonic()
        try:
            # Build ONE combined mpack covering all uncached tips together.
            # wire_fetch_mpack writes a cache row per tip (all pointing to the same
            # mpack_id) so the multi-tip cache check fires on the next clone.
            result = await wire_fetch_mpack(session, repo_id, want=tips_to_build, have=[], force_build=True)
            mpack_id = result.get("mpack_id") or ""
            if not mpack_id:
                logger.warning(
                    "[fetch.mpack.prebuild] combined build produced no mpack_id — skipping cache write",
                )
            else:
                tips_built = len(tips_to_build)
                _build_ms = (_time_module.monotonic() - _build_t0) * 1000
                logger.warning(
                    "[fetch.mpack.prebuild] built tips=%d mpack_id=%s t=%.1fms",
                    tips_built, mpack_id[:20], _build_ms,
                )
                # Explicitly upsert ALL tip cache entries to the new combined mpack_id.
                # wire_fetch_mpack (FMC_11) already upserts the tips it was given, but
                # any tips that were previously cached with a different mpack_id need to
                # be updated here so the clone cache-hit check (len(mpack_ids)==1) passes.
                _expires = _utc_now() + timedelta(days=7)
                for _tip in tip_commit_ids:
                    _cache_id = blob_id((repo_id + _tip).encode()).replace("sha256:", "")
                    await session.execute(
                        _pg_insert(MusehubFetchMPackCache)
                        .values(
                            cache_id=_cache_id,
                            repo_id=repo_id,
                            tip_commit_id=_tip,
                            mpack_id=mpack_id,
                            created_at=_utc_now(),
                            expires_at=_expires,
                        )
                        .on_conflict_do_update(
                            index_elements=["repo_id", "tip_commit_id"],
                            set_={"mpack_id": mpack_id, "expires_at": _expires},
                        )
                    )
        except FetchNotIndexedError:
            logger.warning(
                "[fetch.mpack.prebuild] index gap detected — re-raising for fail_job retry",
            )
            raise
        except Exception as exc:
            logger.error(
                "[fetch.mpack.prebuild] FAILED: %s", exc, exc_info=True,
            )

    total_ms = _ms()
    logger.warning(
        "[fetch.mpack.prebuild] DONE job=%s repo=%s tips=%d built=%d skipped=%d TOTAL=%.1fms",
        job_id[:16], repo_id, len(tip_commit_ids), tips_built, tips_skipped, total_ms,
    )
    return {
        "tips_requested": len(tip_commit_ids),
        "tips_built": tips_built,
        "tips_skipped": tips_skipped,
        "elapsed_ms": total_ms,
    }


class FetchCommitNotFound(Exception):
    """A want commit_id does not exist in musehub_commits."""


class FetchNotReady(Exception):
    """Needed objects are absent from musehub_mpack_index — client must retry."""


async def wire_fetch(
    session: AsyncSession,
    repo_id: str,
    want: list[str],
    have: list[str],
    ttl_seconds: int = 3600,
) -> FetchResult:
    import msgpack as _mp

    _empty: FetchResult = {"mpack_id": "", "mpack_url": None, "commit_count": 0, "blob_count": 0}

    for entry in want:
        if not (isinstance(entry, str) and entry.startswith("sha256:")):
            raise MPackValidationError(f"want entry is not a sha256: id: {entry!r}")

    for entry in have:
        if not (isinstance(entry, str) and entry.startswith("sha256:")):
            raise MPackValidationError(f"have entry is not a sha256: id: {entry!r}")

    if want:
        existing_q = await session.execute(
            select(MusehubCommit.commit_id).where(MusehubCommit.commit_id.in_(want))
        )
        found = {row[0] for row in existing_q}
        missing_want = [cid for cid in want if cid not in found]
        if missing_want:
            raise FetchCommitNotFound(missing_want[0])

    have_set = set(have)
    needed = await _walk_commit_delta(session, want, have_set)
    if not needed:
        return _empty

    cids = list(needed.keys())
    commit_rows: dict[str, MusehubCommit] = {}
    for i in range(0, len(cids), 2000):
        q = await session.execute(
            select(MusehubCommit).where(MusehubCommit.commit_id.in_(cids[i:i + 2000]))
        )
        for row in q.scalars():
            commit_rows[row.commit_id] = row

    want_snap_ids = {r.snapshot_id for r in needed.values() if r.snapshot_id}
    have_snap_ids: set[str] = set()
    if have_set:
        have_commits_q = await session.execute(
            select(MusehubCommit.snapshot_id).where(MusehubCommit.commit_id.in_(list(have_set)))
        )
        have_snap_ids = {row[0] for row in have_commits_q if row[0]}

    new_snap_ids = want_snap_ids - have_snap_ids
    snap_map: dict[str, dict] = {}
    new_oids: set[str] = set()
    backend = get_backend()
    if new_snap_ids:
        snaps_q = await session.execute(
            select(MusehubSnapshot).where(MusehubSnapshot.snapshot_id.in_(list(new_snap_ids)))
        )
        for snap in snaps_q.scalars():
            manifest = (
                _mp.unpackb(snap.manifest_blob, raw=False)
                if snap.manifest_blob
                else await _reconstruct_manifest(session, snap.snapshot_id)
            )
            new_oids.update(v for v in manifest.values() if v)
            snap_map[snap.snapshot_id] = await _snap_row_to_wire_s3(snap, backend, session=session)

    if have_snap_ids:
        have_snaps_q = await session.execute(
            select(MusehubSnapshot).where(MusehubSnapshot.snapshot_id.in_(list(have_snap_ids)))
        )
        for snap in have_snaps_q.scalars():
            m = (
                _mp.unpackb(snap.manifest_blob, raw=False)
                if snap.manifest_blob
                else await _reconstruct_manifest(session, snap.snapshot_id)
            )
            new_oids -= {v for v in m.values() if v}

    if new_oids:
        idx_q = await session.execute(
            select(MusehubMPackIndex.entity_id).where(
                MusehubMPackIndex.entity_id.in_(list(new_oids)),
                MusehubMPackIndex.entity_type == "object",
            )
        )
        indexed = {row[0] for row in idx_q}
        unindexed = new_oids - indexed
        if unindexed:
            raise FetchNotReady(f"{len(unindexed)} object(s) not yet in mpack_index")

    objects: list[dict] = []
    if new_oids:
        obj_q = await session.execute(
            select(MusehubObject).where(MusehubObject.object_id.in_(list(new_oids)))
        )
        for obj_row in obj_q.scalars():
            if obj_row.content_cache is not None:
                content = obj_row.content_cache
            else:
                content = await backend.get(obj_row.object_id) or b""
            objects.append({"object_id": obj_row.object_id, "content": content})

    wire_commits = [_to_wire_commit(r).model_dump() for r in commit_rows.values()]
    from muse.core.mpack import build_wire_mpack as _build_fetch_mpack
    wire_bytes = _build_fetch_mpack({
        "commits":   wire_commits,
        "snapshots": list(snap_map.values()),
        "blobs":     objects,
        "tags":      [],
    })
    mpack_id = blob_id(wire_bytes)

    await backend.put_mpack(mpack_id, wire_bytes)
    mpack_url = await backend.presign_mpack_get(mpack_id, ttl_seconds)

    return {
        "mpack_id":     mpack_id,
        "mpack_url":    mpack_url,
        "commit_count": len(commit_rows),
        "blob_count": len(objects),
    }