Skip to content
zit Artifact [02cdad59a5]
Login

Artifact [02cdad59a5]

Artifact 02cdad59a5b7936bb08372e1bd2c2c3765eca4b36a101be1ccabe1dd45238840:


//! `zit serve`: the HTTP face on the stateless sync responder, and the
//! per-request repository context each served round reads and writes.

const std = @import("std");
const ClientHoldings = zit.sync_session.ClientHoldings;
const File = Io.File;
const Io = std.Io;
const LogIndexStore = zit.log_index_store.LogIndexStore;
const RepoShunSet = zit.log_index_store.RepoShunSet;
const Repository = @import("zit").Repository;
const applySessionErasures = @import("session_erasures.zig").applySessionErasures;
const artifact = zit.artifact;
const cli = @import("zit").cli;
const clusterindex = @import("zit").clusterindex;
const d4OpenLog = @import("sync_test_support.zig").d4OpenLog;
const d4SeedEmptyRepo = @import("sync_test_support.zig").d4SeedEmptyRepo;
const decodeWireName = zit.digest_name.decodeWireName;
const diagnostics = @import("../diagnostics.zig");
const digestToWireName = zit.digest_name.digestToWireName;
const digest_len = zit.digest_name.digest_len;
const erasedBytesHeld = @import("session_erasures.zig").erasedBytesHeld;
const erasureNeedsApplied = @import("session_erasures.zig").erasureNeedsApplied;
const help_pages = @import("../help.zig");
const hexToDigest = zit.digest_name.hexToDigest;
const loadClusterIndex = zit.receive.loadClusterIndex;
const logstore = @import("zit").logstore;
const not_a_repo_msg = diagnostics.not_a_repo_msg;
const openLogAdoptingIndex = zit.log_index_store.openLogAdoptingIndex;
const packSeedDeltaStore = @import("sync_test_support.zig").packSeedDeltaStore;
const persistStore = zit.receive.persistStore;
const persistStoreAdopting = zit.receive.persistStoreAdopting;
const reasonOf = diagnostics.reasonOf;
const repeat = @import("zit").repeat;
const repoReadFail = diagnostics.repoReadFail;
const repoSyncIdentity = zit.sync_session.repoSyncIdentity;
const repo_filename = zit.repo_filename;
const repostate = zit.repostate;
const resolveSettingWith = zit.repo_config.resolveSettingWith;
const s77SeedPolicyRepo = @import("sync_test_support.zig").s77SeedPolicyRepo;
const seedShunnedRepo = @import("sync_test_support.zig").seedShunnedRepo;
const send_shun_digests = @import("sync_test_support.zig").send_shun_digests;
const send_shun_names = @import("sync_test_support.zig").send_shun_names;
const serveAppendFrame = @import("sync_test_support.zig").serveAppendFrame;
const serve_help = help_pages.serve_help;
const serve_mod = @import("../serve.zig");
const shun_test_digest = @import("sync_test_support.zig").shun_test_digest;
const shun_test_held_digest = @import("sync_test_support.zig").shun_test_held_digest;
const shun_test_held_name = @import("sync_test_support.zig").shun_test_held_name;
const shun_test_name = @import("sync_test_support.zig").shun_test_name;
const stateOom = diagnostics.stateOom;
const storage = @import("zit").storage;
const treeManifestBytes = @import("sync_test_support.zig").treeManifestBytes;
const updateConfig = zit.repo_config.updateConfig;
const zit = @import("zit");

/// `zit serve [--port N]` — put an HTTP face on the stateless sync responder.
/// Opens `.zit` read-only and keeps it open for the server's lifetime; every
/// request reads a fresh content view of it and is answered independently
/// (sync §3.8). `std.http`/socket I/O lives entirely in `serve.zig`; this only
/// wires the repository and the listen address.
pub fn runServe(
    gpa: std.mem.Allocator,
    io: std.Io,
    arena: std.mem.Allocator,
    verb_args: []const []const u8,
    streams: cli.Streams,
    /// Carried solely so the served rounds can resolve this server's own
    /// content policy through the shared settings resolver.
    amb: cli.Ambient,
) cli.Exit {
    const parsed = switch (cli.parseServeArgs(verb_args)) {
        .ok => |p| p,
        .unknown_option => |tok| return cli.usageError(streams, "serve", .unknown_option, tok),
        .extra_argument => |tok| return cli.usageError(streams, "serve", .extra_argument, tok),
        .bad_port => |tok| {
            streams.err.print("zit serve: invalid --port value '{s}'\n", .{tok}) catch {};
            return .usage;
        },
        .bad_horizon_url => |tok| {
            streams.err.print("zit serve: invalid --horizon-url value '{s}': one token, no whitespace or control characters\n", .{tok}) catch {};
            return .usage;
        },
    };
    if (parsed.help) {
        streams.out.writeAll(serve_help) catch {};
        return .ok;
    }

    const root = (cli.discoverRoot(arena, io) catch return stateOom(streams, "serve")) orelse {
        streams.err.writeAll(not_a_repo_msg) catch {};
        return .failure;
    };
    var root_dir = root.dir;
    // serve answers from the STORE: its open handle, its swap-detect
    // stat and its config reads all follow the resolved store root.
    if (cli.storeDirOf(io, root_dir) catch {
        root_dir.close(io);
        return repoReadFail(streams, "serve");
    }) |resolved| {
        root_dir.close(io);
        root_dir = resolved;
    }
    const accepted = zit.import_transaction.capture(io, root_dir) catch {
        root_dir.close(io);
        return repoReadFail(streams, "serve");
    };
    var file = accepted.file;
    defer file.close(io);
    const log_st = accepted.accepted_stat;
    // Bring-up order is load-bearing (rationale in `serve_mod.listen`'s
    // doc): open the listener FIRST — before ANY O(store) work, which here means
    // both the config read below and the prime, each a full-log scan. A client
    // that connects during either queues in the accept backlog instead of being
    // refused, so the readiness window starts at the bind rather than after the
    // scans. Announce "listening" only once the bind has actually succeeded (so
    // it never lies about a listener that failed to come up); the accept loop
    // then arms each connection's deadline on accept. The backlog property this
    // rests on is pinned by serve.zig's "listen opens the accept backlog before
    // serve" test.
    const address = std.Io.net.IpAddress.parse("127.0.0.1", parsed.port) catch {
        streams.err.print("zit serve: invalid --port value '{d}'\n", .{parsed.port}) catch {};
        return .usage;
    };
    var listener = serve_mod.listen(io, address) catch {
        streams.err.print("zit serve: cannot bind 127.0.0.1:{d}\n", .{parsed.port}) catch {};
        return .failure;
    };
    defer listener.deinit(io);
    streams.err.print("zit serve: listening on http://127.0.0.1:{d}/xfer (Ctrl-C to stop)\n", .{parsed.port}) catch {};
    streams.err.flush() catch {};

    var fs = storage.FileStorage.initReadOnly(io, file, log_st.size);
    // Through the log-index sidecar, as the snapshot below opens: this open
    // is for one config read, and a whole-log header walk for it was most of
    // a fresh server's first-request cost on a large store.
    var log = openLogAdoptingIndex(gpa, io, root_dir, fs.storageFile(), .refresh_on_scan) catch |e| {
        root_dir.close(io);
        switch (e) {
            error.OutOfMemory => streams.err.writeAll("zit serve: out of memory\n") catch {},
            else => streams.err.print("zit serve: cannot read repository: {s}\n", .{reasonOf(e)}) catch {},
        }
        return .failure;
    };
    defer log.deinit(gpa);
    defer root_dir.close(io);

    // §9.1/§8.2 — emit the repository's stored project code in the clone
    // reply's `push` card, so a clone learns the shared project identity. A
    // repo predating the stored code, or an unreadable config, falls back to
    // the fixed placeholder (informational; servercode never gates a clone).
    var maybe_cfg: ?logstore.OwnedConfig = log.readConfig(gpa) catch null;
    defer if (maybe_cfg) |*oc| oc.deinit(gpa);
    const project_code: []const u8 = if (maybe_cfg) |oc|
        (if (oc.config.project_code.len > 0) oc.config.project_code else serve_mod.server_projectcode)
    else
        serve_mod.server_projectcode;

    // §9.1 — a real instance identity in the clone reply's `push` card,
    // derived from this checkout's absolute path exactly as init derives the
    // project code (stable, distinct per instance, no ambient RNG). The
    // placeholder constant remains only as the test fixtures' server identity.
    const serve_code = zit.sync.deriveServerCode(&.{root.abs});
    const server = zit.sync.Server{
        .version = serve_mod.server_version,
        .credential = null,
        .read_only = parsed.read_only,
        .adopt_project = parsed.adopt_project,
        .self_servercode = &serve_code,
        .project_code = project_code,
        .horizon_url = parsed.horizon_url,
    };
    var ctx = ServeCtx{ .io = io, .root_dir = root_dir, .file = &file, .diag = streams.err, .server = &server, .amb = amb, .fronted = parsed.fronted };
    defer ctx.deinit();
    const responder = serve_mod.Responder{ .ctx = &ctx, .answerFn = serveAnswer, .maintainFn = ServeCtx.maintain, .fronted = parsed.fronted };

    if (ctx.baseSnapshot(gpa)) |_| {} else |_| return repoReadFail(streams, "serve");
    serve_mod.serve(io, gpa, &listener, responder, .{}) catch |e| switch (e) {
        error.Accept => {
            streams.err.writeAll("zit serve: connection accept failed\n") catch {};
            return .failure;
        },
    };
    return .ok;
}

/// The per-request context threaded into `serve.Responder`: the open log to read
/// a fresh store from, the server identity to answer with, and the injected IO +
/// repository directory used to make pushed content durable (a push request
/// ingests new artifacts into the per-request store, which must be persisted into
/// the served repository's on-disk log — sync §3.3).
pub const ServeCtx = struct {
    io: std.Io,
    root_dir: std.Io.Dir,
    /// The ambient environment, carried only so `resolveSetting` (the one
    /// settings resolver) is reachable per round. Reading the config frame
    /// directly here instead would be a second reader, and the two drifting is
    /// the bug `signingSettings` documents having shipped once already.
    amb: ?cli.Ambient = null,
    /// Behind a trusted front. Turns on the per-round membership
    /// rule and keeps the repository image warm between connections so that
    /// rule reads O(image), not O(store), after a push.
    fronted: bool = false,
    /// The open read handle on the served `.zit`. `respond` re-reads the CURRENT
    /// on-disk log from it (§3.8): a fresh stat fixes the committed end-of-log,
    /// so a check-in appended by a separate `zit commit` while `serve` runs is
    /// advertised on the next request — no restart.
    ///
    /// The handle pins an INODE, not a path. `zit pack` and `zit shun --force`
    /// replace `.zit` by rename, which would leave a held-open handle reading
    /// the replaced inode forever (its fstat never moves again — no cache key
    /// over the handle can detect the swap). `baseSnapshot` therefore stats
    /// the PATH beside the handle each round and REOPENS on an inode change:
    /// the swap is noticed at the next round boundary, so a shun that
    /// rode a generation rewrite stops being served with no restart, while an
    /// in-flight round keeps its consistent pre-swap view. A pointer into
    /// `runServe`'s frame so the reopen and the shutdown close agree on one
    /// current handle.
    file: *File,
    /// Where `serveAnswer` names a failed request, or null to stay silent. The
    /// tests and `driveHttp` leave it unset; `runServe` points it at stderr.
    diag: ?*std.Io.Writer = null,
    server: *const zit.sync.Server,
    /// The most recent snapshot of the on-disk log, reused across requests. A
    /// log-backed INDEX (not a full-container copy): it reads the containers it
    /// serves on demand and holds only the index between rounds. Built from
    /// the long-lived allocator `serve` threads into every answer, so it outlives
    /// the request that built it, and owned here — heap-allocated because it owns
    /// the `FileStorage` its log borrows; `dropSnapshot` frees it. Never handed to
    /// `respond` directly — see `serveAnswer`.
    snapshot: ?*LogIndexStore = null,
    /// The served store's structural graph (`structgraph.Graph`), read once
    /// and extended by the frames each rebuilt snapshot adds, so a horizon
    /// classification for ANY cone is a walk over arrays, never a re-read of
    /// the store. Built on the first horizon request, kept across snapshots.
    graph: ?zit.structgraph.Graph = null,
    /// The allocator the graph (and every snapshot) was built with.
    graph_gpa: ?std.mem.Allocator = null,
    /// The snapshot's cluster index, rebuilt with it.
    clusters: ?clusterindex.Resolved = null,
    /// The log size `snapshot` was built from — one half of the cache key that
    /// `baseSnapshot` stats per request (see there for why size alone is not it).
    snapshot_log_size: u64 = 0,
    /// The log's last-modification time (ns) when `snapshot` was built. Together
    /// with the size it is the cache key: a write that does not change the length
    /// still moves `mtime`. A `std.Io.Timestamp`, unwrapped to its `nanoseconds`
    /// here so the key is two scalar comparisons.
    snapshot_log_mtime_ns: i96 = 0,
    /// How many snapshots this server has built. Not used by the server; it is
    /// the observable that makes "snapshot builds do not grow with the round
    /// count" a testable property rather than a wall-clock claim.
    loads: u64 = 0,
    /// The repository the round resolvers read branches, tags, merge bases
    /// and seeds from, kept across rounds while the snapshot's log key is
    /// unchanged. Opening validates and maps the whole image sidecar, which a
    /// multi-round clone of a large store otherwise paid every round. Heap
    /// allocated with `round_repo_gpa`: an open `Repository` is not moved.
    round_repo: ?*Repository = null,
    round_repo_gpa: ?std.mem.Allocator = null,
    /// The snapshot key `round_repo` was opened under.
    round_repo_log_size: u64 = 0,
    round_repo_log_mtime_ns: i96 = 0,
    /// How many times `roundRepo` opened the repository; the observable that
    /// keeps "opens do not grow with the round count" testable.
    repo_opens: u64 = 0,

    /// Free the cached snapshot, leaving the context usable: the next
    /// `baseSnapshot` rebuilds. Both a caller finishing with the context and the
    /// rebuild path itself want exactly this.
    /// Teardown: the snapshot and the graph that outlived its rebuilds.
    pub fn deinit(self: *ServeCtx) void {
        self.dropSnapshot();
        self.dropRoundRepo();
        if (self.graph) |*g| g.deinit(self.graph_gpa.?);
        self.graph = null;
    }

    fn dropRoundRepo(self: *ServeCtx) void {
        if (self.round_repo) |r| {
            r.deinit(self.round_repo_gpa.?);
            self.round_repo_gpa.?.destroy(r);
        }
        self.round_repo = null;
        self.round_repo_gpa = null;
    }

    /// The repository for this round, reopened only when the snapshot's log
    /// key moved since it was opened (a push, a commit beside `serve`, or a
    /// generation swap, which `dropSnapshot` zeroes the key for).
    fn roundRepo(self: *ServeCtx, gpa: std.mem.Allocator) !*Repository {
        if (self.round_repo) |r| {
            if (self.snapshot_log_size != 0 and self.round_repo_log_size == self.snapshot_log_size and
                self.round_repo_log_mtime_ns == self.snapshot_log_mtime_ns) return r;
        }
        self.dropRoundRepo();
        const r = try gpa.create(Repository);
        errdefer gpa.destroy(r);
        try Repository.open(r, gpa, self.io, self.root_dir, .{ .mode = .fast_read });
        self.round_repo = r;
        self.round_repo_gpa = gpa;
        self.round_repo_log_size = self.snapshot_log_size;
        self.round_repo_log_mtime_ns = self.snapshot_log_mtime_ns;
        self.repo_opens += 1;
        return r;
    }

    fn dropSnapshot(self: *ServeCtx) void {
        if (self.clusters) |*c| c.deinit();
        self.clusters = null;
        if (self.snapshot) |s| s.destroy();
        self.snapshot = null;
        self.snapshot_log_size = 0;
        self.snapshot_log_mtime_ns = 0;
    }

    /// Drop plaintext the cached snapshot memoised while answering, keeping the
    /// retained containers it serves from. Called once per round, after every
    /// borrow of the snapshot has ended.
    ///
    /// Inflating is how `content()` answers a wire-backed entry, and the
    /// responder's own §7.2 size proofs call `content()` on every artifact they
    /// emit. Against a throwaway per-request store that plaintext died with the
    /// request; against a store that outlives the request it would accumulate
    /// until the server held the whole repository's uncompressed history. The
    /// containers stay, so the next round answers identically.
    ///
    /// The memo is given up rather than capped because in an optimized build
    /// there is almost nothing to give up: the size proofs are `runtime_safety`
    /// only, so a clone round inflates nothing and the memo would stay empty
    /// regardless. Measured over four clones of a 3001-artifact repository,
    /// ReleaseFast: 12 MB resident and 0.09 s of server CPU with this release,
    /// against 26 MB and 0.15 s without it. A safety-checked build does re-prove
    /// every emitted artifact each round and so pays to re-inflate; that cost
    /// belongs to the proofs, not to the cache.
    fn releaseSnapshotPlaintext(self: *ServeCtx) void {
        if (self.snapshot) |s| s.releaseTransient();
    }

    /// §3.8 — the store describing the CURRENT on-disk log, rebuilt only when the
    /// log has actually grown. The §3.8 guarantee is that a check-in appended by
    /// a separate `zit commit` is advertised on the NEXT request with no restart;
    /// that needs a fresh `stat` per request, not a fresh rebuild per request.
    /// Rebuilding regardless made every round cost the whole repository, which is
    /// what turned a clone of a large store into O(rounds x store) server work.
    ///
    /// A torn tail from an append caught mid-write is rejected by the read-only
    /// scanner exactly as before; the previous snapshot is dropped only once a
    /// replacement is fully built, so a failed rebuild leaves the cache coherent.
    ///
    /// The rebuild itself is O(store) and must therefore not fall inside a
    /// request whose connection carries a deadline. `runServe` primes the cache
    /// before it accepts anything. A round that appends to the log does NOT
    /// rebuild before it returns — it deliberately leaves the snapshot stale
    /// (describing the pre-append log) rather than pay the O(store) rebuild inside
    /// its own reply deadline. The append-only stat gate above makes that
    /// stale snapshot self-correcting: the size no longer matches, so the next
    /// `baseSnapshot` rebuilds. That next call is the accept loop's `maintain`
    /// hook (see `ServeCtx.maintain`), run between connections with no connection
    /// open — so the deferred rebuild still lands outside every connection
    /// deadline, never on an innocent later request. Nothing here can bound the
    /// startup build itself; that is bounded by the store, and always was.
    ///
    /// THE CACHE KEY IS NOT THE SIZE ALONE, and since this snapshot began carrying
    /// the §3.3 shun table it cannot be. A stale snapshot used to cost stale CONTENT
    /// — a peer misses a newly committed artifact and the next round supplies it —
    /// which is self-correcting. It now also decides whether the SUPPRESSION table is
    /// re-read, and a missed re-read serves an artifact the operator shunned, with
    /// nothing failing and nothing logged. "Every writer only appends, so the length
    /// always grows" is true of `zit shun --defer` and `zit commit` today, but it is
    /// an assumption about all present and future writers rather than a checked
    /// property: a generation rewrite landing on the same byte length, or any
    /// out-of-band mutation, would keep the old mask forever. So the key is size AND
    /// mtime — an in-place rewrite that does not change the length still moves the
    /// mtime. Two scalar comparisons against one `stat` this function already
    /// performs, and they can only over-invalidate (which costs a rebuild), never
    /// under-invalidate on a write that reaches THIS INODE.
    ///
    /// Capture a publication-fenced descriptor before consulting the cache.
    /// Its inode detects generation replacement; its fixed bound excludes any
    /// later append. Pending imports fail new requests closed while preserving
    /// the old snapshot for existing borrows. Build the replacement before
    /// closing the descriptor its predecessor owns.
    fn baseSnapshot(self: *ServeCtx, gpa: std.mem.Allocator) serve_mod.AnswerError!repostate.ArtifactStore {
        const accepted = zit.import_transaction.capture(self.io, self.root_dir) catch return error.ServerStorage;
        var adopted = false;
        defer if (!adopted) accepted.close(self.io);
        const st = accepted.accepted_stat;
        const previous = self.file.stat(self.io) catch return error.ServerStorage;
        if (self.snapshot) |s| {
            if (st.inode == previous.inode and st.size == self.snapshot_log_size and
                st.mtime.nanoseconds == self.snapshot_log_mtime_ns) return s.store();
        }

        // Build the fresh index BEFORE dropping the old one: a failed rebuild
        // leaves the previous snapshot (and its size) intact, so the stat gate
        // keeps mismatching until a rebuild succeeds and stale content is never
        // served in the meantime. `openFromFile` fully frees itself on any error.
        const fresh = LogIndexStore.openFromFileIndexed(gpa, self.io, accepted, st.size, self.root_dir) catch |e| switch (e) {
            error.OutOfMemory => return error.OutOfMemory,
            error.Storage, error.Corrupt => return error.ServerStorage,
        };
        self.dropSnapshot();
        self.file.close(self.io);
        self.file.* = accepted.file;
        adopted = true;
        self.snapshot = fresh;
        fresh.classify_sidecar = .{ .io = self.io, .dir = self.root_dir, .graph = &self.graph };
        self.graph_gpa = gpa;
        // Resolve the cluster index over the new snapshot, then drop
        // the cluster plaintext it memoised: the index keeps only names and bits.
        // The cluster scan reads every artifact once and keeps none: the
        // classifier's view, not the memoizing one, so a snapshot build does
        // not pin the store's whole plaintext before the first round.
        self.clusters = loadClusterIndex(gpa, self.io, self.root_dir, &fresh.log, fresh.classifyStore()) catch null;
        fresh.releaseTransient();
        self.snapshot_log_size = st.size;
        self.snapshot_log_mtime_ns = st.mtime.nanoseconds;
        self.loads += 1;
        return fresh.store();
    }

    /// The accept loop's between-connections maintenance hook (see
    /// `serve.Responder.maintainFn`). Runs after a connection has closed and
    /// before the next accept, so no connection is open to charge its O(store)
    /// work to. It re-primes the cache via the same stat-gated `baseSnapshot`:
    /// after a pure read round the stat is unchanged and this is one `stat`; after
    /// a round that appended (a push) the log grew, so this rebuilds the snapshot
    /// the pushing round deliberately left stale rather than pay inside its
    /// deadline. A failed rebuild is swallowed for the same reason
    /// `baseSnapshot` leaves the cache coherent on failure: `baseSnapshot` drops
    /// the old snapshot only after a fresh one is fully built and updates
    /// `snapshot_log_size` only on success, so a failed rebuild RETAINS the
    /// previous (stale) snapshot with its old size — the stat gate keeps
    /// mismatching until a rebuild succeeds, and stale content is never served in
    /// the meantime. The next round (or the next `maintain`) retries, still
    /// outside any earlier round's budget. Type-erased to match the `maintainFn`
    /// seam.
    fn maintain(ctx_ptr: *anyopaque, gpa: std.mem.Allocator) void {
        const self: *ServeCtx = @ptrCast(@alignCast(ctx_ptr));
        // A signed erasure passing its not-before writes nothing, so no stat
        // moves: ask the snapshot's clock. On a flip, reclaim the bytes (the
        // rename then forces the rebuild below) and drop the snapshot either
        // way, so the next round masks what is now erased.
        if (self.snapshot) |snap| if (snap.log.refreshErasureClock()) {
            self.snapshot_log_size = 0;
        };
        const before = self.snapshot_log_size;
        if (self.baseSnapshot(gpa)) |_| {} else |_| {}
        // The reclaim a pushed or flipped erasure calls for runs here, never
        // inside a request: the rewrite is O(store), and between connections
        // no deadline is running. The rename is noticed by the next
        // `baseSnapshot`, which rebuilds over the reclaimed generation.
        if (self.snapshot) |snap| if (erasedBytesHeld(&snap.log) or erasureNeedsApplied(&snap.log)) {
            _ = applySessionErasures(gpa, self.io, self.root_dir, null, "serve", &snap.log, &.{}, true);
            if (self.baseSnapshot(gpa)) |_| {} else |_| {}
        };
        // A push left the zero-parse image stale, and the next
        // protected push would re-derive it inside its own deadline. Derive it
        // here instead, between connections, where O(store) is allowed — and
        // only when the log actually grew, so a pull-heavy fronted server does
        // not pay an image load per connection. Only a fronted server has a
        // resolver to warm; a failure is retried by the round itself, which
        // derives on demand and fails closed on a fault.
        if (self.fronted and self.snapshot_log_size != before) {
            var repo: Repository = undefined;
            if (Repository.open(&repo, gpa, self.io, self.root_dir, .{ .mode = .fast_read })) |_| {
                repo.deinit(gpa);
            } else |_| {}
        }
    }
};

/// The `serve.Responder` seam: snapshot the repository into an in-memory store,
/// answer the framed request over it, and — when the request pushed new content —
/// make that content durable in the served repository's on-disk log (sync §3.3).
///
/// `respond` stays sans-IO: it only `put`s pushed artifacts into the snapshot
/// store it is given. The durable write is this serve-layer's job and reuses the
/// idempotent `persistStore` (a re-push of an already-stored hash appends nothing
/// — content is addressed by hash), the very path clone/pull persist through. A
/// pure gimme/pull request makes nothing new servable, so the overlay stays
/// empty and the log is never reopened; only a genuine push touches disk.
///
/// `respond` is answered over a per-request WRITE OVERLAY of the cached snapshot
/// (`repostate.OverlayStore`), never over the snapshot itself: the responder
/// interns phantoms and upgrades entries as it works, and letting those survive
/// into the next round changes what that round serves. Reads fall through to the
/// snapshot, so reuse costs nothing; writes are confined to the overlay, and the
/// persist pass — which is idempotent over everything already in the log — can
/// only append what the overlay holds.
///
/// The pushed bytes were size-validated by `respond`'s request scan before they
/// entered the store, so `persistStore` only ever writes well-formed content, and
/// a mid-write fault surfaces before `commit`, never as a partial log append.
pub fn serveAnswer(ctx_ptr: *anyopaque, gpa: std.mem.Allocator, request_container: []const u8, cookie: ?[]const u8, front: serve_mod.Front, request_compressed: bool) serve_mod.AnswerError!serve_mod.XferReply {
    const ctx: *ServeCtx = @ptrCast(@alignCast(ctx_ptr));
    return serveAnswerInner(ctx, gpa, request_container, cookie, front, request_compressed) catch |e| {
        // NAME THE FAILURE. `serve.zig` collapses every AnswerError into one
        // bare status -- `ServerStorage`, `OutOfMemory` and `ResponseTooLarge`
        // all become 500 with no body and no log line -- so an operator (or a
        // bench harness) sees "HTTP 500" and has no way to learn which of three
        // unrelated faults produced it. This is the server-side half of naming
        // the status the client now reports; without both ends a 500 is a dead
        // end for anyone diagnosing from the outside.
        //
        // Single funnel on purpose: every `AnswerError` this responder can
        // produce passes through here, so a future cause is reported without a
        // second edit. Diagnostics only -- the error is re-raised unchanged and
        // the status the peer sees does not move.
        if (ctx.diag) |w| {
            w.print("zit serve: request failed: {s}\n", .{@errorName(e)}) catch {};
            w.flush() catch {};
        }
        return e;
    };
}

fn serveAnswerInner(ctx: *ServeCtx, gpa: std.mem.Allocator, request_container: []const u8, cookie: ?[]const u8, front: serve_mod.Front, request_compressed: bool) serve_mod.AnswerError!serve_mod.XferReply {
    const reply = try serveRound(ctx, gpa, request_container, cookie, front, request_compressed);

    // Past this point nothing borrows the snapshot: the overlay is gone with
    // `serveRound`'s frame and the reply owns its own bytes. Dropping the
    // plaintext memo is bounded (it frees only what this round inflated), so it
    // is safe inside the deadline.
    //
    // A round that appended (a push) has left the snapshot stale — it still
    // describes the pre-push log. It is NOT rebuilt here: an O(store) rebuild
    // inside the reply's connection deadline is exactly the failure this avoids. The
    // rebuild is the accept loop's job, via `ServeCtx.maintain`, run after this
    // connection closes and before the next accept — outside every deadline. The
    // append-only stat gate in `baseSnapshot` makes the stale snapshot self-
    // correcting: the next `baseSnapshot` (in `maintain` or the next round) sees
    // the grown size and rebuilds, so no `appended` signal needs to be threaded
    // out of the round.
    //
    // A post-scan read fault this round mapped a held artifact to null. The §8.2
    // clone pager skips such a rid and still reports the sequence complete
    // (NEXT 0), silently finishing a clone MISSING an artifact — a failure the
    // copy-based prime could not produce (a fault surfaced at prime, and a
    // retained-but-uninflatable container was still served verbatim). Read the
    // flag BEFORE releasing the round's memos (which clears it), then surface it
    // as a storage error so the client retries; the next round re-reads.
    const faulted = if (ctx.snapshot) |s| s.read_fault else false;
    ctx.releaseSnapshotPlaintext();
    if (faulted) {
        gpa.free(reply.body);
        if (reply.diverted) |d| gpa.free(d);
        return error.ServerStorage;
    }
    return reply;
}

/// One round over a per-request write overlay. Split out of `serveAnswer` so the
/// overlay — which borrows the cached snapshot — is provably destroyed before
/// `serveAnswer` touches that snapshot's storage. A round that pushes new content
/// persists it durably here; the snapshot it read from is left describing the
/// pre-push log, and `baseSnapshot`'s append-only stat gate rebuilds it on the
/// next call (in the accept loop's `maintain`, never inside this round's
/// deadline), so this round signals nothing back to its caller.
fn serveRound(
    ctx: *ServeCtx,
    gpa: std.mem.Allocator,
    request_container: []const u8,
    cookie: ?[]const u8,
    front: serve_mod.Front,
    request_compressed: bool,
) serve_mod.AnswerError!serve_mod.XferReply {
    var overlay = repostate.OverlayStore.init(gpa, try ctx.baseSnapshot(gpa));
    defer overlay.deinit();

    // sync §3.3 L553-556 / §8.8 L1839-1841 — answer this round with THIS
    // snapshot's shun table. `ctx.server` is the caller's long-lived config and
    // stays const; the per-round copy carries the fields that are properties of
    // the snapshot rather than of the server, so the reply's phantom scan never
    // begs for an artifact this repository has shunned (a client `igot` for a
    // shunned hash still interns its phantom — §3.3 r24(1) L537-540 — it is just
    // never requested).
    // `ctx.baseSnapshot` above published it — the rebuild path assigns
    // `self.snapshot`, the cached path requires it non-null — so the null arm is
    // unreachable today. It is a CHECKED error rather than a fail-open `.none`
    // because "the filter is not skipped" must hold in a release build: a future
    // ctx that primes a store without publishing the snapshot, or an early-out
    // added above, must fail the round rather than silently serve with no shun
    // table and re-beg every shunned hash with nothing failing.
    //
    // submanifests §8.1/§7.2 — the same per-round freshness arms the send gate.
    // The long-lived `ctx.server` is a build identity (version, servercode,
    // project code) and outlives every snapshot; the seen-submanifest indicator,
    // the §8.1 emission setting, and the two settings this server only REPORTS
    // are facts about the CURRENT log and are re-read whenever the snapshot is.
    // Copying per round is what keeps them from drifting: a push that stores this
    // repository's first tree arms the gate for the next round rather than for
    // the next process, and a `zit submanifest enable`/`retune` against a served
    // repository is obeyed by the next round rather than the next process. These
    // read the snapshot unconditionally for the same reason the shun table does —
    // serving a stale default is the failure, not a fallback.
    var round_server = ctx.server.*;
    // sync §3.2/§6.4 — the round's time for the reply's timestamp comment;
    // the sans-IO server has no clock of its own.
    var reply_time_buf: [19]u8 = undefined;
    const now_s: i64 = @intCast(@divFloor(std.Io.Timestamp.now(ctx.io, .real).nanoseconds, std.time.ns_per_s));
    round_server.reply_time = cli.formatWriterTimestamp(now_s, &reply_time_buf);
    const snapshot = ctx.snapshot orelse return error.ServerStorage;
    // The shun table widened by this store's thinned versions, re-read per
    // round like the cone below: the round neither begs a pushing peer for a
    // version `purge artifacts` removed nor stores a copy it sends. Only the
    // admission set widens; the `/shun` rows a peer requests stay the table.
    var thinned_set = ThinnedShunSet.load(gpa, ctx.io, ctx.root_dir, snapshot.shun.shunSet()) catch
        return error.ServerStorage;
    defer thinned_set.deinit(gpa);
    round_server.shun = thinned_set.shunSet();
    // §9.3 r28 — and the row view, for a `reqconfig /shun`.
    round_server.shun_rows = snapshot.shun_rows;
    round_server.setting_rows = snapshot.setting_rows;
    // Sparse-cone RFC section 6.2 -- cone-scoped requests answer filtered.
    round_server.cone_classifier = snapshot.coneClassifier();
    // Horizon draft section 6.2.6 -- the log position this round serves from.
    round_server.horizon_cursor = snapshot.rids.len;
    // Bounded announcement: the clusters carry what they name.
    if (ctx.clusters) |*c| {
        round_server.clustered = &c.clustered;
        round_server.cluster_names = c.cluster_names;
    }
    // This server's own content policy, re-read per round like every
    // other setting here, so `zit settings binary-glob ...` against a served
    // repository is obeyed by the next round rather than the next process.
    //
    // Resolved from the SERVER's settings, never from the artifacts arriving in
    // the push: a push carrying its own policy would otherwise arrive bearing
    // permission to land. The versioned tier is still consulted, and that is
    // deliberate -- it reads the server's own working tree, which a push does
    // not touch, so adopting a project's policy stays an act the operator takes
    // by updating, exactly as `zit trust` is for before-commit consent.
    var policy_arena = std.heap.ArenaAllocator.init(gpa);
    defer policy_arena.deinit();
    if (ctx.amb) |amb| {
        // The repository tier comes from the snapshot's per-build
        // config read, NOT from `resolveSetting`, whose repository read opens
        // the store and re-scans every frame header. That scan per setting
        // per round is what made a 1.17M-artifact clone take half an hour.
        // The snapshot's (size, mtime) key preserves the per-round freshness
        // contract: a settings write grows the log and rebuilds the copy.
        const pa = policy_arena.allocator();
        const repo_bin: ?[]const u8 = if (snapshot.policy_binary_glob.len != 0) snapshot.policy_binary_glob else null;
        const repo_crlf: ?[]const u8 = if (snapshot.policy_crlf_glob.len != 0) snapshot.policy_crlf_glob else null;
        const bin = resolveSettingWith(ctx.io, pa, ctx.root_dir, .{ .environ = amb.environ }, .binary_glob, repo_bin) catch
            zit.settings.Resolved{ .value = "", .source = .default };
        const crlf = resolveSettingWith(ctx.io, pa, ctx.root_dir, .{ .environ = amb.environ }, .crlf_glob, repo_crlf) catch
            zit.settings.Resolved{ .value = "", .source = .default };
        round_server.push_policy = .{ .binary_glob = bin.value, .crlf_glob = crlf.value };
    }
    // Sparse-cone RFC section 5.3 -- a sparse origin refuses clones it does
    // not cover. Read per round like every other snapshot-freshness fact: an
    // `update --cone` against the served tree is obeyed by the next round.
    var origin_cone = zit.repocache.readStoreCone(gpa, ctx.io, ctx.root_dir);
    defer if (origin_cone) |*c| c.deinit(gpa);
    round_server.origin_cone = if (origin_cone) |*c| c else null;
    // sync §7.7 L1463-1467 — the other half of the same admission predicate, from
    // the same snapshot, so `ingest` never pairs this round's shun table with a
    // stale policy.
    round_server.hash_policy = snapshot.hash_policy;
    round_server.seen_submanifest = snapshot.seen_submanifest;
    round_server.submanifests_enabled = snapshot.submanifests_enabled;
    round_server.submanifest_k = snapshot.submanifest_k;
    round_server.submanifest_auto_retune = snapshot.submanifest_auto_retune;
    round_server.git_email_domain = snapshot.git_email_domain;
    if (snapshot.project_code.code()) |code| round_server.project_code = code;
    // The front's membership rule for THIS push, and the resolver it
    // needs. Both set together: a rule with no resolver fails closed in
    // `pushProtectVerdict`, which is the right answer to a misconfiguration but
    // not a state this code should be able to produce. The resolver opens the
    // repository lazily -- a round that pushes nothing protected never pays --
    // and the view it opens reads the on-disk log, which every earlier round
    // already persisted, so a parent pushed last round resolves; a parent in
    // this round is resolved in-round by the rule itself.
    var resolver = RoundBranchResolver{ .ctx = ctx, .gpa = gpa };
    defer resolver.deinit();
    // Horizon draft section 5.2 -- every served repository can mint seeds for a
    // structural request; the resolver opens the repository lazily, so a round
    // that asks for none pays nothing.
    round_server.seed_minter = resolver.seedMinter();
    // The resolver serves every round now, not only a protected one: the
    // seed-derived cancel check and merge-base answers need it, and it opens
    // the repository only when a round actually asks.
    round_server.branch_of = resolver.resolver();
    if (front.protect) |globs| if (globs.len != 0) {
        round_server.push_policy.protect_globs = globs;
    };
    // A divert means nothing without a rule to divert from, so the front's
    // login is read only under one.
    var ledger: ?RefusalLedger = null;
    defer if (ledger) |*l| l.deinit();
    if (front.divert_login) |login| if (round_server.push_policy.protect_globs.len != 0) {
        const now_ms: u64 = @intCast(@divFloor(std.Io.Timestamp.now(ctx.io, .real).nanoseconds, std.time.ns_per_ms));
        ledger = try RefusalLedger.load(gpa, ctx.io, ctx.root_dir, login, now_ms);
        round_server.divert = .{ .login = login, .now_ms = now_ms, .ledger = ledger.?.ledger() };
    };

    var reply = try serve_mod.handleXfer(gpa, &round_server, overlay.store(), request_container, cookie, request_compressed);
    errdefer gpa.free(reply.body);
    defer {
        zit.sync.freeErasures(gpa, reply.erasures);
        gpa.free(reply.erasures);
        reply.erasures = &.{};
    }
    if (ledger) |*l| {
        l.save();
        reply.diverted = try l.header(gpa);
    }
    errdefer if (reply.diverted) |d| gpa.free(d);

    // sync §9.3 r33 — an AUTHORIZED pushed config card's settings, applied to
    // the served repository here because this is where the config lives; the
    // responder is sans-IO and only reports the decision. Unreachable today by
    // construction: `runServe` configures no credential, so `Server.hasAdmin` is
    // false for every requester and every push is rejected (the e2e pins that).
    // It is wired anyway because the alternative — a server that can AUTHORIZE a
    // push and then silently drop it — is the failure mode worth ruling out.
    if (reply.config_apply.any()) {
        updateConfig(gpa, ctx.io, ctx.root_dir, .{
            .enable_submanifests = reply.config_apply.enable,
            .submanifest_k = reply.config_apply.k,
            .submanifest_auto_retune = reply.config_apply.auto_retune,
            .git_email_domain = if (reply.config_apply.git_email_domain) |*d| d.slice() else null,
        }) catch |e| switch (e) {
            error.OutOfMemory => return error.OutOfMemory,
            error.StoreBusy => return error.ServerBusy,
            error.Storage, error.Corrupt => return error.ServerStorage,
        };
    }

    // Only what the round ADDED is persisted, and the walk starts past the
    // snapshot: the base rids already have a durable form, and an upgrade the
    // round retained for one of them (a delta target it reconstructed while
    // serving) is advisory. Walking from rid 1 read every holding once to
    // early-return it -- O(store) after every round that retained anything,
    // 300 s on a 1.25M-entry store, after every structural clone and every
    // push -- and re-wrote each reconstructed form as a new frame, so the store
    // grew by tens of megabytes per clone served.
    if (overlay.added.store().heldCount() > 0) {
        // submanifests §7.1 — the durable half of the push-side duty; the
        // reply-visible half is `sync.ingest`, which phantomizes into the very
        // store the §3.2 walk reads. The gap COUNT is discarded on purpose: a
        // stateless server (§3.8/§8.9) has no operator to report to, and §7.1
        // asks for a phantom, not a diagnostic.
        const stored = persistStoreAdopting(gpa, ctx.io, ctx.root_dir, overlay.store(), null, @intCast(overlay.base_count), reply.adopt_project.code()) catch |e| switch (e) {
            error.OutOfMemory => return error.OutOfMemory,
            error.StoreBusy => return error.ServerBusy,
            error.Storage, error.Corrupt => return error.ServerStorage,
        };
        // sync §8.5 L1688-1689 — another first push adopted the store between
        // this round's read and its write: the reply that accepted this push
        // is replaced by the refusal it now earns.
        if (stored == null) {
            var card_buf: [2 * zit.sync.wrong_project_text.len + 16]u8 = undefined;
            const card = zit.sync.writeSignalCard(.err, zit.sync.wrong_project_text, card_buf[0 .. card_buf.len - 1]);
            card_buf[card.len] = '\n';
            const refusal = zit.container.encode(gpa, card_buf[0 .. card.len + 1], .default) catch |e| switch (e) {
                error.OutOfMemory => return error.OutOfMemory,
                error.InputTooLarge => unreachable,
            };
            gpa.free(reply.body);
            reply.body = refusal;
            reply.content_type = serve_mod.xfer_media_type;
            if (reply.diverted) |d| gpa.free(d);
            reply.diverted = null;
            return reply;
        }
    }
    // Pushed signed erasures the responder verified against this
    // repository's pinned key, recorded after the round's content. Their
    // bytes are reclaimed by `maintain`, between connections.
    if (reply.erasures.len != 0) _ = applySessionErasures(gpa, ctx.io, ctx.root_dir, null, "serve", null, reply.erasures, false);
    return reply;
}

/// The served repository's memory of divert refusals (`sync.DivertLedger`),
/// one line per refusal: `MS LOGIN HASH`, the login fossil-encoded. Loaded
/// for one request's login, written back only when the round added to it,
/// with lines past `refusal_ttl_ms` dropped on the way.
const RefusalLedger = struct {
    gpa: std.mem.Allocator,
    io: std.Io,
    dir: std.Io.Dir,
    now_ms: u64,
    /// The request's login, encoded as it is stored.
    login: []u8,
    /// Every unexpired line, every login's, ready to write back.
    lines: std.ArrayListUnmanaged(u8) = .empty,
    /// This login's refused check-ins.
    mine: std.StringHashMapUnmanaged(void) = .empty,
    added: bool = false,
    moves: std.ArrayListUnmanaged(zit.sync.DivertMove) = .empty,
    arena: std.heap.ArenaAllocator,

    /// How long a refusal counts as the pusher having been told.
    const refusal_ttl_ms: u64 = 7 * 24 * 60 * 60 * 1000;
    /// How far ahead of now a line may be stamped and still count: a clock
    /// stepped back must not make a refusal last forever.
    const refusal_skew_ms: u64 = 24 * 60 * 60 * 1000;
    /// The most lines kept; the oldest go first. A pusher refused this often
    /// in a week is warned again, which is the only cost.
    const refusal_lines_max: usize = 10_000;

    fn load(gpa: std.mem.Allocator, io: std.Io, dir: std.Io.Dir, login: []const u8, now_ms: u64) error{OutOfMemory}!RefusalLedger {
        var self: RefusalLedger = .{ .gpa = gpa, .io = io, .dir = dir, .now_ms = now_ms, .login = undefined, .arena = std.heap.ArenaAllocator.init(gpa) };
        errdefer self.arena.deinit();
        const a = self.arena.allocator();
        const enc = try a.alloc(u8, 2 * login.len);
        self.login = @constCast(zit.artifact.encodeEscapes(login, enc));
        const blob = (try zit.repocache.loadMember(gpa, io, dir, zit.repocache.refusals_member)) orelse return self;
        defer gpa.free(blob);
        // Newest lines are at the end; keep at most the last `refusal_lines_max`.
        var total: usize = std.mem.count(u8, blob, "\n");
        var it = std.mem.splitScalar(u8, blob, '\n');
        while (it.next()) |line| {
            if (total > refusal_lines_max) {
                total -= 1;
                continue;
            }
            var f = std.mem.splitScalar(u8, line, ' ');
            const ms = std.fmt.parseInt(u64, f.next() orelse continue, 10) catch continue;
            const who = f.next() orelse continue;
            const hash = f.next() orelse continue;
            if (f.next() != null) continue;
            if (now_ms -| ms > refusal_ttl_ms or ms -| now_ms > refusal_skew_ms) continue;
            try self.lines.appendSlice(a, line);
            try self.lines.append(a, '\n');
            if (std.mem.eql(u8, who, self.login)) try self.mine.put(a, try a.dupe(u8, hash), {});
        }
        return self;
    }

    fn deinit(self: *RefusalLedger) void {
        self.arena.deinit();
        self.* = undefined;
    }

    fn ledger(self: *RefusalLedger) zit.sync.DivertLedger {
        return .{ .ctx = self, .refusedFn = refused, .recordFn = record, .divertedFn = diverted };
    }

    fn refused(ctx: *anyopaque, hash: []const u8) bool {
        const self: *RefusalLedger = @ptrCast(@alignCast(ctx));
        return self.mine.contains(hash);
    }

    fn record(ctx: *anyopaque, hash: []const u8) error{OutOfMemory}!void {
        const self: *RefusalLedger = @ptrCast(@alignCast(ctx));
        const a = self.arena.allocator();
        try self.lines.print(a, "{d} {s} {s}\n", .{ self.now_ms, self.login, hash });
        try self.mine.put(a, try a.dupe(u8, hash), {});
        self.added = true;
    }

    fn diverted(ctx: *anyopaque, mv: zit.sync.DivertMove) error{OutOfMemory}!void {
        const self: *RefusalLedger = @ptrCast(@alignCast(ctx));
        const a = self.arena.allocator();
        try self.moves.append(a, .{ .hash = try a.dupe(u8, mv.hash), .branch = try a.dupe(u8, mv.branch), .protected = try a.dupe(u8, mv.protected) });
    }

    /// Write back what this round added. Advisory: a lost write costs the
    /// pusher one more refusal.
    fn save(self: *RefusalLedger) void {
        if (self.added) zit.repocache.storeRefusals(self.io, self.dir, self.lines.items);
    }

    /// The `x-zit-diverted` values for this round's moves, one per line
    /// (`serve` sends one header per line), or null. Each field is
    /// fossil-encoded, as on the sync wire, so a branch name carrying a space,
    /// a comma or a newline can neither split a field nor reach the front as
    /// a header of its own.
    fn header(self: *RefusalLedger, gpa: std.mem.Allocator) error{OutOfMemory}!?[]u8 {
        if (self.moves.items.len == 0) return null;
        var out: std.ArrayListUnmanaged(u8) = .empty;
        errdefer out.deinit(gpa);
        for (self.moves.items, 0..) |mv, i| {
            if (i != 0) try out.append(gpa, '\n');
            for ([_][]const u8{ mv.hash, mv.branch, mv.protected }, 0..) |field, k| {
                if (k != 0) try out.append(gpa, ' ');
                const enc = try gpa.alloc(u8, 2 * field.len);
                defer gpa.free(enc);
                try out.appendSlice(gpa, zit.artifact.encodeEscapes(field, enc));
            }
        }
        return try out.toOwnedSlice(gpa);
    }
};

test "serve: the x-zit-diverted value is one fossil-encoded line per move, so no branch name can split it" {
    const gpa = std.testing.allocator;
    var tmp = std.testing.tmpDir(.{});
    defer tmp.cleanup();
    var ledger = try RefusalLedger.load(gpa, std.testing.io, tmp.dir, "jan", 1000);
    defer ledger.deinit();
    const l = ledger.ledger();
    try l.diverted(.{ .hash = "aa", .branch = "attempt/jan/aa", .protected = "release, x\nx-evil: 1" });
    try l.diverted(.{ .hash = "bb", .branch = "attempt/jan/bb", .protected = "trunk" });
    const value = (try ledger.header(gpa)).?;
    defer gpa.free(value);
    try std.testing.expectEqualStrings("aa attempt/jan/aa release,\\sx\\nx-evil:\\s1\nbb attempt/jan/bb trunk", value);
}

test "serve: a refusal record expires after a week, or when stamped too far ahead" {
    const gpa = std.testing.allocator;
    var tmp = std.testing.tmpDir(.{});
    defer tmp.cleanup();
    const day: u64 = 24 * 60 * 60 * 1000;
    const now: u64 = 100 * day;
    {
        var ledger = try RefusalLedger.load(gpa, std.testing.io, tmp.dir, "jan", now);
        defer ledger.deinit();
        try ledger.ledger().record("fresh");
        ledger.save();
    }
    // Rewrite with a stale line and a future one around the fresh one.
    const blob = try std.fmt.allocPrint(gpa, "{d} jan stale\n{d} jan fresh\n{d} jan future\n", .{ now - 8 * day, now, now + 2 * day });
    defer gpa.free(blob);
    zit.repocache.storeRefusals(std.testing.io, tmp.dir, blob);
    var ledger = try RefusalLedger.load(gpa, std.testing.io, tmp.dir, "jan", now);
    defer ledger.deinit();
    const l = ledger.ledger();
    try std.testing.expect(l.refused("fresh"));
    try std.testing.expect(!l.refused("stale"));
    try std.testing.expect(!l.refused("future"));
}

/// `sync.BranchResolver` over the served repository's own view,
/// opened on first use and only for the round. `.fast_read` takes the
/// zero-parse image when it is fresh (`ServeCtx.maintain` keeps it so) and
/// derives when it is not, so the answer is crosslink's own in either case --
/// which is the point: "which branch does this check-in resolve to" has one
/// authority, and this is it, not a re-implementation over raw tags.
/// Horizon draft section 5.2.2 -- a seed's D card in whole seconds: the
/// latest tag event it summarizes, rounded UP, so the seed is never earlier
/// than an event with a sub-second time, and every origin of one repository
/// writes the same D (and so mints the same seed name) for the same state.
fn seedSeconds(latest_ms: u64) u64 {
    return std.math.divCeil(u64, latest_ms, 1000) catch unreachable;
}

test "horizon §5.2.2: a seed is dated at its latest tag event rounded up to a whole second" {
    try std.testing.expectEqual(@as(u64, 0), seedSeconds(0));
    try std.testing.expectEqual(@as(u64, 2), seedSeconds(1001));
    try std.testing.expectEqual(@as(u64, 2), seedSeconds(1999));
    try std.testing.expectEqual(@as(u64, 2), seedSeconds(2000));
}

const RoundBranchResolver = struct {
    ctx: *ServeCtx,
    gpa: std.mem.Allocator,
    /// Borrowed from the serve context, which owns it across rounds.
    repo: *Repository = undefined,
    opened: bool = false,
    failed: bool = false,
    /// Horizon draft section 5.2 -- the seed minted this round, memoized so a
    /// reply that asks twice (igot scan and clone walk both advertise) hashes
    /// once. Owned; freed with the resolver.
    seed_bytes: ?[]u8 = null,
    seed_hash: [64]u8 = undefined,
    seed_hash_len: u8 = 0,
    /// What the memoized seed was minted for: a digest of C and the entries.
    seed_for: [32]u8 = undefined,

    fn resolver(self: *RoundBranchResolver) zit.sync.BranchResolver {
        return .{ .ctx = self, .branchOfFn = branchOf, .mainBranchFn = mainBranch, .tagsOfFn = tagsOf, .mergeBaseFn = mergeBase, .resolveHorizonFn = resolveHorizon };
    }

    /// Horizon draft section 6.2.4 -- Fossil's pivot of `primary` against
    /// `secondaries` over this repository's view, as a hash borrowed from it;
    /// null when they share no ancestor. A check-in this view does not hold
    /// is `Unavailable`: "no common ancestor" would be a claim about history
    /// it cannot see.
    fn mergeBase(ctx_ptr: *anyopaque, gpa: std.mem.Allocator, primary: []const u8, secondaries: []const []const u8) error{ Unavailable, OutOfMemory }!?[]const u8 {
        const self: *RoundBranchResolver = @ptrCast(@alignCast(ctx_ptr));
        const repo = try self.open();
        if (secondaries.len > zit.sync.max_mergebase_secondaries) return error.Unavailable;
        var rids: [zit.sync.max_mergebase_secondaries]repostate.Rid = undefined;
        for (secondaries, rids[0..secondaries.len]) |name, *rid| rid.* = try heldCheckin(repo, name);
        const base = (try repo.pivotOf(gpa, try heldCheckin(repo, primary), rids[0..secondaries.len])) orelse return null;
        return repo.hashOf(base);
    }

    /// Horizon draft section 6.2.7 -- resolved from this origin's own
    /// derivation, as `zit info NAME` would, then DEPTH primary parents back.
    fn resolveHorizon(ctx_ptr: *anyopaque, _: std.mem.Allocator, name: []const u8, depth: u32) error{ Unavailable, OutOfMemory }!?zit.sync.HorizonResolved {
        const self: *RoundBranchResolver = @ptrCast(@alignCast(ctx_ptr));
        const repo = try self.open();
        const pick = repo.view.state.horizonCheckin(name, depth) catch |e| switch (e) {
            error.NotFound => return null,
            error.OutOfMemory => return error.OutOfMemory,
        };
        return .{ .hash = repo.hashOf(pick.rid), .steps = pick.steps };
    }

    fn heldCheckin(repo: *Repository, name: []const u8) error{Unavailable}!repostate.Rid {
        const rid = repo.lookup(name) orelse return error.Unavailable;
        if (!repo.view.state.hasEvent(rid)) return error.Unavailable;
        return rid;
    }

    fn seedMinter(self: *RoundBranchResolver) zit.sync.SeedMinter {
        return .{ .context = self, .mintFn = mintSeed };
    }

    fn deinit(self: *RoundBranchResolver) void {
        if (self.seed_bytes) |b| self.gpa.free(b);
        self.* = undefined;
    }

    /// Horizon draft section 5.2 -- the seed for C: the tag rows in force at C,
    /// and at each check-in of K whose primary parent lies below the horizon
    /// (section 5.2.1), in this repository's own derivation, composed as one
    /// control artifact signed by the serving login. Null when C is not a held
    /// check-in or the repository cannot be opened; the reply then carries no
    /// seed and advertises content (section 6.3).
    fn mintSeed(ctx_ptr: *anyopaque, gpa: std.mem.Allocator, c_hash: []const u8, rule: zit.cone.HorizonRule, entries: []const []const u8) ?zit.sync.Seed {
        const self: *RoundBranchResolver = @ptrCast(@alignCast(ctx_ptr));
        var key: [32]u8 = undefined;
        var hasher = std.crypto.hash.sha2.Sha256.init(.{});
        hasher.update(c_hash);
        hasher.update(rule.name());
        for (entries) |e| {
            hasher.update(" ");
            hasher.update(e);
        }
        hasher.final(&key);
        if (self.seed_bytes != null and std.mem.eql(u8, &self.seed_for, &key)) {
            return .{ .hash = self.seed_hash[0..self.seed_hash_len], .bytes = self.seed_bytes.? };
        }
        const repo = self.open() catch return null;
        const rid = repo.lookup(c_hash) orelse return null;
        if (!repo.view.state.hasEvent(rid)) return null;
        var targets: std.ArrayListUnmanaged(zit.sync.SeedTarget) = .empty;
        defer {
            for (targets.items) |t| gpa.free(t.rows);
            targets.deinit(gpa);
        }
        // Horizon draft section 5.2.2 -- dated at the latest tag event in the
        // repository, cancels included, not at minting: two mints over
        // unchanged state then produce the same bytes and name, so a client's
        // offered name matches and no seed crosses the wire; and no change to
        // tag state moves D earlier, so a clone's D floor never refuses a
        // re-seed. A shun can remove the newest tag rows, so D is also never
        // earlier than the latest D this origin has minted. Entries with no
        // tag rows in force mint no seed at all (`composeSeed` refuses), and
        // the request is served at the content level.
        const floor_ms = zit.repocache.readSeedFloor(gpa, self.ctx.io, self.ctx.root_dir);
        var latest_ms: u64 = @max(floor_ms, repo.view.state.latestTagEvent());
        for ([_][]const []const u8{ &.{c_hash}, entries }) |names| for (names) |name| {
            const r = repo.lookup(name) orelse continue;
            if (!repo.view.state.hasEvent(r)) continue;
            const rows = repo.view.state.tagsOf(gpa, r) catch return null;
            targets.append(gpa, .{ .hash = name, .rows = rows }) catch {
                gpa.free(rows);
                return null;
            };
            for (rows) |row| latest_ms = @max(latest_ms, row.mtime);
        };
        var ts_buf: [19]u8 = undefined;
        const ts = cli.formatWriterTimestamp(@intCast(seedSeconds(latest_ms)), &ts_buf);
        const bytes = zit.sync.composeSeed(gpa, targets.items, .{ .hash = c_hash, .rule = rule }, ts, zit.sync.seed_user) catch return null;
        if (latest_ms > floor_ms) zit.repocache.raiseSeedFloor(gpa, self.ctx.io, self.ctx.root_dir, latest_ms);
        if (self.seed_bytes) |old| self.gpa.free(old);
        self.seed_bytes = bytes;
        const name = artifact.artifactName(.sha3_256, bytes, &self.seed_hash);
        self.seed_hash_len = @intCast(name.len);
        self.seed_for = key;
        return .{ .hash = self.seed_hash[0..self.seed_hash_len], .bytes = bytes };
    }

    /// Open once; a failure is sticky for the round so the rule fails closed
    /// on every question rather than retrying a broken read per artifact.
    fn open(self: *RoundBranchResolver) error{Unavailable}!*Repository {
        if (self.failed) return error.Unavailable;
        if (!self.opened) {
            self.repo = self.ctx.roundRepo(self.gpa) catch {
                self.failed = true;
                return error.Unavailable;
            };
            self.opened = true;
        }
        return self.repo;
    }

    fn branchOf(ctx_ptr: *anyopaque, hash: []const u8) error{Unavailable}!?[]const u8 {
        const self: *RoundBranchResolver = @ptrCast(@alignCast(ctx_ptr));
        const repo = try self.open();
        const rid = repo.lookup(hash) orelse return null;
        // `branchOf` is defined on check-ins; a P card naming a blob (or a
        // phantom) resolves to nothing rather than tripping its precondition.
        if (!repo.view.state.hasEvent(rid)) return null;
        return repo.branchOf(rid);
    }

    fn mainBranch(ctx_ptr: *anyopaque) error{Unavailable}![]const u8 {
        const self: *RoundBranchResolver = @ptrCast(@alignCast(ctx_ptr));
        const repo = try self.open();
        return repo.view.main_branch;
    }

    fn tagsOf(ctx_ptr: *anyopaque, gpa: std.mem.Allocator, hash: []const u8) error{ Unavailable, OutOfMemory }!?[]repostate.RepoState.TagEntry {
        const self: *RoundBranchResolver = @ptrCast(@alignCast(ctx_ptr));
        const repo = try self.open();
        const rid = repo.lookup(hash) orelse return null;
        if (!repo.view.state.hasEvent(rid)) return null;
        return try repo.view.state.tagsOf(gpa, rid);
    }
};

/// Snapshot every stored artifact from the persisted log into `ms`, skipping
/// config frames (not artifacts). A content-bearing frame becomes a held entry;
/// a content-absent frame becomes a phantom — exactly the held/phantom split
/// `respond` walks (sync §3.2/§3.3).
///
/// The log keys frames by the RAW binary digest, but the sync wire names an
/// artifact by that digest's lowercase hex (sync §3.3 — a `file`/`igot`/`gimme`
/// HASH is 40/64 hex characters). The store the responder walks must therefore
/// hold the hex name, or `respond` would emit non-hex bytes that break the
/// peer's card tokenizer. Every hash crossing this boundary is hex-encoded once,
/// here — the single place binary-log identity becomes wire identity.
fn loadContentStore(
    gpa: std.mem.Allocator,
    log: *logstore.LogStore,
    ms: *repostate.MemStore,
) serve_mod.AnswerError!void {
    const rids = log.ridsInPersistedOrder(gpa) catch return error.OutOfMemory;
    defer gpa.free(rids);
    for (rids) |rid| {
        if (log.kindOf(rid) == .config) continue;
        var name_buf: [2 * digest_len]u8 = undefined;
        const name = digestToWireName(log.hashOf(rid), &name_buf);
        // sync §4.1/§7.2 — copy the stored container into the snapshot verbatim
        // so the clone serves it without inflating here and re-compressing at
        // serve. `wire()` is null only for a `.raw` frame or a phantom; those
        // fall back to the plaintext path below. A `.zlib` frame carries the
        // full form; a `.delta` frame carries the stored delta container plus
        // its basis name and reconstructed size (the §7.2 USIZE, delta §3.2).
        var maybe_wire = log.wire(gpa, rid) catch |e| switch (e) {
            error.OutOfMemory => return error.OutOfMemory,
            error.Storage, error.Corrupt => return error.ServerStorage,
        };
        if (maybe_wire) |*w| {
            defer w.deinit(gpa);
            const recorded: bool = switch (w.*) {
                .full => |container| blk: {
                    _ = ms.putWire(name, container) catch return error.OutOfMemory;
                    break :blk true;
                },
                .delta => |d| blk: {
                    // sync §3.3 L553-556 — the delta form is usable only while its
                    // basis is. `zit shun --defer` records the row without
                    // rewriting the generation, so a SURVIVING frame here can be a
                    // delta rooted on a shunned one; that basis reads null through
                    // this loop's own masked doors and interns as a PHANTOM, so
                    // recording the delta would leave an entry the store calls held
                    // (`wire != null`) whose `content()` can never resolve. §3.2's
                    // igot walk would then announce a name no `gimme` can ever be
                    // answered with, and the push would spin the round with nothing
                    // to send. Fall through to the plaintext path instead: the
                    // artifact itself is NOT shunned, so `log.content` reads it
                    // through the frame chain by BYTE OFFSET — which the name-level
                    // mask does not reach — and it is snapshotted as a held full
                    // form. Exactly `LogIndexStore.wireImpl`'s masked-basis guard,
                    // stated for the client's own holdings snapshot.
                    const base = d.baseHash();
                    if (logstore.isCompleteDigest(base.len) and log.isShunned(base)) break :blk false;
                    // The basis frame precedes this one in the log (delta_of <
                    // offset), so it was already inserted at an earlier rid; its
                    // wire name is the hex of the base's binary digest.
                    var src_name_buf: [2 * digest_len]u8 = undefined;
                    const src_name = digestToWireName(base, &src_name_buf);
                    _ = ms.putWireDelta(name, d.container, src_name, d.target_size) catch return error.OutOfMemory;
                    break :blk true;
                },
            };
            if (recorded) continue;
        }
        const maybe = log.content(gpa, rid) catch |e| switch (e) {
            error.OutOfMemory => return error.OutOfMemory,
            error.Storage, error.Corrupt => return error.ServerStorage,
        };
        if (maybe) |bytes| {
            defer gpa.free(bytes);
            _ = ms.store().put(name, bytes) catch return error.OutOfMemory;
        } else {
            _ = ms.store().intern(name) catch return error.OutOfMemory;
        }
    }
}

/// A shun set widened by the thinned list beside the served store.
const ThinnedShunSet = struct {
    base: zit.sync.ShunSet,
    thinned: zit.thinned.Set = .{},

    fn load(gpa: std.mem.Allocator, io: std.Io, dir: std.Io.Dir, base: zit.sync.ShunSet) zit.thinned.Error!ThinnedShunSet {
        return .{ .base = base, .thinned = try zit.thinned.load(gpa, io, dir) };
    }

    fn deinit(self: *ThinnedShunSet, gpa: std.mem.Allocator) void {
        self.thinned.deinit(gpa);
    }

    fn contains(context: *anyopaque, name: []const u8) bool {
        const self: *const ThinnedShunSet = @ptrCast(@alignCast(context));
        return self.base.contains(name) or self.thinned.contains(name);
    }

    fn shunSet(self: *ThinnedShunSet) zit.sync.ShunSet {
        return .{ .context = @ptrCast(self), .vtable = &.{ .contains = contains } };
    }
};

test "serve §3.3: a pushed file card is persisted durably into the served repository's log" {
    const gpa = std.testing.allocator;
    const io = std.testing.io;

    var tmp = std.testing.tmpDir(.{});
    defer tmp.cleanup();

    // A fresh, empty on-disk repository (header only) — the "server" a peer pushes
    // new content into. Built through the real LogStore, not seeded from fossil.
    const hash_kind: u8 = @backingInt(zit.artifact.defaultPolicy(false, false));
    {
        var f = try tmp.dir.createFile(io, repo_filename, .{ .read = true, .exclusive = true });
        defer f.close(io);
        var fs = storage.FileStorage.init(io, f, 0);
        var seed = try logstore.LogStore.open(gpa, fs.storageFile(), hash_kind);
        defer seed.deinit(gpa);
        try seed.commit();
    }

    // A pushed full-content file card for a 64-hex (SHA3-256 width) artifact the
    // server lacks (sync §7.1: `file HASH SIZE\n` + payload; §4.1 zlib container).
    // The name is the artifact's real SHA3-256 (computed by our own hasher, not
    // fossil) so the server's §7.7 commit-hook recompute accepts it.
    const push_body = "pushed artifact bytes\n"; // 22 bytes
    var name_buf: [64]u8 = undefined;
    const push_hash = zit.artifact.artifactName(.sha3_256, push_body, &name_buf);
    const request_plain = try std.fmt.allocPrint(gpa, "pragma client-version 20000\npush sc pc\nfile {s} {d}\n{s}", .{ push_hash, push_body.len, push_body });
    defer gpa.free(request_plain);
    const request = try zit.container.encode(gpa, request_plain, .default);
    defer gpa.free(request);

    var digest_buf: [digest_len]u8 = undefined;
    const push_digest = decodeWireName(push_hash, &digest_buf).?;

    const server = zit.sync.Server{ .version = serve_mod.server_version };

    // Answer the push twice through the real `serve.Responder` seam over a SINGLE
    // open handle (§3.8): the second answer re-reads the current on-disk log from
    // the same handle and sees the first push's frame, so it is an idempotent
    // re-push (content is addressed by hash — no dup frame). A stale startup
    // snapshot would instead re-append the artifact; this handle is never reopened.
    {
        var file = try tmp.dir.openFile(io, repo_filename, .{});
        defer file.close(io);
        var ctx = ServeCtx{ .io = io, .root_dir = tmp.dir, .file = &file, .server = &server };
        defer ctx.deinit();
        for (0..2) |_| {
            const reply = try serveAnswer(&ctx, gpa, request, null, .{}, true);
            gpa.free(reply.body);
        }
    }

    // THE PROOF: re-open the log from disk in a fresh handle; the pushed artifact
    // is present with its exact content — durably stored, not discarded — and
    // appears exactly once (the idempotent re-push added no second frame).
    var file = try tmp.dir.openFile(io, repo_filename, .{});
    defer file.close(io);
    const st = try file.stat(io);
    var fs = storage.FileStorage.init(io, file, st.size);
    var log = try logstore.LogStore.openReadOnly(gpa, fs.storageFile());
    defer log.deinit(gpa);

    const rid = log.lookup(push_digest) orelse return error.PushedArtifactMissing;
    const stored = (try log.content(gpa, rid)).?;
    defer gpa.free(stored);
    try std.testing.expectEqualStrings(push_body, stored);

    const rids = try log.ridsInPersistedOrder(gpa);
    defer gpa.free(rids);
    var artifacts: usize = 0;
    for (rids) |r| {
        if (log.kindOf(r) != .config) artifacts += 1;
    }
    try std.testing.expectEqual(@as(usize, 1), artifacts);
}

test "sync §7.2/§4.1: persistStore stores received full and delta wire forms verbatim; a re-serve preserves the delta container byte-for-byte" {
    const gpa = std.testing.allocator;
    const io = std.testing.io;
    var tmp = std.testing.tmpDir(.{});
    defer tmp.cleanup();
    try d4SeedEmptyRepo(gpa, io, tmp.dir);

    // Model a clone reply in §8.2 RID order: a full base cfile then a delta
    // cfile against it. Names are the real SHA3-256 so the §7.7 hook accepts.
    var ms = repostate.MemStore.init(gpa);
    defer ms.deinit();
    const s = ms.store();
    const base = "the base artifact with a long shared run so the delta stays a compact copy payload distinct in size from the reconstructed target";
    const target = base ++ " plus a small trailing mutation";
    var bn: [64]u8 = undefined;
    var tn: [64]u8 = undefined;
    const base_name = zit.artifact.artifactName(.sha3_256, base, &bn);
    const target_name = zit.artifact.artifactName(.sha3_256, target, &tn);

    const base_container = try zit.container.encode(gpa, base, .default);
    defer gpa.free(base_container);
    const base_rid = try s.put(base_name, base);
    try s.retain(base_rid, .{ .full = base_container });

    const raw = try zit.delta.create(gpa, base, target);
    defer gpa.free(raw);
    const delta_container = try zit.container.encode(gpa, raw, .default);
    defer gpa.free(delta_container);
    const ts = try zit.delta.targetSize(raw);
    const delta_rid = try s.put(target_name, target);
    try s.retain(delta_rid, .{ .delta = .{ .src = base_name, .container = delta_container, .target_size = ts } });

    const written = try persistStore(gpa, io, tmp.dir, ms.store(), null, 0);
    try std.testing.expectEqual(@as(usize, 2), written.written);

    var fs: storage.FileStorage = undefined;
    var log = try d4OpenLog(gpa, io, tmp.dir, &fs);
    defer fs.file.close(io);
    defer log.deinit(gpa);

    // The target persisted as a `.delta` frame that reconstructs to the original.
    var tdig: [digest_len]u8 = undefined;
    const target_digest = decodeWireName(target_name, &tdig).?;
    const trid = log.lookup(target_digest).?;
    try std.testing.expectEqual(logstore.FrameKind.delta, log.kindOf(trid));
    const got = (try log.content(gpa, trid)).?;
    defer gpa.free(got);
    try std.testing.expectEqualStrings(target, got);

    // Clone-of-clone: a re-serve snapshot emits the SAME delta container bytes
    // (§7.2 retransmitted verbatim) — the compactness survives the second hop.
    var serve_ms = repostate.MemStore.init(gpa);
    defer serve_ms.deinit();
    try loadContentStore(gpa, &log, &serve_ms);
    const serve_rid = serve_ms.store().lookup(target_name).?;
    const wf = serve_ms.store().wire(serve_rid).?;
    try std.testing.expect(wf.delta != null);
    try std.testing.expectEqualSlices(u8, delta_container, wf.container);
    try std.testing.expectEqual(@as(u64, target.len), wf.delta.?.target_size);
}

test "submanifests §7.1/§8.1: the S-reference gap survives a RESTART, rebuilt from the durable indicator" {
    // §7.1's phantom is an interned entry with no frame, "exactly as an absent
    // delta source creates a source phantom" — and `LogStore.intern` states the
    // consequence outright: "Phantoms never reach disk." So a restart loses
    // them, and the only thing that can make them correct across one is a
    // REBUILD from the durable content-bearing frames.
    //
    // This test is that invariant for a sweep over the whole store (start_after
    // 0, as a clone or a push ingest persists): run 1 mints the gap, the process
    // ends, run 2 re-derives the identical gap over a store loaded from `.zit`
    // alone. Remove the rebuild (`rescan_persisted`) and run 2 reports ZERO gaps
    // — a repository that quietly declares an unenumerable check-in converged.
    // Sync and pull persist only what arrived; their half is the gap index
    // (`subManifestGaps`) and the e2e "keeps reporting a sub-manifest gap".
    const gpa = std.testing.allocator;
    const io = std.testing.io;
    var tmp = std.testing.tmpDir(.{});
    defer tmp.cleanup();
    try d4SeedEmptyRepo(gpa, io, tmp.dir);

    const leaf_a = "F a.txt " ++ (repeat("1", 64)) ++ "\n";
    const leaf_b = "F b.txt " ++ (repeat("2", 64)) ++ "\n";
    var an: [64]u8 = undefined;
    var bn: [64]u8 = undefined;
    const name_a = zit.artifact.artifactName(.sha3_256, leaf_a, &an);
    const name_b = zit.artifact.artifactName(.sha3_256, leaf_b, &bn);
    const tree = try treeManifestBytes(gpa, &.{ name_a, name_b });
    defer gpa.free(tree);
    var tn: [64]u8 = undefined;
    const tree_name = zit.artifact.artifactName(.sha3_256, tree, &tn);

    // RUN 1 — the tree lands; neither sub-manifest is held.
    {
        var ms = repostate.MemStore.init(gpa);
        defer ms.deinit();
        _ = try ms.store().put(tree_name, tree);
        const first = try persistStore(gpa, io, tmp.dir, ms.store(), null, 0);
        try std.testing.expectEqual(@as(usize, 1), first.written);
        try std.testing.expectEqual(@as(usize, 2), first.submanifest_gaps);
    }

    // RESTART — nothing survives but the bytes in `.zit`.
    var ms2 = repostate.MemStore.init(gpa);
    defer ms2.deinit();
    {
        var fs: storage.FileStorage = undefined;
        var log = try d4OpenLog(gpa, io, tmp.dir, &fs);
        defer fs.file.close(io);
        defer log.deinit(gpa);

        // §8.1 — the indicator IS durable: "record a local seen-submanifest
        // indicator". It is the one byte the rebuild rests on.
        var oc = (try log.readConfig(gpa)) orelse return error.NoConfig;
        defer oc.deinit(gpa);
        try std.testing.expect(oc.config.seen_submanifest);

        // …and the phantoms are NOT durable, asserted rather than assumed —
        // this is the premise the whole rebuild exists to answer.
        var adig: [digest_len]u8 = undefined;
        try std.testing.expect(log.lookup(decodeWireName(name_a, &adig).?) == null);

        // The snapshot a fresh process starts every verb from.
        try loadContentStore(gpa, &log, &ms2);
    }
    // Only the tree came back: the store a second run works from holds no trace
    // of the gap.
    try std.testing.expectEqual(@as(usize, 1), ms2.store().count());

    // RUN 2 — the gap is re-derived, identically, from the durable frames.
    const second = try persistStore(gpa, io, tmp.dir, ms2.store(), null, 0);
    try std.testing.expectEqual(@as(usize, 1), second.written);
    try std.testing.expectEqual(@as(usize, 2), second.submanifest_gaps);
}

test "sync §7.2/§7.4/§3.3: a dangling reverse-delta cfile persists as a verbatim .delta frame that re-serves byte-identically" {
    const gpa = std.testing.allocator;
    const io = std.testing.io;
    var tmp = std.testing.tmpDir(.{});
    defer tmp.cleanup();
    try d4SeedEmptyRepo(gpa, io, tmp.dir);

    // Fossil's clone stream: a reverse delta (the OLDER revision stored as a
    // delta of the NEWER one) arrives BEFORE its basis, so it is dangling. The
    // client retains the §4.1 container through the pending queue and, when the
    // basis lands, persists it as a compact `.delta` — not a full re-compression.
    const newer = "artifact NEWER: a long shared body kept verbatim so the reverse delta reconstructing the older revision stays a compact copy op";
    const older = "artifact NEWER: a long shared body kept verbatim so the reverse delta reconstructing the older revision stays a compact copy op minus tail";
    var nn: [64]u8 = undefined;
    var on: [64]u8 = undefined;
    const newer_name = zit.artifact.artifactName(.sha3_256, newer, &nn);
    const older_name = zit.artifact.artifactName(.sha3_256, older, &on);
    const newer_container = try zit.container.encode(gpa, newer, .default);
    defer gpa.free(newer_container);
    const raw = try zit.delta.create(gpa, newer, older); // OLDER = delta ∘ NEWER
    defer gpa.free(raw);
    const delta_container = try zit.container.encode(gpa, raw, .default);
    defer gpa.free(delta_container);

    var ms = repostate.MemStore.init(gpa);
    defer ms.deinit();
    var client = zit.sync.Client{ .operation = .clone, .state = .clone_round0 };
    defer client.deinit(gpa);

    var body: std.ArrayList(u8) = .empty;
    defer body.deinit(gpa);
    try body.appendSlice(gpa, "clone_seqno 0\npush 1111111111111111 aa87ea41b0bb05ba528f7a3bdba700d7e23d6318\n");
    // Reverse (dangling) order: the delta cfile precedes its basis cfile.
    const dh = try std.fmt.allocPrint(gpa, "cfile {s} {s} {d} {d}\n", .{ older_name, newer_name, older.len, delta_container.len });
    defer gpa.free(dh);
    try body.appendSlice(gpa, dh);
    try body.appendSlice(gpa, delta_container);
    try body.append(gpa, '\n');
    const bh = try std.fmt.allocPrint(gpa, "cfile {s} {d} {d}\n", .{ newer_name, newer.len, newer_container.len });
    defer gpa.free(bh);
    try body.appendSlice(gpa, bh);
    try body.appendSlice(gpa, newer_container);
    try body.append(gpa, '\n');

    _ = try client.consumeReply(gpa, ms.store(), body.items);

    const written = try persistStore(gpa, io, tmp.dir, ms.store(), null, 0);
    try std.testing.expectEqual(@as(usize, 2), written.written);

    var fs: storage.FileStorage = undefined;
    var log = try d4OpenLog(gpa, io, tmp.dir, &fs);
    defer fs.file.close(io);
    defer log.deinit(gpa);

    // §3.3 — the older revision persisted as a `.delta`, not a full re-compression,
    // and reconstructs the original bytes (delta ∘ basis).
    var od: [digest_len]u8 = undefined;
    const older_rid = log.lookup(decodeWireName(older_name, &od).?).?;
    try std.testing.expectEqual(logstore.FrameKind.delta, log.kindOf(older_rid));
    const got = (try log.content(gpa, older_rid)).?;
    defer gpa.free(got);
    try std.testing.expectEqualStrings(older, got);

    // §7.2 — a clone-of-clone re-serve re-emits the SAME delta container byte-for-byte.
    var serve_ms = repostate.MemStore.init(gpa);
    defer serve_ms.deinit();
    try loadContentStore(gpa, &log, &serve_ms);
    const srid = serve_ms.store().lookup(older_name).?;
    const wf = serve_ms.store().wire(srid).?;
    try std.testing.expect(wf.delta != null);
    try std.testing.expectEqualSlices(u8, delta_container, wf.container);
    try std.testing.expectEqualStrings(newer_name, wf.delta.?.src_hash);
}

/// A test-only `storage.StorageFile` that wraps another and tallies the bytes
/// every `pread` actually returned — the instrument for "how many times does a
/// prime read the log?". Every other vtable method delegates verbatim, so a log
/// opened over it behaves identically while its read traffic is measured.
const CountingStorage = struct {
    inner: storage.StorageFile,
    read_bytes: usize = 0,

    fn storageFile(self: *CountingStorage) storage.StorageFile {
        return .{ .context = self, .vtable = &vtable };
    }

    const vtable = storage.StorageFile.VTable{
        .append = appendImpl,
        .pread = preadImpl,
        .sync = syncImpl,
        .size = sizeImpl,
        .truncate = truncateImpl,
        .refresh_end = refreshEndImpl,
    };

    /// One writer by construction, so there is no other writer to exclude.
    fn refreshEndImpl(_: *anyopaque) storage.StorageError!void {}

    fn appendImpl(ctx: *anyopaque, bytes: []const u8) storage.StorageError!void {
        const self: *CountingStorage = @ptrCast(@alignCast(ctx));
        return self.inner.append(bytes);
    }
    fn preadImpl(ctx: *anyopaque, offset: u64, buf: []u8) storage.StorageError!usize {
        const self: *CountingStorage = @ptrCast(@alignCast(ctx));
        const n = try self.inner.pread(offset, buf);
        self.read_bytes += n;
        return n;
    }
    fn syncImpl(ctx: *anyopaque) storage.StorageError!void {
        const self: *CountingStorage = @ptrCast(@alignCast(ctx));
        return self.inner.sync();
    }
    fn sizeImpl(ctx: *anyopaque) storage.StorageError!u64 {
        const self: *CountingStorage = @ptrCast(@alignCast(ctx));
        return self.inner.size();
    }
    fn truncateImpl(ctx: *anyopaque, len: u64) storage.StorageError!void {
        const self: *CountingStorage = @ptrCast(@alignCast(ctx));
        return self.inner.truncate(len);
    }
};

/// Seed a `.zit` under `dir` holding a full+delta+manifest+config mix (via
/// `packSeedDeltaStore`) and return its committed byte size — the fixture the
/// serve-prime read-traffic and index-equivalence tests both build over.
fn seedServeRepo(gpa: std.mem.Allocator, io: std.Io, dir: std.Io.Dir) !u64 {
    const hash_kind: u8 = @backingInt(zit.artifact.defaultPolicy(false, false));
    var f = try dir.createFile(io, repo_filename, .{ .read = true });
    defer f.close(io);
    var fs = storage.FileStorage.init(io, f, 0);
    var log = try logstore.LogStore.open(gpa, fs.storageFile(), hash_kind);
    defer log.deinit(gpa);
    var tip: [64]u8 = undefined;
    try packSeedDeltaStore(gpa, &log, &tip);
    return log.size();
}

test "serve prime reads the served log at most once (no second full-container copy)" {
    const gpa = std.testing.allocator;
    const io = std.testing.io;
    var tmp = std.testing.tmpDir(.{});
    defer tmp.cleanup();

    const file_size = try seedServeRepo(gpa, io, tmp.dir);

    var handle = try tmp.dir.openFile(io, repo_filename, .{});
    defer handle.close(io);
    var fs = storage.FileStorage.init(io, handle, file_size);
    var counting = CountingStorage{ .inner = fs.storageFile() };

    // Build the serve base snapshot over the counting storage and measure how
    // many bytes priming read. `openReadOnly`'s scan already whole-frame-CRC'd
    // every byte once (the warm-start CRC concern); an index prime adds NOTHING on top, so
    // total prime reads stay at roughly one pass over the log. The copy prime
    // (`loadContentStore`) read every container a SECOND time — this bound fails
    // for it, which is exactly the cost the log-offset index removes.
    var index = try LogIndexStore.open(gpa, counting.storageFile());
    defer index.destroy();

    try std.testing.expect(counting.read_bytes <= file_size + file_size / 2);
}

test "log-backed index answers count/hashOf/held/content/wire identically to the MemStore snapshot" {
    const gpa = std.testing.allocator;
    const io = std.testing.io;
    var tmp = std.testing.tmpDir(.{});
    defer tmp.cleanup();

    const file_size = try seedServeRepo(gpa, io, tmp.dir);

    // Reference: the whole-container MemStore snapshot `loadContentStore` builds.
    var ref_handle = try tmp.dir.openFile(io, repo_filename, .{});
    defer ref_handle.close(io);
    var ref_fs = storage.FileStorage.init(io, ref_handle, file_size);
    var ref_log = try logstore.LogStore.openReadOnly(gpa, ref_fs.storageFile());
    defer ref_log.deinit(gpa);
    var ref = repostate.MemStore.init(gpa);
    defer ref.deinit();
    try loadContentStore(gpa, &ref_log, &ref);
    const rs = ref.store();

    // Subject: the log-backed index over the same file.
    var idx_handle = try tmp.dir.openFile(io, repo_filename, .{});
    defer idx_handle.close(io);
    var index = try LogIndexStore.openFromFile(gpa, io, idx_handle, file_size);
    defer index.destroy();
    const is = index.store();

    try std.testing.expectEqual(rs.count(), is.count());
    try std.testing.expect(rs.count() > 0);

    var rid: repostate.Rid = 1;
    while (rid <= rs.count()) : (rid += 1) {
        // Identity, held-ness, and lookup round-trip.
        try std.testing.expectEqualStrings(rs.hashOf(rid), is.hashOf(rid));
        try std.testing.expectEqual(rs.held(rid), is.held(rid));
        try std.testing.expectEqual(@as(?repostate.Rid, rid), is.lookup(rs.hashOf(rid)));

        // Plaintext byte-for-byte.
        const rc = rs.content(rid);
        const ic = is.content(rid);
        try std.testing.expectEqual(rc == null, ic == null);
        if (rc) |rb| try std.testing.expectEqualSlices(u8, rb, ic.?);

        // Wire form: container bytes, and the delta arm's DELTASRC + target size.
        const rw = rs.wire(rid);
        const iw = is.wire(rid);
        try std.testing.expectEqual(rw == null, iw == null);
        if (rw) |rwf| {
            try std.testing.expectEqualSlices(u8, rwf.container, iw.?.container);
            try std.testing.expectEqual(rwf.delta == null, iw.?.delta == null);
            if (rwf.delta) |rd| {
                try std.testing.expectEqualStrings(rd.src_hash, iw.?.delta.?.src_hash);
                try std.testing.expectEqual(rd.target_size, iw.?.delta.?.target_size);
            }
        }
    }
}

test "appendix honours intern/put/retain for hashes the log does not carry" {
    const gpa = std.testing.allocator;
    const io = std.testing.io;
    var tmp = std.testing.tmpDir(.{});
    defer tmp.cleanup();

    const file_size = try seedServeRepo(gpa, io, tmp.dir);
    var handle = try tmp.dir.openFile(io, repo_filename, .{});
    defer handle.close(io);
    var index = try LogIndexStore.openFromFile(gpa, io, handle, file_size);
    defer index.destroy();
    const s = index.store();

    // The serve base is contractually read-only — every write lands in the
    // per-request OverlayStore (ticket constraint 3), so these appendix arms never
    // fire in production. They exist so the store honours the whole ArtifactStore
    // interface instead of trapping on a write; exercise them directly here so that
    // completeness is not dead-untested surface.
    const persisted = s.count();
    try std.testing.expect(persisted > 0);

    // A hash the log cannot hold (all-0xAB digest, hex-named as the wire does).
    var d1: [digest_len]u8 = undefined;
    @memset(&d1, 0xAB);
    var h1_buf: [2 * digest_len]u8 = undefined;
    const h1 = digestToWireName(&d1, &h1_buf);
    try std.testing.expectEqual(@as(?repostate.Rid, null), s.lookup(h1));

    // intern mints an appendix phantom ABOVE the persisted rids: not held (no
    // content yet), count grows by one, identity round-trips, and it is idempotent.
    const r1 = try s.intern(h1);
    try std.testing.expect(r1 > persisted);
    try std.testing.expectEqual(r1, try s.intern(h1));
    try std.testing.expectEqual(@as(?repostate.Rid, r1), s.lookup(h1));
    try std.testing.expectEqualStrings(h1, s.hashOf(r1));
    try std.testing.expect(!s.held(r1));
    try std.testing.expectEqual(@as(?[]const u8, null), s.content(r1));
    try std.testing.expectEqual(persisted + 1, s.count());

    // put upgrades that phantom in place: held flips true, content reads back, and
    // the persisted count is unchanged (an off-log hash never touches the index).
    const body = "off-log body bytes";
    try std.testing.expectEqual(r1, try s.put(h1, body));
    try std.testing.expect(s.held(r1));
    try std.testing.expectEqualSlices(u8, body, s.content(r1).?);
    try std.testing.expectEqual(persisted + 1, s.count());

    // retain on a PERSISTED rid is the advisory no-op (sync §7.2 first-form-wins;
    // the log IS the retained form): it returns without error and ignores ingest.
    try s.retain(1, .{ .full = "ignored — a persisted rid keeps its log form" });

    // None of the appendix traffic left persisted-round memos resident.
    try std.testing.expectEqual(@as(usize, 0), index.residentBytes());
}

test "index materialises only the container a round reads and releases it between rounds" {
    const gpa = std.testing.allocator;
    const io = std.testing.io;
    var tmp = std.testing.tmpDir(.{});
    defer tmp.cleanup();

    const file_size = try seedServeRepo(gpa, io, tmp.dir);
    var handle = try tmp.dir.openFile(io, repo_filename, .{});
    defer handle.close(io);
    var index = try LogIndexStore.openFromFile(gpa, io, handle, file_size);
    defer index.destroy();
    const s = index.store();

    // Right after the prime the index holds ZERO container/plaintext bytes — the
    // whole point: it did not copy the store into RAM.
    try std.testing.expectEqual(@as(usize, 0), index.residentBytes());

    // Find one wire-bearing rid (a zlib/delta frame).
    var target: ?repostate.Rid = null;
    var rid: repostate.Rid = 1;
    while (rid <= s.count()) : (rid += 1) {
        if (s.wire(rid) != null) {
            target = rid;
            break;
        }
    }
    try std.testing.expect(target != null);

    // Reading it materialised only its container; drop the round's memos.
    try std.testing.expect(index.residentBytes() > 0);
    index.releaseTransient();
    try std.testing.expectEqual(@as(usize, 0), index.residentBytes());

    // A single round's residency is EXACTLY the one container it emitted — not
    // the whole store's containers (which the old snapshot held resident).
    const one = s.wire(target.?).?;
    try std.testing.expectEqual(one.container.len, index.residentBytes());
}

/// A test-only `storage.StorageFile` that reads faithfully until `fail_reads` is
/// flipped, then fails every `pread` — the instrument for a fault that strikes
/// AFTER `openReadOnly` has scanned and whole-frame-CRC'd the log, exactly the
/// post-scan bitrot / transient EIO the on-demand serve reads must not swallow
/// silently. Every other method delegates verbatim.
const FaultAfterScanStorage = struct {
    inner: storage.StorageFile,
    fail_reads: bool = false,

    fn storageFile(self: *FaultAfterScanStorage) storage.StorageFile {
        return .{ .context = self, .vtable = &vtable };
    }

    const vtable = storage.StorageFile.VTable{
        .append = appendImpl,
        .pread = preadImpl,
        .sync = syncImpl,
        .size = sizeImpl,
        .truncate = truncateImpl,
        .refresh_end = refreshEndImpl,
    };

    /// One writer by construction, so there is no other writer to exclude.
    fn refreshEndImpl(_: *anyopaque) storage.StorageError!void {}

    fn appendImpl(ctx: *anyopaque, bytes: []const u8) storage.StorageError!void {
        const self: *FaultAfterScanStorage = @ptrCast(@alignCast(ctx));
        return self.inner.append(bytes);
    }
    fn preadImpl(ctx: *anyopaque, offset: u64, buf: []u8) storage.StorageError!usize {
        const self: *FaultAfterScanStorage = @ptrCast(@alignCast(ctx));
        if (self.fail_reads) return error.Io;
        return self.inner.pread(offset, buf);
    }
    fn syncImpl(ctx: *anyopaque) storage.StorageError!void {
        const self: *FaultAfterScanStorage = @ptrCast(@alignCast(ctx));
        return self.inner.sync();
    }
    fn sizeImpl(ctx: *anyopaque) storage.StorageError!u64 {
        const self: *FaultAfterScanStorage = @ptrCast(@alignCast(ctx));
        return self.inner.size();
    }
    fn truncateImpl(ctx: *anyopaque, len: u64) storage.StorageError!void {
        const self: *FaultAfterScanStorage = @ptrCast(@alignCast(ctx));
        return self.inner.truncate(len);
    }
};

test "a post-scan read fault on a held rid is recorded, not silently swallowed" {
    const gpa = std.testing.allocator;
    const io = std.testing.io;
    var tmp = std.testing.tmpDir(.{});
    defer tmp.cleanup();

    const file_size = try seedServeRepo(gpa, io, tmp.dir);
    var handle = try tmp.dir.openFile(io, repo_filename, .{});
    defer handle.close(io);
    var fs = storage.FileStorage.init(io, handle, file_size);
    var faulting = FaultAfterScanStorage{ .inner = fs.storageFile() };

    // Open succeeds: the scan CRCs the whole log BEFORE any fault is armed.
    var index = try LogIndexStore.open(gpa, faulting.storageFile());
    defer index.destroy();
    const s = index.store();

    // From here every on-demand container/plaintext read faults (post-scan EIO).
    faulting.fail_reads = true;

    // Walk the store as the §8.2 clone pager does: a held rid whose wire() AND
    // content() both return null is one the pager silently skips while still
    // reporting the sequence complete — a clone finishing MISSING an artifact.
    var silently_omitted = false;
    var rid: repostate.Rid = 1;
    while (rid <= s.count()) : (rid += 1) {
        if (!s.held(rid)) continue;
        if (s.wire(rid) == null and s.content(rid) == null) silently_omitted = true;
    }

    // The fault genuinely makes a held rid unemittable (the bug's precondition)...
    try std.testing.expect(silently_omitted);
    // ...and the store RECORDED it, so the serve layer can convert the round to an
    // error instead of completing a broken clone. A copy-based prime could not
    // reach this state: a read fault surfaced at prime, not silently at serve.
    try std.testing.expect(index.read_fault);
}

test "serveAnswer converts a recorded read fault into a storage error (no silent short clone)" {
    const gpa = std.testing.allocator;
    const io = std.testing.io;
    var tmp = std.testing.tmpDir(.{});
    defer tmp.cleanup();

    var hex_buf: [2 * digest_len]u8 = undefined;
    try serveSeedRepo(gpa, io, tmp.dir, 4, &hex_buf);

    const server = zit.sync.Server{
        .version = serve_mod.server_version,
        .self_servercode = serve_mod.server_servercode,
        .project_code = serve_mod.server_projectcode,
    };
    var file = try tmp.dir.openFile(io, repo_filename, .{});
    defer file.close(io);
    var ctx = ServeCtx{ .io = io, .root_dir = tmp.dir, .file = &file, .server = &server };
    defer ctx.deinit();

    const clone_plain = try std.fmt.allocPrint(gpa, "pragma client-version 20000\nclone 3 1\n", .{});
    defer gpa.free(clone_plain);
    const clone_req = try zit.container.encode(gpa, clone_plain, .default);
    defer gpa.free(clone_req);

    // A healthy round builds the cached snapshot and completes normally.
    const ok = try serveAnswer(&ctx, gpa, clone_req, null, .{}, true);
    gpa.free(ok.body);

    // Simulate a post-scan read fault having struck THIS round — the test above
    // proves the store records exactly this. serveAnswer MUST refuse to hand back
    // a reply built while an artifact read faulted: otherwise the §8.2 pager's
    // silent skip ships a clone missing an artifact and reports it complete.
    ctx.snapshot.?.read_fault = true;
    try std.testing.expectError(error.ServerStorage, serveAnswer(&ctx, gpa, clone_req, null, .{}, true));

    // The flag is cleared with the round's memos, so an immediately retried round
    // over the now-healthy snapshot succeeds again (a transient fault self-heals).
    const recovered = try serveAnswer(&ctx, gpa, clone_req, null, .{}, true);
    gpa.free(recovered.body);
}

// ---------------------------------------------------------------------------
// `zit serve` must answer one sync round in time bounded by the
// REQUEST, not by the served store. Two per-request costs made a clone
// O(rounds x store): counting held artifacts by forcing a full inflate of every
// artifact, and rebuilding the entire in-memory snapshot from the log on every
// request. The guards below pin both as SCALING properties measured with work
// counters (plaintext bytes materialised, snapshot builds performed) — never
// wall-clock thresholds, which flake and prove nothing about the mechanism.
// ---------------------------------------------------------------------------

/// Seed `ms` with `n` distinct wire-backed artifacts exactly as
/// `loadContentStore` does for a served repository: one §4.1 full container per
/// artifact, with NO plaintext materialised. `ms.plaintextBytesHeld()` is 0 on
/// return, so any later non-zero reading is inflation this store did not ask for.
fn serveSeedWireStore(gpa: std.mem.Allocator, ms: *repostate.MemStore, n: usize) !void {
    var i: usize = 0;
    while (i < n) : (i += 1) {
        var body_buf: [64]u8 = undefined;
        const body = try std.fmt.bufPrint(&body_buf, "issue nine artifact {d}\n", .{i});
        var name_buf: [64]u8 = undefined;
        const name = zit.artifact.artifactName(.sha3_256, body, &name_buf);
        const container = try zit.container.encode(gpa, body, .default);
        defer gpa.free(container);
        _ = try ms.putWire(name, container);
    }
    std.debug.assert(ms.plaintextBytesHeld() == 0);
}

test "serve: the held-artifact count serve uses never materialises plaintext (constant in store size)" {
    const gpa = std.testing.allocator;
    // Two store sizes: the work this count performs must not grow with n. The
    // count VALUE alone would pass before and after the fix — it is the
    // materialised-plaintext reading that observes the defect, so that is what
    // is asserted, at both sizes, as the scaling statement.
    for ([_]usize{ 8, 64 }) |n| {
        var ms = repostate.MemStore.init(gpa);
        defer ms.deinit();
        try serveSeedWireStore(gpa, &ms, n);

        try std.testing.expectEqual(n, ms.store().heldCount());
        try std.testing.expectEqual(@as(usize, 0), ms.plaintextBytesHeld());
    }
}

test "serve: a held artifact whose container does not inflate is still counted as servable" {
    const gpa = std.testing.allocator;
    var ms = repostate.MemStore.init(gpa);
    defer ms.deinit();

    // §4.1 shape (4-byte length prefix) with a payload that is not a valid zlib
    // stream: `held()==true`, `content()==null` — the case `held()`'s contract at
    // repostate.zig names. `respond` retransmits it verbatim and `persistStore`
    // counts it, so serve's own count must agree with them.
    const bogus = "\x00\x00\x00\x0anot-zlib-bytes";
    _ = try ms.putWire(repeat("f", 64), bogus);

    try std.testing.expectEqual(@as(usize, 1), ms.store().heldCount());
    try std.testing.expect(ms.store().held(1));
    try std.testing.expect(ms.store().content(1) == null);
}

/// A §4.1-framed read-only request naming `hash` in a `gimme` card.
fn serveGimmeRequest(gpa: std.mem.Allocator, card: []const u8, hash: []const u8) ![]u8 {
    const plain = try std.fmt.allocPrint(gpa, "pragma client-version 20000\n{s} {s}\n", .{ card, hash });
    defer gpa.free(plain);
    return zit.container.encode(gpa, plain, .default);
}

test "serve publication fence retains the old snapshot and refuses new pending requests" {
    const gpa = std.testing.allocator;
    const io = std.testing.io;
    var tmp = std.testing.tmpDir(.{});
    defer tmp.cleanup();
    try serveAppendFrame(gpa, io, tmp.dir, repeat("a", digest_len), "old content\n");
    const server = zit.sync.Server{ .version = serve_mod.server_version };
    var file = try tmp.dir.openFile(io, repo_filename, .{});
    defer file.close(io);
    var ctx = ServeCtx{ .io = io, .root_dir = tmp.dir, .file = &file, .server = &server };
    defer ctx.dropSnapshot();
    const old = try ctx.baseSnapshot(gpa);
    const old_size = ctx.snapshot.?.fs.end;
    try tmp.dir.createDir(io, zit.import_transaction.pending_name, .default_dir);
    try serveAppendFrame(gpa, io, tmp.dir, repeat("b", digest_len), "prepared content\n");
    try std.testing.expectError(error.ServerStorage, ctx.baseSnapshot(gpa));
    try std.testing.expectEqual(@as(usize, 1), old.count());
    try std.testing.expectEqual(old_size, ctx.snapshot.?.fs.end);
    try ctx.snapshot.?.fs.storageFile().refreshEnd();
    try std.testing.expectEqual(old_size, ctx.snapshot.?.fs.end);
    try tmp.dir.deleteTree(io, zit.import_transaction.pending_name);
    const fresh = try ctx.baseSnapshot(gpa);
    try std.testing.expectEqual(@as(usize, 2), fresh.count());
}

test "serve: repeated rounds over an unchanged log build the snapshot once (constant in round count)" {
    const gpa = std.testing.allocator;
    const io = std.testing.io;
    var tmp = std.testing.tmpDir(.{});
    defer tmp.cleanup();

    const digest_a = repeat("a", digest_len);
    try serveAppendFrame(gpa, io, tmp.dir, digest_a, "content a\n");
    var hex_buf: [2 * digest_len]u8 = undefined;
    const hex_a = digestToWireName(digest_a, &hex_buf);
    const request = try serveGimmeRequest(gpa, "pull sc pc\ngimme", hex_a);
    defer gpa.free(request);

    const server = zit.sync.Server{ .version = serve_mod.server_version };
    var file = try tmp.dir.openFile(io, repo_filename, .{});
    defer file.close(io);
    var ctx = ServeCtx{ .io = io, .root_dir = tmp.dir, .file = &file, .server = &server };
    defer ctx.deinit();

    // Eight rounds, log unchanged: the snapshot is a function of the log, not of
    // the request, so the number of builds must not grow with the round count.
    for (0..8) |_| {
        const reply = try serveAnswer(&ctx, gpa, request, null, .{}, true);
        gpa.free(reply.body);
    }
    try std.testing.expectEqual(@as(u64, 1), ctx.loads);
}

test "serve: rounds over an unchanged log open the repository once, and a grown log reopens it" {
    const gpa = std.testing.allocator;
    const io = std.testing.io;
    var tmp = std.testing.tmpDir(.{});
    defer tmp.cleanup();

    try serveAppendFrame(gpa, io, tmp.dir, repeat("a", digest_len), "content a\n");
    const server = zit.sync.Server{ .version = serve_mod.server_version };
    var file = try tmp.dir.openFile(io, repo_filename, .{});
    defer file.close(io);
    var ctx = ServeCtx{ .io = io, .root_dir = tmp.dir, .file = &file, .server = &server };
    defer ctx.deinit();

    // Opening validates and maps the whole image sidecar, so a multi-round
    // clone that reopened per round paid O(image) every round.
    _ = try ctx.baseSnapshot(gpa);
    const first = try ctx.roundRepo(gpa);
    _ = try ctx.baseSnapshot(gpa);
    const second = try ctx.roundRepo(gpa);
    try std.testing.expect(first == second);
    try std.testing.expectEqual(@as(u64, 1), ctx.repo_opens);

    try serveAppendFrame(gpa, io, tmp.dir, repeat("b", digest_len), "content b\n");
    _ = try ctx.baseSnapshot(gpa);
    _ = try ctx.roundRepo(gpa);
    try std.testing.expectEqual(@as(u64, 2), ctx.repo_opens);
}

test "serve: a responder's phantom interning cannot leak into the next round" {
    const gpa = std.testing.allocator;
    const io = std.testing.io;
    var tmp = std.testing.tmpDir(.{});
    defer tmp.cleanup();

    const digest_a = repeat("a", digest_len);
    try serveAppendFrame(gpa, io, tmp.dir, digest_a, "content a\n");
    var hex_buf: [2 * digest_len]u8 = undefined;
    const hex_a = digestToWireName(digest_a, &hex_buf);

    // §3.3 — an `igot` for a hash the server lacks makes `respond` intern a
    // phantom into whatever store it answers over. That mutation must not
    // survive into the reused snapshot.
    const unknown_hex = repeat("c", (2 * digest_len));
    const igot_req = try serveGimmeRequest(gpa, "pull sc pc\nigot", unknown_hex);
    defer gpa.free(igot_req);
    const gimme_req = try serveGimmeRequest(gpa, "pull sc pc\ngimme", hex_a);
    defer gpa.free(gimme_req);

    const server = zit.sync.Server{ .version = serve_mod.server_version };
    var file = try tmp.dir.openFile(io, repo_filename, .{});
    defer file.close(io);

    // NOTE ON THIS GUARD'S ROLE: it is green against the pre-fix code (which
    // rebuilds per request and so cannot leak) — the round-count guard above is
    // the red one. This guard exists because the obvious WRONG way to satisfy
    // that guard — answer directly over one shared mutable snapshot — passes it
    // and truncates real clones, since the phantoms and memoisations `respond`
    // writes change what later rounds serve. Without this assertion that
    // implementation ships.
    var ctx = ServeCtx{ .io = io, .root_dir = tmp.dir, .file = &file, .server = &server };
    defer ctx.deinit();

    const r1 = try serveAnswer(&ctx, gpa, igot_req, null, .{}, true);
    gpa.free(r1.body);
    const snap = ctx.snapshot.?.store();
    try std.testing.expectEqual(@as(usize, 1), snap.count()); // the one on-disk artifact, nothing more
    try std.testing.expect(snap.lookup(unknown_hex) == null); // the phantom did not land here

    const r2 = try serveAnswer(&ctx, gpa, gimme_req, null, .{}, true);
    defer gpa.free(r2.body);
    try std.testing.expectEqual(@as(u64, 1), ctx.loads); // still one build: the log never changed

    // The reply is byte-identical to the one a server with no prior round produces.
    var fresh_file = try tmp.dir.openFile(io, repo_filename, .{});
    defer fresh_file.close(io);
    var fresh_ctx = ServeCtx{ .io = io, .root_dir = tmp.dir, .file = &fresh_file, .server = &server };
    defer fresh_ctx.deinit();
    const expected = try serveAnswer(&fresh_ctx, gpa, gimme_req, null, .{}, true);
    defer gpa.free(expected.body);
    try std.testing.expectEqualSlices(u8, expected.body, r2.body);
}

test "serve §3.8: a reused snapshot still sees a concurrent commit's append" {
    const gpa = std.testing.allocator;
    const io = std.testing.io;
    var tmp = std.testing.tmpDir(.{});
    defer tmp.cleanup();

    const digest_a = repeat("a", digest_len);
    const digest_b = repeat("b", digest_len);
    try serveAppendFrame(gpa, io, tmp.dir, digest_a, "content a\n");
    var hex_a_buf: [2 * digest_len]u8 = undefined;
    var hex_b_buf: [2 * digest_len]u8 = undefined;
    const hex_a = digestToWireName(digest_a, &hex_a_buf);
    const hex_b = digestToWireName(digest_b, &hex_b_buf);
    const req_a = try serveGimmeRequest(gpa, "pull sc pc\ngimme", hex_a);
    defer gpa.free(req_a);
    const req_b = try serveGimmeRequest(gpa, "pull sc pc\ngimme", hex_b);
    defer gpa.free(req_b);

    const server = zit.sync.Server{ .version = serve_mod.server_version };
    var file = try tmp.dir.openFile(io, repo_filename, .{});
    defer file.close(io);
    var ctx = ServeCtx{ .io = io, .root_dir = tmp.dir, .file = &file, .server = &server };
    defer ctx.deinit();

    const r1 = try serveAnswer(&ctx, gpa, req_a, null, .{}, true);
    gpa.free(r1.body);
    try std.testing.expectEqual(@as(usize, 1), ctx.snapshot.?.store().count());

    // A SEPARATE writer appends while the serve handle stays open.
    try serveAppendFrame(gpa, io, tmp.dir, digest_b, "content b\n");

    const r2 = try serveAnswer(&ctx, gpa, req_b, null, .{}, true);
    gpa.free(r2.body);
    // The log grew, so the snapshot was rebuilt and the new artifact is servable:
    // a cache that never invalidates would still report one artifact and one load.
    try std.testing.expectEqual(@as(u64, 2), ctx.loads);
    try std.testing.expectEqual(@as(usize, 2), ctx.snapshot.?.store().count());
    try std.testing.expect(ctx.snapshot.?.store().lookup(hex_b) != null);
}

/// Seed `dir`'s `.zit` with `n` distinct compressible artifacts, returning the
/// wire (hex) name of the first. Compressible so the log retains a §4.1
/// container per frame — the shape a served repository actually has, and the
/// only shape in which "answering a round does not inflate the store" has
/// anything to say.
fn serveSeedRepo(gpa: std.mem.Allocator, io: std.Io, dir: std.Io.Dir, n: usize, first_hex: *[2 * digest_len]u8) !void {
    const hash_kind: u8 = @backingInt(zit.artifact.defaultPolicy(false, false));
    var f = dir.openFile(io, repo_filename, .{ .mode = .read_write }) catch
        try dir.createFile(io, repo_filename, .{ .read = true });
    defer f.close(io);
    const st = try f.stat(io);
    var fs = storage.FileStorage.init(io, f, st.size);
    var log = try logstore.LogStore.open(gpa, fs.storageFile(), hash_kind);
    defer log.deinit(gpa);
    var i: usize = 0;
    while (i < n) : (i += 1) {
        var body: [512]u8 = undefined;
        @memset(&body, 'a' + @as(u8, @intCast(i % 26)));
        var digest: [digest_len]u8 = undefined;
        @memset(&digest, 0);
        std.mem.writeInt(u64, digest[0..8], i + 1, .big);
        _ = try log.putZlib(&digest, &body);
        if (i == 0) _ = digestToWireName(&digest, first_hex);
    }
    try log.commit();
}

test "serve: answering a round inflates only what the round emits (constant in store size)" {
    const gpa = std.testing.allocator;
    const io = std.testing.io;

    // The same read round against two store sizes. The reply is identical, so
    // the plaintext the server inflates to produce it must be identical too: any
    // dependence on n is the server paying for artifacts the round never names.
    // This is the assertion the whole change exists to make true — the pre-fix
    // held-count walked `content()` over every rid, and so did inflate the store.
    var inflated: [2]usize = undefined;
    for ([_]usize{ 4, 40 }, 0..) |n, k| {
        var tmp = std.testing.tmpDir(.{});
        defer tmp.cleanup();
        var hex_buf: [2 * digest_len]u8 = undefined;
        try serveSeedRepo(gpa, io, tmp.dir, n, &hex_buf);
        const request = try serveGimmeRequest(gpa, "pull sc pc\ngimme", &hex_buf);
        defer gpa.free(request);

        const server = zit.sync.Server{
            .version = serve_mod.server_version,
            .self_servercode = serve_mod.server_servercode,
            .project_code = serve_mod.server_projectcode,
        };
        var file = try tmp.dir.openFile(io, repo_filename, .{});
        defer file.close(io);
        var ctx = ServeCtx{ .io = io, .root_dir = tmp.dir, .file = &file, .server = &server };
        defer ctx.deinit();

        for (0..3) |_| {
            const reply = try serveAnswer(&ctx, gpa, request, null, .{}, true);
            gpa.free(reply.body);
            // Nothing the round materialised is still resident: the cached index
            // reads containers on demand and frees them between rounds, never
            // holding the repository's uncompressed history (or its containers).
            try std.testing.expectEqual(@as(usize, 0), ctx.snapshot.?.residentBytes());
        }
        const emitted = ctx.snapshot.?.materialized_bytes;

        // A CLONE round is the worst case for residency: it emits every artifact
        // and proves each one's declared size against the plaintext, so it
        // legitimately inflates the whole store. What must not survive it is the
        // plaintext — a snapshot that outlives the round would otherwise end up
        // holding the entire repository uncompressed, for the process's life.
        const clone_plain = try std.fmt.allocPrint(gpa, "pragma client-version 20000\nclone 3 1\n", .{});
        defer gpa.free(clone_plain);
        const clone_req = try zit.container.encode(gpa, clone_plain, .default);
        defer gpa.free(clone_req);
        const clone_reply = try serveAnswer(&ctx, gpa, clone_req, null, .{}, true);
        gpa.free(clone_reply.body);
        try std.testing.expectEqual(@as(usize, 0), ctx.snapshot.?.residentBytes());
        try std.testing.expect(ctx.snapshot.?.materialized_bytes >= emitted);
        try std.testing.expectEqual(@as(usize, n), ctx.snapshot.?.store().count());
        inflated[k] = emitted;
    }
    try std.testing.expectEqual(inflated[0], inflated[1]);
    // ... and the constant is the round's own emission, not the store's: a
    // 40-artifact store holds 20480 bytes of plaintext, so an equality that
    // happened to hold at "everything" would still be caught here.
    try std.testing.expect(inflated[1] < 4 * 512);
}

test "serve: the pushing round does not rebuild inside its deadline; maintain rebuilds between connections" {
    const gpa = std.testing.allocator;
    const io = std.testing.io;
    var tmp = std.testing.tmpDir(.{});
    defer tmp.cleanup();

    const hash_kind: u8 = @backingInt(zit.artifact.defaultPolicy(false, false));
    {
        var f = try tmp.dir.createFile(io, repo_filename, .{ .read = true, .exclusive = true });
        defer f.close(io);
        var fs = storage.FileStorage.init(io, f, 0);
        var seed = try logstore.LogStore.open(gpa, fs.storageFile(), hash_kind);
        defer seed.deinit(gpa);
        try seed.commit();
    }

    const push_body = "pushed artifact bytes\n";
    var name_buf: [64]u8 = undefined;
    const push_hash = zit.artifact.artifactName(.sha3_256, push_body, &name_buf);
    const plain = try std.fmt.allocPrint(gpa, "pragma client-version 20000\npush sc pc\nfile {s} {d}\n{s}", .{ push_hash, push_body.len, push_body });
    defer gpa.free(plain);
    const push_req = try zit.container.encode(gpa, plain, .default);
    defer gpa.free(push_req);
    const read_req = try serveGimmeRequest(gpa, "pull sc pc\ngimme", push_hash);
    defer gpa.free(read_req);

    const server = zit.sync.Server{ .version = serve_mod.server_version };
    var file = try tmp.dir.openFile(io, repo_filename, .{});
    defer file.close(io);
    var ctx = ServeCtx{ .io = io, .root_dir = tmp.dir, .file = &file, .server = &server };
    defer ctx.deinit();

    const r0 = try serveAnswer(&ctx, gpa, read_req, null, .{}, true);
    gpa.free(r0.body);
    try std.testing.expectEqual(@as(u64, 1), ctx.loads);

    // The push makes the snapshot stale, but answering it must NOT pay the
    // O(store) rebuild: the reply is written inside a connection deadline, and
    // The failure is exactly the whole-repository rebuild landing inside that
    // budget. The rebuild is deferred to `maintain`, which the accept loop runs
    // after the connection closes — outside every deadline. So the pushing round
    // leaves `loads` untouched.
    const r1 = try serveAnswer(&ctx, gpa, push_req, null, .{}, true);
    gpa.free(r1.body);
    try std.testing.expectEqual(@as(u64, 1), ctx.loads); // no rebuild inside the round
    // The snapshot is momentarily stale — it predates the push — yet the push is
    // already durable on disk: `persistStore` ran inside the round.
    try std.testing.expect(ctx.snapshot != null);
    try std.testing.expect(ctx.snapshot.?.store().lookup(push_hash) == null);

    // The accept loop's post-connection maintenance hook does the O(store)
    // rebuild, between connections, with no connection open to charge it to.
    ServeCtx.maintain(&ctx, gpa);
    try std.testing.expectEqual(@as(u64, 2), ctx.loads);
    try std.testing.expect(ctx.snapshot.?.store().lookup(push_hash) != null);
    // The rebuilt snapshot describes the grown log exactly (the append-only stat
    // gate that `baseSnapshot` already carries).
    const st = try file.stat(io);
    try std.testing.expectEqual(st.size, ctx.snapshot_log_size);

    // A later read round is stat-gated to no rebuild, and still serves the push.
    const r2 = try serveAnswer(&ctx, gpa, read_req, null, .{}, true);
    defer gpa.free(r2.body);
    try std.testing.expectEqual(@as(u64, 2), ctx.loads);
}

const shun_test_letter_name = repeat("ab", digest_len);

test "sync §3.3 L553-556: a repository shun row is a durable wire-name hit, keyed exactly" {
    const gpa = std.testing.allocator;
    const io = std.testing.io;
    var tmp = std.testing.tmpDir(.{});
    defer tmp.cleanup();
    try seedShunnedRepo(gpa, io, tmp.dir);

    var holdings = try ClientHoldings.open(gpa, io, tmp.dir);
    defer holdings.deinit(io);
    const shun = &holdings.index.shun;
    const set = holdings.admission().shun;

    // The complete name is the key: a hit.
    try std.testing.expect(set.contains(shun_test_name));
    // The held artifact is not shunned.
    try std.testing.expect(!set.contains(shun_test_held_name));
    // A 12-hex PREFIX of the shunned name is a DIFFERENT key, not a hit. The
    // lookup never truncates, pads, or prefix-matches — a prefix must not be
    // able to masquerade as a shun-table hit. Nor may an incomplete name reach
    // `LogStore.isShunned`, whose caller contract (src/logstore.zig L1746-1757)
    // binds this boundary: the width check is a CHECKED rejection, not an
    // assert, because an assert is nothing in ReleaseFast and these names come
    // off the wire.
    //
    // These OUT-OF-DOMAIN widths are probed against `containsWireName` directly,
    // not through `zit.sync.ShunSet.contains`: the release-checked rule lives
    // here, in the implementation that owns it, while the wrapper asserts the
    // §3.2 width its own key domain promises. Going through the wrapper would
    // pin the assert instead of the rejection these lines mean to pin.
    try std.testing.expect(!RepoShunSet.containsWireName(shun, shun_test_name[0..12]));
    try std.testing.expect(!RepoShunSet.containsWireName(shun, shun_test_name[0 .. 2 * digest_len - 1])); // odd length
    try std.testing.expect(!RepoShunSet.containsWireName(shun, "")); // empty
    try std.testing.expect(!RepoShunSet.containsWireName(shun, repeat("ab", 48))); // 96 hex — not one of the two forms
    // Correct WIDTH, not hex: in the wrapper's key domain, so probed through it.
    try std.testing.expect(!set.contains(repeat("z", (2 * digest_len)))); // not hex
    // An UPPERCASE spelling of the shunned name decodes to the same digest and
    // so answers TRUE. artifact-format §3.3 L370-377 makes the token invalid but
    // lets an implementation accept it at name validation and fail it at
    // verification; over-suppressing a name that can never verify is the safe
    // direction. Pinned so the fail-closed direction is a decision, not an
    // accident of `hexToBytes` accepting case.
    try std.testing.expect(set.contains(shun_test_letter_name));
    var upper: [2 * digest_len]u8 = undefined;
    for (shun_test_letter_name, 0..) |c, i| upper[i] = std.ascii.toUpper(c);
    try std.testing.expect(!std.mem.eql(u8, &upper, shun_test_letter_name)); // the case really differs
    try std.testing.expect(set.contains(&upper));
}

test "sync §3.3 L553-556: an OOM inside the shun-set load leaves no borrowed key in the owned-key map" {
    const gpa = std.testing.allocator;
    const io = std.testing.io;
    var tmp = std.testing.tmpDir(.{});
    defer tmp.cleanup();
    try seedShunnedRepo(gpa, io, tmp.dir);

    var file = try tmp.dir.openFile(io, repo_filename, .{});
    defer file.close(io);
    const st = try file.stat(io);
    var fs = storage.FileStorage.init(io, file, st.size);
    var log = try logstore.LogStore.openReadOnly(gpa, fs.storageFile());
    defer log.deinit(gpa);
    try std.testing.expect(log.shunList().len >= 2);

    // `load` dupes each row's digest because `shunList` borrows the STORE's own
    // bytes, and the dupe must PRECEDE the insert: insert-then-replace leaves the
    // borrowed slice live as a key on the one error path, after which `deinit`
    // frees the store's digest and `log.deinit` frees it again. A manual sweep
    // (not `checkAllAllocationFailures`) because the obligation is about which
    // POINTER survives the unwind, not just about leaking: the store is
    // allocated from the UNWRAPPED allocator, so a key that is not `load`'s own
    // dupe is freed through the wrap and the double free lands on
    // `testing.allocator`, which catches it. `fail_index` indexes `load`'s
    // allocations alone for the same reason.
    var i: usize = 0;
    while (i < 64) : (i += 1) {
        var fa = std.testing.FailingAllocator.init(gpa, .{ .fail_index = i });
        var shun = RepoShunSet.init(fa.allocator());
        defer shun.deinit();
        if (shun.load(&log)) |_| {
            // The fail point lay at or past the last allocation: no failure was
            // forced, so every allocation site is now covered and the set is
            // whole.
            try std.testing.expect(shun.digests.count() >= 2);
            break;
        } else |e| {
            try std.testing.expectEqual(error.OutOfMemory, e);
        }
    } else return error.SweepNeverCompleted;
}

/// Does the decoded reply body carry `gimme NAME` as a whole card line?
fn replyHasGimme(gpa: std.mem.Allocator, reply_container: []const u8, name: []const u8) !bool {
    const body = try zit.container.decode(gpa, reply_container, @intCast(logstore.max_payload));
    defer gpa.free(body);
    var it = std.mem.splitScalar(u8, body, '\n');
    while (it.next()) |line| {
        if (line.len == 6 + name.len and
            std.mem.startsWith(u8, line, "gimme ") and
            std.mem.eql(u8, line[6..], name)) return true;
    }
    return false;
}

test "sync §3.3 L553-556 / §8.8 L1839-1841: a served reply never gimme's a shunned phantom, and a shun row written between rounds is honoured by the next" {
    const gpa = std.testing.allocator;
    const io = std.testing.io;
    var tmp = std.testing.tmpDir(.{});
    defer tmp.cleanup();

    // A repo holding one artifact and NO shun row yet.
    const hk: u8 = @backingInt(zit.artifact.defaultPolicy(false, false));
    {
        var f = try tmp.dir.createFile(io, repo_filename, .{ .read = true, .exclusive = true });
        defer f.close(io);
        var fs = storage.FileStorage.init(io, f, 0);
        var seed = try logstore.LogStore.open(gpa, fs.storageFile(), hk);
        defer seed.deinit(gpa);
        _ = try seed.put(shun_test_held_digest, "held content\n");
        try seed.commit();
    }

    // A pushing client's `igot` for a hash this repo lacks: §3.3 r24(1)
    // L511-514 makes the server a receiver, so `respond` interns the phantom
    // and would beg for it.
    const igot_req = try serveGimmeRequest(gpa, "pull sc pc\npush sc pc\nigot", shun_test_name);
    defer gpa.free(igot_req);

    const server = zit.sync.Server{ .version = serve_mod.server_version };
    var file = try tmp.dir.openFile(io, repo_filename, .{});
    defer file.close(io);
    var ctx = ServeCtx{ .io = io, .root_dir = tmp.dir, .file = &file, .server = &server };
    defer ctx.deinit();

    // Round 1, no shun row: the reply asks for it. This is the behaviour the
    // filter must change, so the test is red on an unfiltered server.
    {
        const r = try serveAnswer(&ctx, gpa, igot_req, null, .{}, true);
        defer gpa.free(r.body);
        try std.testing.expect(try replyHasGimme(gpa, r.body, shun_test_name));
    }

    // The operator shuns it BETWEEN rounds — an append to the same log.
    {
        var f = try tmp.dir.openFile(io, repo_filename, .{ .mode = .read_write });
        defer f.close(io);
        const st = try f.stat(io);
        var fs = storage.FileStorage.init(io, f, st.size);
        var log = try logstore.LogStore.open(gpa, fs.storageFile(), hk);
        defer log.deinit(gpa);
        try log.putShun(shun_test_digest, "operator request", 1);
        try log.commit();
    }

    // Round 2 honours it with no restart: the append grew the log, so
    // `baseSnapshot`'s stat gate rebuilds the index — and the rebuild re-loads
    // the shun table (`LogIndexStore.shun`). That is the freshness mechanism this
    // set rides; nothing here is memoised past a build.
    {
        const r = try serveAnswer(&ctx, gpa, igot_req, null, .{}, true);
        defer gpa.free(r.body);
        try std.testing.expect(!try replyHasGimme(gpa, r.body, shun_test_name));
        // The unshunned holding is still advertised: only the shunned name went quiet.
        const body = try zit.container.decode(gpa, r.body, @intCast(logstore.max_payload));
        defer gpa.free(body);
        try std.testing.expect(std.mem.indexOf(u8, body, "igot " ++ shun_test_held_name) != null);
    }
    try std.testing.expectEqual(@as(u64, 2), ctx.loads); // one build per log state, not per round
}

/// The FIRST, a MIDDLE and the LAST of the five are shunned, so an off-by-one or
/// a misindexed mask cannot pass: the survivors are interleaved among them.
fn sendShunIsShunned(i: usize) bool {
    return i % 2 == 0;
}

/// Seed `dir`'s repository holding all five `send_shun_digests` in order, with a
/// live config frame BEFORE the first and another BETWEEN the second and third,
/// and shun rows naming the first, middle and last.
///
/// The interleaving is what an off-by-one cannot survive: shunning the FIRST, a
/// MIDDLE and the LAST slot means a mask built by any walk other than the
/// enumeration's own loop names one artifact and suppresses another, and the
/// alignment test below reads that straight off the log. The config frames are
/// here for a WEAKER reason than they look: they never enter
/// `ridsInPersistedOrder` at all (a config frame is not interned — `LogStore.scan`
/// only records its offset), so they exercise the `.config` guards' *presence*, not
/// a live skip; they do not by themselves make a second walk misalign.
fn seedSendShunRepo(gpa: std.mem.Allocator, io: std.Io, dir: std.Io.Dir) !void {
    const hk: u8 = @backingInt(zit.artifact.defaultPolicy(false, false));
    var f = try dir.createFile(io, repo_filename, .{ .read = true, .exclusive = true });
    defer f.close(io);
    var fs = storage.FileStorage.init(io, f, 0);
    var log = try logstore.LogStore.open(gpa, fs.storageFile(), hk);
    defer log.deinit(gpa);
    try log.putConfig(.{ .hash_policy = hk, .default_branch = "trunk", .project_id = "", .project_code = "" });
    _ = try log.put(send_shun_digests[0], "content zero\n");
    _ = try log.put(send_shun_digests[1], "content one\n");
    try log.putConfig(.{ .hash_policy = hk, .default_branch = "trunk", .project_id = "", .project_code = "cccc" });
    _ = try log.put(send_shun_digests[2], "content two\n");
    _ = try log.put(send_shun_digests[3], "content three\n");
    _ = try log.put(send_shun_digests[4], "content four\n");
    for (send_shun_digests, 0..) |d, i| {
        if (sendShunIsShunned(i)) try log.putShun(d, "operator request", 1);
    }
    try log.commit();
}

/// How many of `index`'s slots a lookup of their own name finds: the
/// unmasked ones.
fn resolvableNames(index: *LogIndexStore) usize {
    var found: usize = 0;
    for (0..index.rids.len) |a| {
        if (index.nameRid(index.nameAt(a))) |rid| {
            std.debug.assert(rid == a + 1);
            found += 1;
        }
    }
    return found;
}

test "sync §9.5 L2170-2174: a shunned holding is masked out of the adapter enumeration and its name is absent from by_name" {
    const gpa = std.testing.allocator;
    const io = std.testing.io;
    var tmp = std.testing.tmpDir(.{});
    defer tmp.cleanup();
    try seedSendShunRepo(gpa, io, tmp.dir);

    var file = try tmp.dir.openFile(io, repo_filename, .{});
    defer file.close(io);
    const st = try file.stat(io);
    var index = try LogIndexStore.openFromFile(gpa, io, file, st.size);
    defer index.destroy();
    const s = index.store();

    // §8.2 L1551-1553 — the rid space is the LOG's, not the survivors': all five
    // artifact frames still hold their slot (config frames were never in it).
    try std.testing.expectEqual(@as(usize, 5), index.rids.len);
    try std.testing.expectEqual(@as(usize, 5), s.count());

    for (send_shun_names, 0..) |name, i| {
        const rid: repostate.Rid = @intCast(i + 1);
        if (sendShunIsShunned(i)) {
            // Not resolvable by name: the §3.2 gimme arm keys on `lookup`, so
            // this IS §3.3 L569-572's "If absent, silently skip".
            try std.testing.expect(index.nameRid(name) == null);
            try std.testing.expect(s.lookup(name) == null);
            // Not announced (§3.2's igot walk gates on `held`), and nothing to
            // send in either form.
            try std.testing.expect(!s.held(rid));
            try std.testing.expect(s.content(rid) == null);
            try std.testing.expect(s.wire(rid) == null);
        } else {
            try std.testing.expectEqual(@as(?repostate.Rid, rid), s.lookup(name));
            try std.testing.expect(s.held(rid));
            try std.testing.expect(s.content(rid) != null);
        }
    }
    // A masked frame is a policy gap, never a read fault: the round must not be
    // converted to `error.ServerStorage` by `serveAnswer`.
    try std.testing.expect(!index.read_fault);
}

/// Does the decoded reply body carry `VERB NAME` as a whole card line?
fn replyHasCardFor(body: []const u8, verb: []const u8, name: []const u8) bool {
    var it = std.mem.splitScalar(u8, body, '\n');
    while (it.next()) |line| {
        if (line.len != verb.len + 1 + name.len) continue;
        if (!std.mem.startsWith(u8, line, verb)) continue;
        if (line[verb.len] != ' ') continue;
        if (std.mem.eql(u8, line[verb.len + 1 ..], name)) return true;
    }
    return false;
}

test "sync §9.5 L2170-2174: a served round igot-announces the survivors and never a masked holding" {
    const gpa = std.testing.allocator;
    const io = std.testing.io;
    var tmp = std.testing.tmpDir(.{});
    defer tmp.cleanup();
    try seedSendShunRepo(gpa, io, tmp.dir);

    const server = zit.sync.Server{ .version = serve_mod.server_version };
    var file = try tmp.dir.openFile(io, repo_filename, .{});
    defer file.close(io);
    var ctx = ServeCtx{ .io = io, .root_dir = tmp.dir, .file = &file, .server = &server };
    defer ctx.deinit();

    // A round that makes the server run its §3.2 inventory walk over every rid.
    // The announced hash is one this repo does not hold, so nothing else about
    // the request steers which holdings the walk reaches. The pull names the
    // served project (sync §8.5).
    var pc_buf: [zit.sync.max_projectcode_len]u8 = undefined;
    const identity = try repoSyncIdentity(gpa, io, tmp.dir, "test-fixture-repo", &pc_buf);
    const pull_igot = try std.fmt.allocPrint(gpa, "pull sc {s}\nigot", .{identity.project_code});
    defer gpa.free(pull_igot);
    const req = try serveGimmeRequest(gpa, pull_igot, shun_test_name);
    defer gpa.free(req);
    const reply = try serveAnswer(&ctx, gpa, req, null, .{}, true);
    defer gpa.free(reply.body);
    const body = try zit.container.decode(gpa, reply.body, @intCast(logstore.max_payload));
    defer gpa.free(body);

    for (send_shun_names, 0..) |name, i| {
        if (sendShunIsShunned(i)) {
            // §9.5 L2170-2174 — not among "every eligible holding": the walk's
            // `held()` gate answers false, so no igot names it.
            try std.testing.expect(!replyHasCardFor(body, "igot", name));
            // Nor does it fall out of the walk as a PHANTOM to beg for. The
            // enumeration now hands the walk a non-held rid, and it is `Server.shun`
            // — the §3.3 L553-556 arm this repository's own table feeds through
            // `serveRound` — that keeps the reply quiet. That check is not dead
            // after this slice; the mask is what makes it load-bearing.
            try std.testing.expect(!replyHasCardFor(body, "gimme", name));
        } else {
            try std.testing.expect(replyHasCardFor(body, "igot", name));
        }
    }
    // A masked holding is not an error condition on any card.
    try std.testing.expect(std.mem.indexOf(u8, body, "error") == null);
}

test "sync §9.5 L2170-2174: the masked enumeration stays aligned — adapter rid r names rids[r-1] with shunned first, middle and last" {
    const gpa = std.testing.allocator;
    const io = std.testing.io;
    var tmp = std.testing.tmpDir(.{});
    defer tmp.cleanup();
    try seedSendShunRepo(gpa, io, tmp.dir);

    var file = try tmp.dir.openFile(io, repo_filename, .{});
    defer file.close(io);
    const st = try file.stat(io);
    var index = try LogIndexStore.openFromFile(gpa, io, file, st.size);
    defer index.destroy();
    const s = index.store();

    // `rids`, `names`, `masked`, `content_memo` and `wire_memo` are PARALLEL
    // arrays and `by_name` maps a wire name to that same index. Filtering or
    // masking one out of step with the others makes adapter rid r name a
    // DIFFERENT artifact's bytes — silent corruption on the wire, not an error.
    // Pin the whole alignment against the log itself, entry by entry.
    var shunned_seen: usize = 0;
    for (index.rids, 0..) |lr, a| {
        var buf: [2 * digest_len]u8 = undefined;
        const expect_name = digestToWireName(index.log.hashOf(lr), &buf);
        const rid: repostate.Rid = @intCast(a + 1);
        try std.testing.expectEqualStrings(expect_name, index.nameAt(a));
        try std.testing.expectEqualStrings(expect_name, s.hashOf(rid));
        try std.testing.expectEqualStrings(send_shun_names[a], expect_name);
        // The mask indexes the SAME slot as `rids[a]` — the invariant a mask
        // built over any second walk over the log breaks (verified: a mask
        // written one slot out of step turns this expectation red).
        try std.testing.expectEqual(index.shun.digests.contains(index.log.hashOf(lr)), index.masked[a]);
        if (index.masked[a]) {
            shunned_seen += 1;
            try std.testing.expect(index.nameRid(expect_name) == null);
        } else {
            try std.testing.expectEqual(@as(?repostate.Rid, rid), index.nameRid(expect_name));
        }
    }
    // The fixture really does interleave: three shunned, two survivors.
    try std.testing.expectEqual(@as(usize, 3), shunned_seen);
    try std.testing.expectEqual(@as(usize, 2), resolvableNames(index));
}

test "sync §9.5 L2170-2174 / §7.7 L1472-1475: a write against a masked wire name does not unmask it — no second identity, still not held, still not servable" {
    const gpa = std.testing.allocator;
    const io = std.testing.io;
    var tmp = std.testing.tmpDir(.{});
    defer tmp.cleanup();
    try seedSendShunRepo(gpa, io, tmp.dir);

    var file = try tmp.dir.openFile(io, repo_filename, .{});
    defer file.close(io);
    const st = try file.stat(io);
    var index = try LogIndexStore.openFromFile(gpa, io, file, st.size);
    defer index.destroy();
    const s = index.store();

    // The masked name is absent from `by_name`, so every write door below misses the
    // dedup key the survivors hit and would otherwise fall through to the appendix —
    // minting a SECOND, HELD entry for a name §9.5 says this server does not send,
    // and putting it back on the §3.2 walk. The mask outranks the write instead.
    const masked_name = send_shun_names[0];
    try std.testing.expect(index.masked[0]);
    const before = s.count();

    try std.testing.expectEqual(@as(repostate.Rid, 1), try s.intern(masked_name));
    try std.testing.expectEqual(@as(repostate.Rid, 1), try s.put(masked_name, "content zero\n"));
    // Even bytes that DISAGREE with the frame: the mask is not a content check, and
    // this path must not read (nor assert on) a masked frame's plaintext.
    try std.testing.expectEqual(@as(repostate.Rid, 1), try s.put(masked_name, "different bytes\n"));
    try s.retain(1, .{ .full = "not a real container" });

    // Nothing was created and nothing was unmasked.
    try std.testing.expectEqual(before, s.count());
    try std.testing.expectEqual(@as(usize, 2), resolvableNames(index));
    try std.testing.expect(!s.held(1));
    try std.testing.expect(s.content(1) == null);
    try std.testing.expect(s.wire(1) == null);
    // §3.3 L569-572 still applies to an inbound `gimme` for it: absent, silently
    // skipped, no second rid for the walk to trip over.
    try std.testing.expect(s.lookup(masked_name) == null);
    try std.testing.expect(!index.read_fault);

    // NEGATIVE SPACE: the appendix arm is intact for a name the log genuinely does
    // not carry — the guard above narrows the masked case only.
    const absent_name = repeat("99", digest_len);
    const appendix_rid = try s.intern(absent_name);
    try std.testing.expectEqual(@as(repostate.Rid, 6), appendix_rid);
    try std.testing.expectEqual(before + 1, s.count());
    try std.testing.expect(!s.held(appendix_rid));
}

test "sync §7.7 L1479-1485 / §9.5 L2170-2174: the adapter owns its content mask — the frame's plaintext is still on disk and still readable through the maintenance door" {
    const gpa = std.testing.allocator;
    const io = std.testing.io;
    var tmp = std.testing.tmpDir(.{});
    defer tmp.cleanup();
    try seedSendShunRepo(gpa, io, tmp.dir);

    var file = try tmp.dir.openFile(io, repo_filename, .{});
    defer file.close(io);
    const st = try file.stat(io);
    var index = try LogIndexStore.openFromFile(gpa, io, file, st.size);
    defer index.destroy();
    const s = index.store();

    // §9.5's filter is a POLICY answer about what this server SENDS, not a deletion:
    // the frame, its bytes and its checksums are untouched on disk. §7.7 L1479-1485
    // depends on exactly that — "For an admitted target whose DELTASRC name is in
    // the repository shun table, the receiver does not apply admission independently
    // to that source: content still held locally MAY serve as the delta basis" — so
    // "still held locally" is a property this slice must not have quietly destroyed.
    // `LogStore.contentUnmasked` is the maintenance door that reads under no mask
    // (`pack.zig`'s reader), and it is the only way to distinguish "the bytes are
    // gone" from "the send side refuses to hand them out".
    try std.testing.expect(index.masked[0]);
    const on_disk = try index.log.contentUnmasked(gpa, index.rids[0], null);
    defer if (on_disk) |b| gpa.free(b);
    try std.testing.expectEqualStrings("content zero\n", on_disk.?);

    // ...and the store still refuses, in both forms, without calling it a fault.
    try std.testing.expect(s.content(1) == null);
    try std.testing.expect(s.wire(1) == null);
    try std.testing.expect(!index.read_fault);
    // Nothing was materialised on the way: a refusal is answered from the mask, so
    // a masked frame is never inflated into the round's memo (which is also what
    // keeps a shunned artifact's plaintext out of a server's memory).
    try std.testing.expectEqual(@as(usize, 0), index.materialized_bytes);
    try std.testing.expectEqual(@as(usize, 0), index.residentBytes());

    // NEGATIVE SPACE: the maintenance door is not a blanket unmask of the store —
    // a SURVIVOR reads identically through both, so the asymmetry above is the
    // mask's doing and not an artefact of which reader was called.
    const survivor = try index.log.contentUnmasked(gpa, index.rids[1], null);
    defer if (survivor) |b| gpa.free(b);
    try std.testing.expectEqualStrings(survivor.?, s.content(2).?);
}

test "sync §9.5 L2170-2174 / §7.7 L1472-1475: a served round's writes land in the round-local overlay — the base enumeration's write doors are never reached" {
    const gpa = std.testing.allocator;
    const io = std.testing.io;
    var tmp = std.testing.tmpDir(.{});
    defer tmp.cleanup();

    // `seedSendShunRepo`'s digests are synthetic, so no peer could legitimately push
    // one back — the responder hashes the payload and would reject the name long
    // before reaching any store door. This fixture names its two artifacts by their
    // REAL content address, so the push below is one a real peer could send.
    const shunned_body = "shunned artifact bytes\n";
    const survivor_body = "surviving artifact bytes\n";
    var shunned_buf: [64]u8 = undefined;
    var survivor_buf: [64]u8 = undefined;
    const shunned_name = zit.artifact.artifactName(.sha3_256, shunned_body, &shunned_buf);
    const survivor_name = zit.artifact.artifactName(.sha3_256, survivor_body, &survivor_buf);
    var shunned_dbuf: [digest_len]u8 = undefined;
    var survivor_dbuf: [digest_len]u8 = undefined;
    const shunned_digest = hexToDigest(shunned_name, &shunned_dbuf) orelse return error.BadTestName;
    const survivor_digest = hexToDigest(survivor_name, &survivor_dbuf) orelse return error.BadTestName;

    const hk: u8 = @backingInt(zit.artifact.defaultPolicy(false, false));
    {
        var f = try tmp.dir.createFile(io, repo_filename, .{ .read = true, .exclusive = true });
        defer f.close(io);
        var fs = storage.FileStorage.init(io, f, 0);
        var seed = try logstore.LogStore.open(gpa, fs.storageFile(), hk);
        defer seed.deinit(gpa);
        try seed.putConfig(.{ .hash_policy = hk, .default_branch = "trunk", .project_id = "", .project_code = "" });
        _ = try seed.put(shunned_digest, shunned_body);
        _ = try seed.put(survivor_digest, survivor_body);
        try seed.putShun(shunned_digest, "operator request", 1);
        try seed.commit();
    }

    const server = zit.sync.Server{
        .version = serve_mod.server_version,
        .self_servercode = serve_mod.server_servercode,
        .project_code = serve_mod.server_projectcode,
    };
    var file = try tmp.dir.openFile(io, repo_filename, .{});
    defer file.close(io);
    var ctx = ServeCtx{ .io = io, .root_dir = tmp.dir, .file = &file, .server = &server };
    defer ctx.deinit();

    // A peer pushes the very name this repository has shunned.
    const push_plain = try std.fmt.allocPrint(gpa, "pragma client-version 20000\npush sc pc\nfile {s} {d}\n{s}", .{ shunned_name, shunned_body.len, shunned_body });
    defer gpa.free(push_plain);
    const push_req = try zit.container.encode(gpa, push_plain, .default);
    defer gpa.free(push_req);
    {
        const reply = try serveAnswer(&ctx, gpa, push_req, null, .{}, true);
        defer gpa.free(reply.body);

        // THE PROPERTY. `putImpl`/`internImpl` deliberately NARROW the store contract
        // for a masked name — they answer a rid whose `content` is null and whose
        // `held` is false — and the vtable's `error{OutOfMemory}` cannot signal that.
        // What keeps the narrowing safe is that a served round never reaches those
        // doors at all: `respond` writes into a per-request `repostate.OverlayStore`
        // that is discarded at round end. `appendix` is where any write that DID
        // reach this base would land, so its emptiness is that claim, measured.
        const base = ctx.snapshot.?;
        try std.testing.expectEqual(@as(usize, 0), base.appendix.store().count());
        try std.testing.expectEqual(@as(usize, 2), base.store().count());
        // ...and the push did not unmask the name it carried.
        try std.testing.expect(base.masked[0]);
        try std.testing.expect(base.store().lookup(shunned_name) == null);
        try std.testing.expect(!base.store().held(1));
        try std.testing.expect(base.store().content(1) == null);
        try std.testing.expect(!base.read_fault);
        // The survivor is untouched by any of it.
        try std.testing.expectEqual(@as(?repostate.Rid, 2), base.store().lookup(survivor_name));
    }

    // NEGATIVE SPACE: it is not the MASK that keeps the base's doors shut, it is the
    // overlay. A push of a name this repository has never seen — the case that has a
    // real appendix arm waiting for it — must land in the round-local store just the
    // same. (This round's `baseSnapshot` rebuilds over the grown log first, so the
    // snapshot read below is the one this round actually served from.)
    const fresh_body = "a name this repository has never held\n";
    var fresh_buf: [64]u8 = undefined;
    const fresh_name = zit.artifact.artifactName(.sha3_256, fresh_body, &fresh_buf);
    const fresh_plain = try std.fmt.allocPrint(gpa, "pragma client-version 20000\npush sc pc\nfile {s} {d}\n{s}", .{ fresh_name, fresh_body.len, fresh_body });
    defer gpa.free(fresh_plain);
    const fresh_req = try zit.container.encode(gpa, fresh_plain, .default);
    defer gpa.free(fresh_req);
    const reply2 = try serveAnswer(&ctx, gpa, fresh_req, null, .{}, true);
    defer gpa.free(reply2.body);
    try std.testing.expectEqual(@as(usize, 0), ctx.snapshot.?.appendix.store().count());
}

/// The `clone_seqno NEXT` cursor a clone reply carries (§8.2 L1573-1576: "An
/// accepting clone reply emits zero or more clone cfile cards in RID order … then
/// clone_seqno NEXT, push SERVERCODE PROJECTCODE, and final comment. … NEXT zero
/// signals exhaustion."), read off the decoded body.
fn cloneSeqnoOf(body: []const u8) !u64 {
    var it = std.mem.splitScalar(u8, body, '\n');
    while (it.next()) |line| {
        if (!std.mem.startsWith(u8, line, "clone_seqno ")) continue;
        return std.fmt.parseInt(u64, line["clone_seqno ".len..], 10) catch return error.BadCloneSeqno;
    }
    return error.NoCloneSeqno;
}

/// Does the decoded reply body carry a `cfile` card for `name`? Keyed on the card
/// prefix plus the separating space, so a name that is a prefix of another cannot
/// answer for it.
fn replyHasCfile(gpa: std.mem.Allocator, body: []const u8, name: []const u8) !bool {
    const needle = try std.fmt.allocPrint(gpa, "cfile {s} ", .{name});
    defer gpa.free(needle);
    return std.mem.indexOf(u8, body, needle) != null;
}

// WHAT THIS TEST PINS, and what it does NOT. The masked frames' absence from the
// clone stream is NOT this slice's doing: the pager gates on `store.wire()` then
// `store.content()`, and `LogStore.wire`/`content` already answered null for a
// shunned entry through their own rid-keyed read mask before the enumeration was
// masked at all — so this test passes with `LogIndexStore`'s exclusion removed
// (confirmed by mutation). What it does pin, and what nothing else pins, is that
// the mask keeps the pager's persisted-order cursor CONTIGUOUS over the survivors:
// each survivor arrives exactly once across paged batches and the sequence
// terminates at NEXT 0. A mask written out of step with `rids` turns it red.
test "sync §8.2 L1551-1553 / §9.5 L2170-2174: the clone pager walks the survivors contiguously across paged batches and terminates at NEXT 0" {
    const gpa = std.testing.allocator;
    const io = std.testing.io;
    var tmp = std.testing.tmpDir(.{});
    defer tmp.cleanup();
    try seedSendShunRepo(gpa, io, tmp.dir);

    // A one-artifact batch cap forces the pager to page, so the persisted-order
    // cursor is exercised at every masked frame rather than swallowed by a single
    // full-store batch.
    const server = zit.sync.Server{
        .version = serve_mod.server_version,
        .self_servercode = serve_mod.server_servercode,
        .project_code = serve_mod.server_projectcode,
        .clone_batch_max = 1,
    };
    var file = try tmp.dir.openFile(io, repo_filename, .{});
    defer file.close(io);
    var ctx = ServeCtx{ .io = io, .root_dir = tmp.dir, .file = &file, .server = &server };
    defer ctx.deinit();

    var delivered = @as([5]usize, @splat(0));
    var seqno: u64 = 1;
    var rounds: usize = 0;
    while (rounds < 16) : (rounds += 1) {
        const plain = try std.fmt.allocPrint(gpa, "pragma client-version 20000\nclone 3 {d}\n", .{seqno});
        defer gpa.free(plain);
        const req = try zit.container.encode(gpa, plain, .default);
        defer gpa.free(req);
        const reply = try serveAnswer(&ctx, gpa, req, null, .{}, true);
        defer gpa.free(reply.body);
        // §8.1 L1529-1531 / §4.1 L885-887 — a clone reply is the RAW card/cfile stream under
        // `application/x-fossil-uncompressed`, never a zlib container.
        try std.testing.expectEqualStrings("application/x-fossil-uncompressed", reply.content_type);
        const body = reply.body;

        for (send_shun_names, 0..) |name, i| {
            if (try replyHasCfile(gpa, body, name)) delivered[i] += 1;
        }
        const next = try cloneSeqnoOf(body);
        if (next == 0) break;
        // A LOOP GUARD, not a protocol requirement: §8.2 L1577-1579 says the
        // opposite — "The client records a digit-only NEXT and does not validate
        // that a positive value advances from the supplied SEQNO". A pager that
        // returned a non-advancing cursor would spin this test to its round cap
        // instead of failing on the thing it is here to measure, so the guard
        // states the pager's own contract, with no normative claim behind it.
        try std.testing.expect(next > seqno);
        seqno = next;
    } else return error.CloneNeverExhausted;

    // THE PROOF: every survivor arrived EXACTLY ONCE across the paged batches, and
    // the sequence reached NEXT 0. The zero counts for the masked slots are carried
    // by the log's own read mask (see the note above the test), not by this slice;
    // the "exactly once" and the termination are the mask's contribution — a slot
    // masked out of step with `rids` drops or duplicates a survivor here.
    for (delivered, 0..) |n, i| {
        const want: usize = if (sendShunIsShunned(i)) 0 else 1;
        try std.testing.expectEqual(want, n);
    }
}

test "sync §9.5 L2170-2174: a shun row written between clone rounds is honoured by the next round WITHOUT renumbering the survivors" {
    const gpa = std.testing.allocator;
    const io = std.testing.io;
    var tmp = std.testing.tmpDir(.{});
    defer tmp.cleanup();

    // A repo holding all five artifacts and NO shun row yet.
    const hk: u8 = @backingInt(zit.artifact.defaultPolicy(false, false));
    {
        var f = try tmp.dir.createFile(io, repo_filename, .{ .read = true, .exclusive = true });
        defer f.close(io);
        var fs = storage.FileStorage.init(io, f, 0);
        var seed = try logstore.LogStore.open(gpa, fs.storageFile(), hk);
        defer seed.deinit(gpa);
        try seed.putConfig(.{ .hash_policy = hk, .default_branch = "trunk", .project_id = "", .project_code = "" });
        for (send_shun_digests, 0..) |d, i| {
            var body_buf: [32]u8 = undefined;
            _ = try seed.put(d, try std.fmt.bufPrint(&body_buf, "distinct content {d}\n", .{i}));
        }
        try seed.commit();
    }

    const server = zit.sync.Server{
        .version = serve_mod.server_version,
        .self_servercode = serve_mod.server_servercode,
        .project_code = serve_mod.server_projectcode,
    };
    var file = try tmp.dir.openFile(io, repo_filename, .{});
    defer file.close(io);
    var ctx = ServeCtx{ .io = io, .root_dir = tmp.dir, .file = &file, .server = &server };
    defer ctx.deinit();

    const clone_plain = "pragma client-version 20000\nclone 3 1\n";
    const clone_req = try zit.container.encode(gpa, clone_plain, .default);
    defer gpa.free(clone_req);

    // Round 1, no shun row: every artifact is served, and artifact 3 sits at
    // adapter rid 3. This is the behaviour the mask must change, so the test is
    // red on an unfiltered server.
    {
        const reply = try serveAnswer(&ctx, gpa, clone_req, null, .{}, true);
        defer gpa.free(reply.body);
        const body = reply.body; // §8.1 L1529-1531 / §4.1 L885-887 — uncompressed clone stream
        for (send_shun_names) |name| try std.testing.expect(try replyHasCfile(gpa, body, name));
        try std.testing.expectEqual(@as(?repostate.Rid, 3), ctx.snapshot.?.store().lookup(send_shun_names[2]));
        try std.testing.expectEqual(@as(?repostate.Rid, 5), ctx.snapshot.?.store().lookup(send_shun_names[4]));
    }

    // The operator shuns the MIDDLE artifact between rounds — an append, which is
    // exactly what trips `baseSnapshot`'s append-only stat gate and rebuilds.
    {
        var f = try tmp.dir.openFile(io, repo_filename, .{ .mode = .read_write });
        defer f.close(io);
        const st = try f.stat(io);
        var fs = storage.FileStorage.init(io, f, st.size);
        var log = try logstore.LogStore.open(gpa, fs.storageFile(), hk);
        defer log.deinit(gpa);
        try log.putShun(send_shun_digests[1], "operator request", 1);
        try log.commit();
    }

    // Round 2 honours it with no restart — AND the survivors above it keep their
    // adapter rids. A dense filter would shift artifact 3 to rid 2 and artifact 5
    // to rid 4, so a client resuming this clone at cursor 3 would step over
    // artifact 3 entirely and still be told NEXT 0 (§8.2 L1551-1553 licenses the
    // gap; it does not license the shift).
    {
        const reply = try serveAnswer(&ctx, gpa, clone_req, null, .{}, true);
        defer gpa.free(reply.body);
        const body = reply.body; // §8.1 L1529-1531 / §4.1 L885-887 — uncompressed clone stream
        try std.testing.expect(!try replyHasCfile(gpa, body, send_shun_names[1]));
        for (send_shun_names, 0..) |name, i| {
            if (i == 1) continue;
            try std.testing.expect(try replyHasCfile(gpa, body, name));
        }
        try std.testing.expectEqual(@as(usize, 5), ctx.snapshot.?.store().count());
        try std.testing.expectEqual(@as(?repostate.Rid, 3), ctx.snapshot.?.store().lookup(send_shun_names[2]));
        try std.testing.expectEqual(@as(?repostate.Rid, 5), ctx.snapshot.?.store().lookup(send_shun_names[4]));
        // THE MASK ITSELF, at THIS layer. The absent `cfile` above does not prove it:
        // `LogStore.wire`/`content` answer null for a shunned entry through their own
        // read mask, so the clone stream would omit the frame even with the
        // enumeration unmasked. The rebuilt index is where a shun table read once at
        // startup instead of per generation shows up, so assert on it directly.
        try std.testing.expect(ctx.snapshot.?.masked[1]);
        try std.testing.expect(ctx.snapshot.?.store().lookup(send_shun_names[1]) == null);
        try std.testing.expect(!ctx.snapshot.?.store().held(2));
    }
    try std.testing.expectEqual(@as(u64, 2), ctx.loads); // one build per log state
}

test "serve §3.8 / sync §9.5 L2170-2174: the snapshot cache key is not the size alone — a same-length write to the log invalidates it" {
    const gpa = std.testing.allocator;
    const io = std.testing.io;
    var tmp = std.testing.tmpDir(.{});
    defer tmp.cleanup();
    try seedSendShunRepo(gpa, io, tmp.dir);

    const server = zit.sync.Server{ .version = serve_mod.server_version };
    var file = try tmp.dir.openFile(io, repo_filename, .{});
    defer file.close(io);
    var ctx = ServeCtx{ .io = io, .root_dir = tmp.dir, .file = &file, .server = &server };
    defer ctx.deinit();

    const req = try serveGimmeRequest(gpa, "pull sc pc\nigot", shun_test_name);
    defer gpa.free(req);

    // Two read rounds over an untouched log: built once, then stat-gated. This is
    // the property the mtime term must NOT cost — a read round still does not
    // rebuild, so the cache is still a cache.
    for (0..2) |_| {
        const reply = try serveAnswer(&ctx, gpa, req, null, .{}, true);
        gpa.free(reply.body);
    }
    try std.testing.expectEqual(@as(u64, 1), ctx.loads);
    const before = try file.stat(io);

    // A write that leaves the log BYTE-IDENTICAL and exactly as long: the last byte
    // is lifted off and put straight back. Nothing a `zit` writer does today looks
    // like this — they all append — but "every writer only appends" is an assumption
    // about all present and future writers, not a checked property, and since this
    // snapshot began carrying the §3.3 shun table a missed rebuild no longer costs
    // stale CONTENT (self-correcting) but a stale SUPPRESSION TABLE: an artifact the
    // operator shunned served on, with nothing failing and nothing logged.
    {
        var f = try tmp.dir.openFile(io, repo_filename, .{ .mode = .read_write });
        defer f.close(io);
        var fs = storage.FileStorage.init(io, f, before.size);
        var last: [1]u8 = undefined;
        try std.testing.expectEqual(@as(usize, 1), try fs.storageFile().pread(before.size - 1, &last));
        try fs.storageFile().truncate(before.size - 1);
        var reopened = storage.FileStorage.init(io, f, before.size - 1);
        try reopened.storageFile().append(&last);
        try reopened.storageFile().sync();
    }

    // THE PREMISE, asserted rather than assumed: the log really is the same length
    // and the filesystem really did move the modification time. A filesystem that
    // could not express this scenario fails here, loudly, instead of letting the
    // conclusion below pass vacuously.
    const after = try file.stat(io);
    try std.testing.expectEqual(before.size, after.size);
    try std.testing.expect(after.mtime.nanoseconds != before.mtime.nanoseconds);

    // THE CONCLUSION: the size-only gate would have returned the stale snapshot and
    // its stale shun table. The size+mtime key rebuilds.
    {
        const reply = try serveAnswer(&ctx, gpa, req, null, .{}, true);
        gpa.free(reply.body);
    }
    try std.testing.expectEqual(@as(u64, 2), ctx.loads);
    try std.testing.expectEqual(after.mtime.nanoseconds, ctx.snapshot_log_mtime_ns);

    // ...and having rebuilt, it settles again: the key is stable, not a rebuild on
    // every round.
    {
        const reply = try serveAnswer(&ctx, gpa, req, null, .{}, true);
        gpa.free(reply.body);
    }
    try std.testing.expectEqual(@as(u64, 2), ctx.loads);
}

test "sync §7.2 L1265-1266 / §9.5 L2170-2174: a surviving delta whose basis is masked is served in FULL form, never as a dangling DELTASRC" {
    const gpa = std.testing.allocator;
    const io = std.testing.io;
    var tmp = std.testing.tmpDir(.{});
    defer tmp.cleanup();

    // `zit shun --defer` records the row without rewriting the generation, so a
    // SURVIVING frame in the current generation can still be a delta rooted on
    // the shunned one. Handing that delta's wire form out would emit a `cfile`
    // whose DELTASRC is never sent: the peer stores a permanently dangling delta
    // and gimme's a basis it will be silently skipped on — CORRUPT, not absent.
    const base_plain = "the quick brown fox jumps over the lazy dog, and then again once more";
    const child_plain = "the quick brown fox jumps over the lazy dog, and then twice more, at last";
    const hk: u8 = @backingInt(zit.artifact.defaultPolicy(false, false));
    {
        var f = try tmp.dir.createFile(io, repo_filename, .{ .read = true, .exclusive = true });
        defer f.close(io);
        var fs = storage.FileStorage.init(io, f, 0);
        var log = try logstore.LogStore.open(gpa, fs.storageFile(), hk);
        defer log.deinit(gpa);
        try log.putConfig(.{ .hash_policy = hk, .default_branch = "trunk", .project_id = "", .project_code = "" });
        const base_rid = try log.put(send_shun_digests[0], base_plain);
        const d = try zit.delta.create(gpa, base_plain, child_plain);
        defer gpa.free(d);
        _ = try log.putDelta(send_shun_digests[1], base_rid, d);
        try log.putShun(send_shun_digests[0], "operator request", 1);
        try log.commit();
    }

    var file = try tmp.dir.openFile(io, repo_filename, .{});
    defer file.close(io);
    const st = try file.stat(io);
    {
        var index = try LogIndexStore.openFromFile(gpa, io, file, st.size);
        defer index.destroy();
        const s = index.store();
        // The premise: the child really is a delta frame rooted on the masked one.
        try std.testing.expectEqual(logstore.FrameKind.delta, index.log.kindOf(index.rids[1]));
        // The masked basis is a §8.2 gap...
        try std.testing.expect(!s.held(1));
        try std.testing.expect(s.wire(1) == null);
        // ...so the child's DELTA wire form is withheld — the responder falls back
        // to compressing `content()` on the fly (§7.2), which reconstructs against
        // the raw log and is unaffected by the name-level mask.
        try std.testing.expect(s.held(2));
        try std.testing.expect(s.wire(2) == null);
        try std.testing.expectEqualStrings(child_plain, s.content(2).?);
        // Withholding a wire form for policy is not a read fault.
        try std.testing.expect(!index.read_fault);
    }

    // End to end through a clone round: the child arrives, the basis does not, and
    // the shunned NAME appears nowhere in the reply — no DELTASRC to dangle on.
    const server = zit.sync.Server{
        .version = serve_mod.server_version,
        .self_servercode = serve_mod.server_servercode,
        .project_code = serve_mod.server_projectcode,
    };
    var ctx = ServeCtx{ .io = io, .root_dir = tmp.dir, .file = &file, .server = &server };
    defer ctx.deinit();
    const clone_req = try zit.container.encode(gpa, "pragma client-version 20000\nclone 3 1\n", .default);
    defer gpa.free(clone_req);
    const reply = try serveAnswer(&ctx, gpa, clone_req, null, .{}, true);
    defer gpa.free(reply.body);
    const body = reply.body; // §8.1 L1529-1531 / §4.1 L885-887 — uncompressed clone stream
    try std.testing.expect(try replyHasCfile(gpa, body, send_shun_names[1]));
    try std.testing.expect(std.mem.indexOf(u8, body, send_shun_names[0]) == null);
}

/// True when `dir`'s repository resolves `name` — read back off disk, after the
/// served round has persisted, so this answers "did it LAND", not "was it
/// staged".
fn s77RepoHolds(gpa: std.mem.Allocator, io: std.Io, dir: std.Io.Dir, name: []const u8) !bool {
    var file = try dir.openFile(io, repo_filename, .{});
    defer file.close(io);
    const st = try file.stat(io);
    var index = try LogIndexStore.openFromFile(gpa, io, file, st.size);
    defer index.destroy();
    return index.store().lookup(name) != null;
}

test "sync §7.7 L1463-1467: the SERVED round's admission predicate is read from the repository's stored hash-policy, not defaulted" {
    const gpa = std.testing.allocator;
    const io = std.testing.io;

    const content = "a SHA1-named artifact a peer pushes at us\n";
    var nbuf: [64]u8 = undefined;
    const sha1_name = zit.artifact.artifactName(.sha1, content, &nbuf);
    try std.testing.expectEqual(@as(usize, 40), sha1_name.len);

    const plain = try std.fmt.allocPrint(
        gpa,
        "pragma client-version 20000\npush {s} {s}\nfile {s} {d}\n{s}",
        .{ serve_mod.server_servercode, serve_mod.server_projectcode, sha1_name, content.len, content },
    );
    defer gpa.free(plain);
    const request = try zit.container.encode(gpa, plain, .default);
    defer gpa.free(request);

    const server = zit.sync.Server{
        .version = serve_mod.server_version,
        .self_servercode = serve_mod.server_servercode,
        .project_code = serve_mod.server_projectcode,
    };

    // CONTROL: the same repository under `sha3` stores the pushed SHA1 name. If
    // this half ever stops holding, the shun-sha1 half below proves nothing.
    {
        var tmp = std.testing.tmpDir(.{});
        defer tmp.cleanup();
        try s77SeedPolicyRepo(gpa, io, tmp.dir, .sha3);
        var file = try tmp.dir.openFile(io, repo_filename, .{});
        defer file.close(io);
        var ctx = ServeCtx{ .io = io, .root_dir = tmp.dir, .file = &file, .server = &server };
        defer ctx.deinit();
        const reply = try serveAnswer(&ctx, gpa, request, null, .{}, true);
        gpa.free(reply.body);
        try std.testing.expect(try s77RepoHolds(gpa, io, tmp.dir, sha1_name));
    }

    // THE PROOF: the identical round against a repository whose stored config
    // names shun-sha1 discards it — with no error card (L1437-1440) — and the
    // ONLY difference between the two runs is that stored byte. A `serveRound`
    // that defaulted the policy instead of reading the snapshot would store here.
    {
        var tmp = std.testing.tmpDir(.{});
        defer tmp.cleanup();
        try s77SeedPolicyRepo(gpa, io, tmp.dir, .shun_sha1);
        var file = try tmp.dir.openFile(io, repo_filename, .{});
        defer file.close(io);
        var ctx = ServeCtx{ .io = io, .root_dir = tmp.dir, .file = &file, .server = &server };
        defer ctx.deinit();
        const reply = try serveAnswer(&ctx, gpa, request, null, .{}, true);
        defer gpa.free(reply.body);
        const plain_reply = try zit.container.decode(gpa, reply.body, 1 << 20);
        defer gpa.free(plain_reply);
        try std.testing.expect(std.mem.indexOf(u8, plain_reply, "error ") == null);
        try std.testing.expect(!try s77RepoHolds(gpa, io, tmp.dir, sha1_name));
    }
}

test "submanifests §8.1/§7.2: a repository that HOLDS a leaf arms its serve-side gate against a pre-S peer" {
    // The PRODUCTION wiring of the §7.2 gate, end to end through the durable
    // store: `persistStore` records §8.1's seen-submanifest indicator for a
    // stored SUBMANIFEST (which carries no S card at all, §4.4), the serve
    // snapshot re-reads it, and `serveRound` arms the gate with it. Every link
    // is load-bearing:
    //
    //   * drop the `transferGatedArtifact` line in `phantomizeSubManifestRefs`
    //     and the indicator stays false — a leaf is not "S-bearing" literally;
    //   * drop `round_server.seen_submanifest = …` in `serveRound` and the gate
    //     is unarmed, because §8.1's emission setting is false on every zit;
    //   * drop `or self.seen_submanifest` from `Server.submanifestGateArmed`
    //     and it is unarmed for the same reason.
    //
    // Each of the three leaves the leaf in the reply to a fossil-2.28 peer,
    // which §8 says can only hold it as "unreadable ... opaque content".
    const gpa = std.testing.allocator;
    const io = std.testing.io;
    var tmp = std.testing.tmpDir(.{});
    defer tmp.cleanup();
    var hex_buf: [2 * digest_len]u8 = undefined;
    try serveSeedRepo(gpa, io, tmp.dir, 1, &hex_buf);

    // §4.3: an F run with no D card is type SUBMANIFEST. The flat check-in
    // manifest beside it is everything that predates this draft.
    const leaf = "F a.txt " ++ (repeat("3", 64)) ++ "\n";
    const flat = "C m\nD 2026-07-27T12:00:00.000\nF a.txt " ++ (repeat("2", 64)) ++ "\nU u\n";
    var leaf_name: [2 * digest_len]u8 = undefined;
    var flat_name: [2 * digest_len]u8 = undefined;
    _ = zit.artifact.artifactName(.sha3_256, leaf, &leaf_name);
    _ = zit.artifact.artifactName(.sha3_256, flat, &flat_name);

    var ms = repostate.MemStore.init(gpa);
    defer ms.deinit();
    _ = try ms.store().put(&leaf_name, leaf);
    _ = try ms.store().put(&flat_name, flat);
    _ = try persistStore(gpa, io, tmp.dir, ms.store(), null, 0);

    // §8.1 — the indicator is DURABLE and covers §7.2's type shape, not only
    // its S-card shape. Read back through the same function the CLI uses.
    var pc_buf: [zit.sync.max_projectcode_len]u8 = undefined;
    const identity = try repoSyncIdentity(gpa, io, tmp.dir, "test-fixture-repo", &pc_buf);
    try std.testing.expect(identity.seen_submanifest);
    // …and the emission setting is the OTHER, independent half of the arming
    // disjunction: this repository holds a gated artifact it received, and has
    // never been told to emit one. A single flag could not tell the two apart.
    try std.testing.expect(!identity.enable_submanifests);

    // …and the served reply refuses the leaf to a peer announcing fossil 2.28,
    // while still handing it the artifact it can read.
    const server = zit.sync.Server{
        .version = serve_mod.server_version,
        .self_servercode = serve_mod.server_servercode,
        .project_code = serve_mod.server_projectcode,
    };
    try std.testing.expect(!server.submanifests_enabled); // §8.1's default, stated
    var file = try tmp.dir.openFile(io, repo_filename, .{});
    defer file.close(io);
    var ctx = ServeCtx{ .io = io, .root_dir = tmp.dir, .file = &file, .server = &server };
    defer ctx.deinit();

    const plain = try std.fmt.allocPrint(
        gpa,
        "pragma client-version 22800\npull sc {s}\ngimme {s}\ngimme {s}\n",
        .{ server.project_code, &leaf_name, &flat_name },
    );
    defer gpa.free(plain);
    const request = try zit.container.encode(gpa, plain, .default);
    defer gpa.free(request);
    const reply = try serveAnswer(&ctx, gpa, request, null, .{}, true);
    defer gpa.free(reply.body);
    const body = try zit.container.decode(gpa, reply.body, zit.sync.reply_body_cap);
    defer gpa.free(body);

    // Built through the same writer the server uses (§11.1's escape encoding
    // applies to the text), so the expectation cannot drift from the emission.
    var card_buf: [2 * zit.sync.submanifest_peer_error_text.len + 16]u8 = undefined;
    const refusal = zit.sync.writeSignalCard(.err, zit.sync.submanifest_peer_error_text, &card_buf);
    try std.testing.expect(std.mem.indexOf(u8, body, refusal) != null);
    try std.testing.expect(std.mem.indexOf(u8, body, &leaf_name) == null);
    try std.testing.expect(std.mem.indexOf(u8, body, &flat_name) != null);
}