Skip to content
zit Artifact [157c2464ff]
Login

Artifact [157c2464ff]

Artifact 157c2464ff7ca370acfed9ab9394a6b8211bdda44efcf35c618c8b6187e0d8d5:


//! `zit submanifest`: show, enable, disable, retune and analyze sub-manifests.

const std = @import("std");
const zit = @import("zit");
const cli = @import("zit").cli;
const cmd_tracking = @import("tracking.zig");
const logstore = @import("zit").logstore;
const storage = @import("zit").storage;
const checkout = @import("zit").checkout;
const Repository = @import("zit").Repository;
const artifact = zit.artifact;
const diagnostics = @import("../diagnostics.zig");
const help_pages = @import("../help.zig");
const max_tracked_file_bytes = cmd_tracking.max_tracked_file_bytes;

// ---------------------------------------------------------------------------
// `zit submanifest [show|enable|disable|retune|analyze]` — the sub-manifest
// operator surface (draft-fossil-submanifests-00 §6.3, §6.4, §8.1).
//
// Four actions over two settings. `show` reports them; `enable`/`disable` move
// §8.1's emission gate, `enable` pinning §6.3's partition parameter the first
// time and printing the consequence warning; `retune` performs §6.4's manual,
// forward-only re-pin; `analyze` runs §6.3's selection pass and writes nothing.
//
// §8.1's flag day makes enabling an act with real consequences: the card
// alphabet is closed, so a peer that does not announce support (§7.2) sees a
// truncated check-in graph from the first tree on. Enabling is therefore
// opt-in with the warning printed, not a silent toggle and not an
// indefinite refusal: the maintainer's compatibility contract says zit 0.2.0
// stays backwards compatible with fossil, and it does — the DEFAULT is off, and
// §7.2's transfer gate refuses every S-bearing artifact to a peer that has not
// sent `send-submanifests` rather than hand it something it cannot read.
// ---------------------------------------------------------------------------

pub fn runSubmanifest(
    gpa: std.mem.Allocator,
    io: std.Io,
    arena: std.mem.Allocator,
    verb_args: []const []const u8,
    streams: cli.Streams,
    amb: cli.Ambient,
) cli.Exit {
    const parsed = switch (cli.parseSubmanifestArgs(verb_args)) {
        .ok => |p| p,
        .unknown_option => |tok| return cli.usageError(streams, "submanifest", .unknown_option, tok),
        .extra_argument => |tok| return cli.usageError(streams, "submanifest", .extra_argument, tok),
        .bad_k => |tok| {
            streams.err.print(
                "zit submanifest: --k wants an integer {d}..{d} (got '{s}')\n",
                .{ artifact.min_k, artifact.max_k, tok },
            ) catch {};
            streams.err.writeAll("try 'zit submanifest --help'\n") catch {};
            return .usage;
        },
        .missing_value => |tok| {
            streams.err.print("zit submanifest: {s} wants a path\n", .{tok}) catch {};
            streams.err.writeAll("try 'zit submanifest --help'\n") catch {};
            return .usage;
        },
    };
    if (parsed.help) {
        streams.out.writeAll(help_pages.submanifest_help) catch {};
        return .ok;
    }

    // Settings-writing actions operate on the repository the checkout names;
    // only `analyze` (a pure measurement) honors -R -- the conversion
    // gate's pre-flight runs against a bare cloned store.
    if (amb.repo_override != null and parsed.action != .analyze) {
        streams.err.writeAll("zit submanifest: -R/--repo works with 'analyze' only; settings live in the repository the checkout names\n") catch {};
        return .failure;
    }
    if (parsed.replay_all and parsed.action != .analyze) {
        streams.err.writeAll("zit submanifest: --replay-all is an 'analyze' option\n") catch {};
        return .usage;
    }

    const root = (cli.resolveRoot(arena, io, amb.repo_override) catch return submanifestOom(streams)) orelse {
        diagnostics.reportNoRoot(streams, io, "submanifest", amb.repo_override);
        return .failure;
    };
    var root_dir = root.dir;
    defer root_dir.close(io);

    return switch (parsed.action) {
        .show => submanifestShow(gpa, io, root_dir, streams),
        .enable => submanifestEnable(gpa, io, root_dir, parsed.k, streams),
        .disable => submanifestDisable(gpa, io, root_dir, streams),
        .retune => submanifestRetune(gpa, io, root_dir, parsed.k, streams),
        .analyze => submanifestAnalyze(gpa, io, root_dir, parsed.names_path, parsed.replay_all, streams),
        // Routed by main.zig before a checkout is resolved.
        .convert => .usage,
    };
}

/// Read the repository's config frame. A missing or unreadable frame is a
/// repository-level failure here (unlike on the commit path, where the safe
/// default is simply "off"): every action below either reports the settings or
/// rewrites them, and both would be lies over a config that did not load.
fn submanifestConfig(
    gpa: std.mem.Allocator,
    io: std.Io,
    root_dir: std.Io.Dir,
    streams: cli.Streams,
) ?logstore.OwnedConfig {
    var file = cli.openStoreRead(io, root_dir) catch |e| {
        streams.err.print("zit submanifest: cannot read the repository: {s}\n", .{diagnostics.reasonOf(e)}) catch {};
        return null;
    };
    defer file.close(io);
    const st = file.stat(io) catch {
        streams.err.writeAll("zit submanifest: cannot read the repository\n") catch {};
        return null;
    };
    var fs = storage.FileStorage.init(io, file, st.size);
    // Through the saved log index, as `info` opens, so one config value does
    // not cost a header read per frame; a missing index is built here once.
    var resolved = checkout.storeDirOf(io, root_dir) catch null;
    defer if (resolved) |*r| r.close(io);
    var log = Repository.openLogIndexed(gpa, io, resolved orelse root_dir, fs.storageFile(), false) catch {
        streams.err.writeAll("zit submanifest: cannot read the repository\n") catch {};
        return null;
    };
    defer log.deinit(gpa);
    const oc = log.readConfig(gpa) catch {
        streams.err.writeAll("zit submanifest: cannot read the repository\n") catch {};
        return null;
    };
    if (oc == null) {
        streams.err.writeAll("zit submanifest: the repository carries no configuration\n") catch {};
        return null;
    }
    return oc;
}

/// An outer null preserves the cached value; an outer non-null writes its inner
/// value, including null to conservatively clear an unreadable checkout's cache.
/// This is implementation-only state, not an RFC setting.
pub fn replaceSettledCostShape(shape: ?[32]u8) ??[32]u8 {
    return shape;
}

/// Read-modify-write of the sub-manifest settings, preserving every unrelated
/// config field (plan E last-frame-wins). `settled_cost_shape` is tri-state so only
/// disable may preserve its cache; enable and retune replace it even with null.
pub fn submanifestWrite(
    gpa: std.mem.Allocator,
    io: std.Io,
    root_dir: std.Io.Dir,
    enabled: ?bool,
    k: ?u8,
    settled_cost_shape: ??[32]u8,
    streams: cli.Streams,
) bool {
    var store_append = cli.openStoreAppend(io, root_dir) catch |e| {
        if (e == error.StoreBusy) return false; // the lock notice already said it
        streams.err.writeAll("zit submanifest: cannot write the repository\n") catch {};
        return false;
    };
    defer store_append.close(io);
    const file = store_append.file;
    const st = file.stat(io) catch {
        streams.err.writeAll("zit submanifest: cannot write the repository\n") catch {};
        return false;
    };
    var fs = storage.FileStorage.init(io, file, st.size);
    var log = logstore.LogStore.open(gpa, fs.storageFile(), 0) catch {
        streams.err.writeAll("zit submanifest: cannot write the repository\n") catch {};
        return false;
    };
    defer log.deinit(gpa);
    var oc = (log.readConfig(gpa) catch null) orelse {
        streams.err.writeAll("zit submanifest: the repository carries no configuration\n") catch {};
        return false;
    };
    defer oc.deinit(gpa);
    var next = oc.config;
    if (enabled) |value| next.enable_submanifests = value;
    if (k) |value| next.submanifest_k = value;
    if (settled_cost_shape) |shape| next.submanifest_settled_cost_shape = shape;
    log.putConfig(next) catch {
        streams.err.writeAll("zit submanifest: cannot write the repository\n") catch {};
        return false;
    };
    log.commit() catch {
        streams.err.writeAll("zit submanifest: cannot write the repository\n") catch {};
        return false;
    };
    return true;
}

fn submanifestShow(
    gpa: std.mem.Allocator,
    io: std.Io,
    root_dir: std.Io.Dir,
    streams: cli.Streams,
) cli.Exit {
    var oc = submanifestConfig(gpa, io, root_dir, streams) orelse return .failure;
    defer oc.deinit(gpa);
    const s: zit.submanifest.Settings = .of(oc.config);

    streams.out.print("enable-submanifests: {s}\n", .{if (s.enabled) "on" else "off"}) catch {};
    if (s.pinned()) {
        streams.out.print("submanifest-k:       {d}\n", .{s.k}) catch {};
    } else {
        streams.out.writeAll("submanifest-k:       (not pinned)\n") catch {};
    }
    // §6.4's `submanifest-auto-retune` — shown because it is now a PROPAGATED
    // setting: a clone adopts it from its origin over sync §9.3, so an operator
    // can arrive at a repository that re-tunes on commit without ever having
    // set it here. A setting that can reach a repository without the operator's
    // act has to be visible to the operator.
    streams.out.print(
        "submanifest-auto-retune: {s}\n",
        .{if (oc.config.submanifest_auto_retune) "on" else "off"},
    ) catch {};
    // §8.1's local indicator, the thing that arms the §7.2 transfer gate even
    // after the setting is turned back off. Worth showing: it is the durable
    // record that peers unable to read trees no longer see this repository's
    // whole history.
    streams.out.print(
        "seen-submanifest:    {s}\n",
        .{if (oc.config.seen_submanifest) "yes (this repository holds S-bearing artifacts)" else "no"},
    ) catch {};

    switch (zit.submanifest.emission(s)) {
        .off => streams.out.writeAll("commits emit: flat manifests\n") catch {},
        .out_of_range => |v| streams.out.print(
            "commits emit: flat manifests — {s} ({d}; must be {d}..{d})\n",
            .{ zit.submanifest.out_of_range_report_prefix, v, artifact.min_k, artifact.max_k },
        ) catch {},
        .tree => |v| streams.out.print("commits emit: tree manifests, partitioned at k={d}\n", .{v}) catch {},
    }
    // §6.3's project-scope requirement is not met; say so where an operator will
    // read it rather than only in a source comment.
    streams.out.writeAll(submanifest_scope_gap) catch {};
    return .ok;
}

/// §6.3 — "Project scope (configuration propagating to clones) is REQUIRED".
/// A clone now adopts these settings over [FossilSync] §9.3's scalar `/config`
/// channel, so the shortfall is narrower than it was: what remains is that a
/// repository already in existence never re-reads them from a peer. Printed by
/// `show` and by `enable`, and kept honest about which half works.
const submanifest_scope_gap =
    "\nscope: a CLONE adopts these settings from its origin (§6.3 project scope, over\n" ++
    "the sync §9.3 configuration exchange), so a fresh clone partitions the way this\n" ++
    "repository does. An EXISTING repository is not refreshed by a later pull or\n" ++
    "sync — change it here and on each peer. Repositories pinned differently still\n" ++
    "exchange artifacts correctly (§6.4) — they just stop sharing sub-manifests.\n";

/// The cache key is an effective F-set shape, never a checkout filename list.
/// Failure to read the current check-in leaves the setting change valid but
/// uncached; the following commit then conservatively scans.
fn submanifestSettledShape(
    gpa: std.mem.Allocator,
    io: std.Io,
    root_dir: std.Io.Dir,
) ?[32]u8 {
    var arena_state = std.heap.ArenaAllocator.init(gpa);
    defer arena_state.deinit();
    const arena = arena_state.allocator();
    var repo: Repository = undefined;
    repo.open(gpa, io, root_dir, .{ .mode = .full }) catch return null;
    defer repo.deinit(gpa);
    const rid = repo.currentCheckoutRid() orelse return null;
    var files = (repo.files(gpa, rid) catch return null) orelse return null;
    defer files.deinit(gpa);

    var entries: std.ArrayList(artifact.FCard) = .empty;
    defer entries.deinit(arena);
    var it = files.iterator();
    while (it.next()) |entry| entries.append(arena, entry) catch return null;
    var digest: [32]u8 = undefined;
    _ = zit.submanifest.costShapeDigest(entries.items, &digest);
    return digest;
}

fn submanifestEnable(
    gpa: std.mem.Allocator,
    io: std.Io,
    root_dir: std.Io.Dir,
    k_arg: ?u8,
    streams: cli.Streams,
) cli.Exit {
    var oc = submanifestConfig(gpa, io, root_dir, streams) orelse return .failure;
    defer oc.deinit(gpa);
    const s: zit.submanifest.Settings = .of(oc.config);

    // §6.3: "The partition parameter k is selected once, when the
    // enable-submanifests setting is first turned on for a repository, and
    // pinned". A repository that already has one keeps it — re-pinning is a
    // re-tune (§6.4), which is a different verb with a different consequence.
    // Only a value in range is a pin, though: a stored value outside 1..12 came
    // from a hand edit or another writer, and §8.1 says it is neither kept nor
    // treated as absent — without --k the request is refused naming it, and an
    // explicit in-range --k replaces it.
    const valid_pin = s.pinned() and zit.submanifest.inRange(s.k);
    if (valid_pin and k_arg != null and k_arg.? != s.k) {
        streams.err.print(
            "zit submanifest: k is already pinned to {d}; changing it is a re-tune — " ++
                "use 'zit submanifest retune --k {d}'\n",
            .{ s.k, k_arg.? },
        ) catch {};
        return .failure;
    }
    if (s.pinned() and !valid_pin and k_arg == null) {
        streams.err.print(
            "zit submanifest: the stored submanifest-k {d} is outside {d}..{d}; " ++
                "pass --k N to replace it\n",
            .{ s.k, artifact.min_k, artifact.max_k },
        ) catch {};
        return .failure;
    }
    // §6.3: "The partition parameter k is selected once, when the
    // enable-submanifests setting ... is first turned on" — and the draft names
    // the objective it is selected BY, so selecting it is the writer's job. An
    // explicit --k overrides; an already-pinned repository keeps its value
    // (re-pinning is a re-tune); otherwise the analysis pass answers, and
    // §8.1's "MUST NOT enable emission ... with no pinned parameter" is
    // satisfied by pinning rather than by refusing.
    var analyzed_over: ?usize = null;
    const k: u8 = if (k_arg) |v| v else if (valid_pin) s.k else blk: {
        const sel = submanifestSelectK(gpa, io, root_dir, streams) orelse return .failure;
        analyzed_over = sel.names;
        // History outranks the snapshot when both can speak. The
        // snapshot objective is theory over ONE file set; the replay is the
        // same choice measured against this repository's own recent commits
        // (argmin of realized steady-state materialization). No verdict, no
        // gate — the one decision that stays with the operator is the
        // compatibility spend, stated below as it always was.
        break :blk submanifestReplayK(gpa, io, root_dir, sel.k, streams) orelse sel.k;
    };
    // §6.3: "MUST support every value from 1 to 12 inclusive (the pinned value
    // MUST lie in that range)". Refuse to PIN an out-of-range value; the
    // fallback-and-report rule exists for a value that reaches a writer some
    // other way, not as a licence to store one here.
    if (!zit.submanifest.inRange(k)) {
        streams.err.print(
            "zit submanifest: k must be {d}..{d} (got {d})\n",
            .{ artifact.min_k, artifact.max_k, k },
        ) catch {};
        return .failure;
    }

    const settled_shape = submanifestSettledShape(gpa, io, root_dir);
    if (!submanifestWrite(
        gpa,
        io,
        root_dir,
        true,
        k,
        replaceSettledCostShape(settled_shape),
        streams,
    )) return .failure;

    // §8.1/§7.2 — the consequence, stated before the operator's next commit,
    // not buried in documentation.
    streams.out.print("enable-submanifests: on (submanifest-k pinned to {d})\n", .{k}) catch {};
    // What this does NOT do, said here rather than discovered
    // later — existing history is untouched, and every fossil peer stops
    // receiving new check-ins.
    streams.out.writeAll(
        "existing check-ins stay flat; from the next commit, peers that do not announce\n" ++
            "sub-manifest support (every fossil) receive nothing new from this repository.\n" ++
            "To re-mint the whole history as trees in a new repository:\n" ++
            "'zit submanifest convert SRC DEST'.\n",
    ) catch {};
    if (analyzed_over) |names| {
        // §6.3: "The selection is advisory rather than canonical -- any pinned
        // k yields conforming artifacts". Say what it was measured over, so the
        // operator can tell a selection from a default.
        streams.out.print(
            "submanifest-k was selected by the §6.3 analysis over this check-in's {d} names;\n" ++
                "'zit submanifest analyze' shows the full table, 'retune --k N' moves the pin.\n",
            .{names},
        ) catch {};
    }
    streams.out.print("\nWARNING: {s}\n", .{zit.sync.submanifest_enable_warning}) catch {};
    streams.out.writeAll(submanifest_scope_gap) catch {};
    return .ok;
}

fn submanifestDisable(
    gpa: std.mem.Allocator,
    io: std.Io,
    root_dir: std.Io.Dir,
    streams: cli.Streams,
) cli.Exit {
    // §8.1: "Disabling the setting stops the emission of new tree manifests; it
    // cannot retire existing ones (artifact names are immutable)." The pin is
    // deliberately left in place — it is the repository's identity for content
    // sharing, and clearing it would silently make a later re-enable a re-tune.
    if (!submanifestWrite(gpa, io, root_dir, false, null, null, streams)) return .failure;
    streams.out.writeAll("enable-submanifests: off\n") catch {};
    var oc = submanifestConfig(gpa, io, root_dir, streams) orelse return .ok;
    defer oc.deinit(gpa);
    if (oc.config.seen_submanifest) {
        streams.out.writeAll(
            "note: this repository already holds S-bearing artifacts. Disabling stops new\n" ++
                "tree manifests; it cannot retire the existing ones, and peers that do not\n" ++
                "announce sub-manifest support are still refused every one of them.\n",
        ) catch {};
    }
    return .ok;
}

fn submanifestRetune(
    gpa: std.mem.Allocator,
    io: std.Io,
    root_dir: std.Io.Dir,
    k_arg: ?u8,
    streams: cli.Streams,
) cli.Exit {
    // §6.4: "A re-tune MUST be manual and operator-initiated". The value is
    // never inferred here — no argument is a usage failure, not a call into the
    // analysis pass.
    const k = k_arg orelse {
        streams.err.writeAll(
            "zit submanifest: retune needs an explicit value: 'zit submanifest retune --k N'.\n" ++
                "A re-tune is always manual; run 'zit submanifest analyze' first if you want the " ++
                "analyzed optimum.\n",
        ) catch {};
        return .failure;
    };
    if (!zit.submanifest.inRange(k)) {
        streams.err.print(
            "zit submanifest: k must be {d}..{d} (got {d})\n",
            .{ artifact.min_k, artifact.max_k, k },
        ) catch {};
        return .failure;
    }
    var oc = submanifestConfig(gpa, io, root_dir, streams) orelse return .failure;
    defer oc.deinit(gpa);
    const s: zit.submanifest.Settings = .of(oc.config);
    if (s.k == k) {
        streams.out.print("submanifest-k: already {d} — nothing to do\n", .{k}) catch {};
        return .ok;
    }

    const settled_shape = submanifestSettledShape(gpa, io, root_dir);
    if (!submanifestWrite(
        gpa,
        io,
        root_dir,
        null,
        k,
        replaceSettledCostShape(settled_shape),
        streams,
    )) return .failure;
    streams.out.print("submanifest-k: {d} -> {d}\n", .{ s.k, k }) catch {};
    // §6.4: "If both it and its parent are trees, they share exactly the
    // sub-manifest artifacts whose bytes are identical under the two full
    // constructions; this can be every, some, or none of the parent's
    // sub-manifests". The unshared ones land in the next commit, so the cost
    // is said now rather than met at an arbitrary moment.
    if (s.enabled) {
        streams.out.writeAll(
            "note: the next commit shares only the sub-manifests whose bytes are unchanged under\n" ++
                "the new k: all, some or none. No history is rewritten and no reader behaves differently.\n",
        ) catch {};
    }
    return .ok;
}

/// §6.3's objective at every k in `min_k..max_k`, in order, into `out`; returns
/// how many rows were filled. The shared core of `analyze` (which prints the
/// whole table) and `enable` (which pins only the winner), so the value the
/// operator is shown is by construction the value that gets pinned.
fn submanifestCosts(
    gpa: std.mem.Allocator,
    entries: []const artifact.FCard,
    out: *[artifact.max_k - artifact.min_k + 1]zit.submanifest.Cost,
) std.mem.Allocator.Error!usize {
    var n: usize = 0;
    var k: u4 = artifact.min_k;
    while (true) : (k += 1) {
        out[n] = try zit.submanifest.cost(gpa, entries, k, .sha3_256);
        n += 1;
        // Explicit terminator: `k` is a u4, so raising `max_k` to 15 would make
        // `k += 1` wrap to 0 and spin forever on a `k <= max_k` condition.
        if (k == artifact.max_k) break;
    }
    return n;
}

/// §6.3's selection: the k minimizing the objective over the repository's
/// current name set. This is the writer's choice, not the operator's — the
/// draft has the parameter "selected once, when the enable-submanifests setting
/// is first turned on", and names the objective it is selected by. Returns null
/// after reporting why no value could be selected; the caller then refuses to
/// enable rather than substituting one.
fn submanifestSelectK(
    gpa: std.mem.Allocator,
    io: std.Io,
    root_dir: std.Io.Dir,
    streams: cli.Streams,
) ?struct { k: u8, names: usize } {
    var arena_state = std.heap.ArenaAllocator.init(gpa);
    defer arena_state.deinit();

    const entries = submanifestNamesFromCheckout(gpa, arena_state.allocator(), io, root_dir, false, streams) orelse {
        streams.err.writeAll(
            "zit submanifest: no file set to select a partition parameter from — " ++
                "pin one explicitly with 'zit submanifest enable --k N'.\n",
        ) catch {};
        return null;
    };
    if (entries.len == 0) {
        streams.err.writeAll(
            "zit submanifest: the current check-in holds no files, so there is nothing to\n" ++
                "select a partition parameter from — pin one with 'zit submanifest enable --k N'.\n",
        ) catch {};
        return null;
    }

    var costs: [artifact.max_k - artifact.min_k + 1]zit.submanifest.Cost = undefined;
    const n = submanifestCosts(gpa, entries, &costs) catch {
        _ = submanifestOom(streams);
        return null;
    };
    const winner = zit.submanifest.best(costs[0..n]) orelse {
        // Every k leaves this name set flat (§6.2 step 2), so the objective has
        // no candidate to minimize and there is no analyzed value to pin. Not a
        // reason to invent one: the set will not stay this small, and §6.3
        // leaves the choice to the operator when the pass cannot make it.
        streams.err.print(
            "zit submanifest: no k partitions this repository's {d} names into a tree " ++
                "(§6.2 step 2),\nso no parameter can be selected — pin one with " ++
                "'zit submanifest enable --k N' if you want one anyway.\n",
            .{entries.len},
        ) catch {};
        return null;
    };
    return .{ .k = winner.k, .names = entries.len };
}

/// The §6.3 analysis pass over a name set: k = 1..12, the objective for each,
/// and the §6.5 prediction beside the measured optimum.
///
/// Writes nothing. §6.4: "an implementation MAY advise of drift from the
/// analyzed optimum but MUST NOT re-tune automatically" — so this reports and
/// stops, and moving the pin is the operator's separate `retune` act.
fn submanifestAnalyze(
    gpa: std.mem.Allocator,
    io: std.Io,
    root_dir: std.Io.Dir,
    names_path: ?[]const u8,
    replay_all: bool,
    streams: cli.Streams,
) cli.Exit {
    var arena_state = std.heap.ArenaAllocator.init(gpa);
    defer arena_state.deinit();
    const aa = arena_state.allocator();

    const entries = (if (names_path) |p|
        submanifestNamesFromFile(aa, io, p, streams)
    else
        submanifestNamesFromCheckout(gpa, aa, io, root_dir, true, streams)) orelse {
        if (names_path == null) {
            streams.err.writeAll("zit submanifest: analyze a name list instead with '--names PATH'\n") catch {};
        }
        return .failure;
    };

    if (entries.len == 0) {
        streams.err.writeAll("zit submanifest: the name set is empty — nothing to analyze\n") catch {};
        return .failure;
    }

    streams.out.print("names: {d}\n", .{entries.len}) catch {};
    streams.out.writeAll("\n  k   leaves  depth   S-bytes  wmean-leaf     total   flat-F-bytes\n") catch {};

    var costs: [artifact.max_k - artifact.min_k + 1]zit.submanifest.Cost = undefined;
    const n = submanifestCosts(gpa, entries, &costs) catch return submanifestOom(streams);
    for (costs[0..n]) |c| {
        if (c.flat) {
            streams.out.print(
                "{d:>3}   {s:>44}   {d:>12}\n",
                .{ c.k, "(flat: fewer than two groups, §6.2 step 2)", c.flat_bytes },
            ) catch {};
        } else {
            streams.out.print(
                "{d:>3}   {d:>6}  {d:>5}  {d:>8}  {d:>10.1}  {d:>8.1}   {d:>12}\n",
                .{ c.k, c.leaves, c.heights, c.s_bytes, c.weighted_mean_leaf_bytes, c.total, c.flat_bytes },
            ) catch {};
        }
    }

    // Stated before any early return: a name list carries no history,
    // and history is the replay's whole subject.
    if (names_path != null) {
        streams.out.writeAll(
            "\nreplay: unavailable with --names — a name list carries no commit history,\n" ++
                "and history is what decides whether enabling pays (see 'zit submanifest --help').\n",
        ) catch {};
    }

    const winner = zit.submanifest.best(costs[0..n]) orelse {
        streams.out.writeAll(
            "\nno k partitions this name set into a tree (§6.2 step 2) — commits stay flat at every k.\n",
        ) catch {};
        return .ok;
    };
    streams.out.print(
        "\nanalyzed optimum: k={d} (objective {d:.1})\n",
        .{ winner.k, winner.total },
    ) catch {};
    // §6.5, informative: "the analyzed optimum tracks roughly half the base-2
    // logarithm of the file count". Printed beside the measurement so drift
    // between the two is visible rather than assumed away.
    streams.out.print(
        "§6.5 prediction:  ~{d:.1} (half the base-2 log of {d} names)\n",
        .{ zit.submanifest.predictedK(entries.len), entries.len },
    ) catch {};

    // The replay — the static table above is theory over ONE snapshot;
    // whether enabling would have PAID on this repository is a property of
    // its history (churn/reuse), so it is measured by replaying that history
    // through the real builder and the real delta encoder.
    if (names_path == null) {
        submanifestReplaySection(gpa, io, root_dir, winner.k, if (replay_all) std.math.maxInt(usize) else replay_window, streams);
    }

    streams.out.writeAll(
        "\nAdvisory only — any pinned k yields conforming artifacts (§6.3). Nothing was\n" ++
            "changed; move the pin with 'zit submanifest retune --k N' (§6.4, manual only).\n",
    ) catch {};
    return .ok;
}

/// The replay window: enough steady-state commits for churn structure to
/// show, small enough that analyze stays an offline-audit-scale wait.
const replay_window: usize = 200;

/// Render the replay for the static winner and its in-range neighbours. Any
/// failure is reported and skipped — the replay is evidence for a decision,
/// never a gate on printing the static analysis above it.
fn submanifestReplaySection(
    gpa: std.mem.Allocator,
    io: std.Io,
    root_dir: std.Io.Dir,
    winner_k: u4,
    window: usize,
    streams: cli.Streams,
) void {
    var ks_buf: [3]u4 = undefined;
    var n_ks: usize = 0;
    if (winner_k > artifact.min_k) {
        ks_buf[n_ks] = winner_k - 1;
        n_ks += 1;
    }
    ks_buf[n_ks] = winner_k;
    n_ks += 1;
    if (winner_k < artifact.max_k) {
        ks_buf[n_ks] = winner_k + 1;
        n_ks += 1;
    }

    var repo: Repository = undefined;
    Repository.open(&repo, gpa, io, root_dir, .{ .mode = .full }) catch {
        streams.out.writeAll("\nreplay: cannot open the repository — skipped.\n") catch {};
        return;
    };
    defer repo.deinit(gpa);

    var rep = zit.submanifest.replay(gpa, &repo, window, ks_buf[0..n_ks]) catch {
        streams.out.writeAll("\nreplay: failed reading history — skipped.\n") catch {};
        return;
    };
    defer rep.deinit(gpa);
    renderReplay(&rep, streams);
}

/// The replay table: flat actuals first, then each arm's steady-state deltas
/// on BOTH axes with bootstrap and breakeven separate — the verdict gates on
/// full-form/materialization (where the F-card wall actually breaks people),
/// with store inflation reported as the price.
fn renderReplay(rep: *const zit.submanifest.Replay, streams: cli.Streams) void {
    if (rep.commits < 2) {
        streams.out.print(
            "\nreplay: only {d} replayable commit(s) — too little history to measure; not evidence either way.\n",
            .{rep.commits},
        ) catch {};
        return;
    }
    streams.out.print(
        "\nreplayed over the last {d} commits (this repository's own history):\n" ++
            "flat (actual):   store {d} bytes, full-form {d} bytes\n",
        .{ rep.commits, rep.flat_store, rep.flat_full },
    ) catch {};
    const steady_commits: u64 = @intCast(rep.commits - 1);
    const flat_first_store = rep.flat_store - rep.flat_store_steady;
    for (rep.arms) |arm| {
        if (arm.all_flat) {
            streams.out.print("k={d:<2}  every replayed commit built flat (§6.2 step 2) — no evidence at this k\n", .{arm.k}) catch {};
            continue;
        }
        const full_pct = signedPct(arm.steady_full, rep.flat_full_steady);
        const store_pct = signedPct(arm.steady_store, rep.flat_store_steady);
        streams.out.print(
            "k={d:<2}  steady state: full-form {d:>6.1}%, store {d:>6.1}%; bootstrap {d} bytes",
            .{ arm.k, full_pct, store_pct, arm.bootstrap_store },
        ) catch {};
        // Breakeven on the STORE axis: commits until the bootstrap's extra
        // stored bytes are repaid by the steady-state per-commit saving.
        if (arm.bootstrap_store > flat_first_store and rep.flat_store_steady > arm.steady_store) {
            const extra = arm.bootstrap_store - flat_first_store;
            const saving_per_commit = (rep.flat_store_steady - arm.steady_store) / steady_commits;
            if (saving_per_commit > 0) {
                streams.out.print(", breakeven ~{d} commits", .{extra / saving_per_commit + 1}) catch {};
            }
        } else if (arm.steady_store >= rep.flat_store_steady) {
            streams.out.writeAll(", breakeven: never on store bytes") catch {};
        }
        streams.out.writeAll("\n") catch {};
    }
    if (rep.bestArm()) |w| {
        if (w.steady_full < rep.flat_full_steady) {
            const full_pct = signedPct(w.steady_full, rep.flat_full_steady);
            streams.out.print(
                "verdict: k={d} — steady-state full-form {d:.1}% vs flat over this window.\n",
                .{ w.k, full_pct },
            ) catch {};
            if (rep.insideDesignEnvelope()) {
                streams.out.print(
                    "note: flat materialization averages {d} KB/commit — inside the format's design\n" ++
                        "envelope, so the absolute saving is small; the real decision is the permanent\n" ++
                        "compatibility spend, and that one is yours.\n",
                    .{rep.flatFullSteadyPerCommit() / 1024},
                ) catch {};
            }
        } else {
            streams.out.writeAll(
                "verdict: no replayed k beat the flat arm's steady-state full-form cost over\n" ++
                    "this window — this churn pattern favors flat manifests.\n",
            ) catch {};
        }
    }
}

/// The k-selector for `enable`: replay the snapshot winner and its
/// in-range neighbours over recent history and return the argmin of realized
/// steady-state materialization — the k this repository's own churn actually
/// rewards — or null when the replay cannot speak (no history, every arm
/// flat, unopenable repository), leaving the snapshot winner standing. Prints
/// which evidence chose the pin. Never refuses anything: choosing k is this
/// function's whole authority.
fn submanifestReplayK(
    gpa: std.mem.Allocator,
    io: std.Io,
    root_dir: std.Io.Dir,
    snapshot_k: u8,
    streams: cli.Streams,
) ?u8 {
    if (!zit.submanifest.inRange(snapshot_k)) return null;
    const winner_k: u4 = @intCast(snapshot_k);
    var ks_buf: [3]u4 = undefined;
    var n_ks: usize = 0;
    if (winner_k > artifact.min_k) {
        ks_buf[n_ks] = winner_k - 1;
        n_ks += 1;
    }
    ks_buf[n_ks] = winner_k;
    n_ks += 1;
    if (winner_k < artifact.max_k) {
        ks_buf[n_ks] = winner_k + 1;
        n_ks += 1;
    }

    var repo: Repository = undefined;
    Repository.open(&repo, gpa, io, root_dir, .{ .mode = .full }) catch return null;
    defer repo.deinit(gpa);
    var rep = zit.submanifest.replay(gpa, &repo, replay_window, ks_buf[0..n_ks]) catch return null;
    defer rep.deinit(gpa);
    if (rep.commits < 2) return null;
    const w = rep.bestArm() orelse return null;
    streams.out.print(
        "k={d} by replaying {d} commits (steady-state materialization {d:.1}% vs flat; " ++
            "snapshot optimum k={d}).\n",
        .{ w.k, rep.commits, signedPct(w.steady_full, rep.flat_full_steady), snapshot_k },
    ) catch {};
    return w.k;
}

/// Percentage delta of `got` against `base`, signed: -40.0 means 40% below.
fn signedPct(got: u64, base: u64) f64 {
    std.debug.assert(base > 0);
    const g: f64 = @floatFromInt(got);
    const b: f64 = @floatFromInt(base);
    return (g - b) * 100.0 / b;
}

/// The current checkout's effective file set as F cards, on `aa`.
fn submanifestNamesFromCheckout(
    gpa: std.mem.Allocator,
    aa: std.mem.Allocator,
    io: std.Io,
    root_dir: std.Io.Dir,
    fallback_tip: bool,
    streams: cli.Streams,
) ?[]const artifact.FCard {
    var repo: Repository = undefined;
    repo.open(gpa, io, root_dir, .{ .mode = .full }) catch {
        streams.err.writeAll("zit submanifest: cannot read the repository\n") catch {};
        return null;
    };
    defer repo.deinit(gpa);
    // The fact only — each caller states its own remedy, since `analyze` can be
    // pointed at a name file and `enable` cannot.
    const rid = repo.currentCheckoutRid() orelse blk: {
        // analyze over a bare store (-R, no checkout anywhere): the main
        // branch's tip file set is the natural measurement subject.
        if (fallback_tip) {
            if (repo.resolve("tip", .checkin)) |tip| {
                streams.out.writeAll("no checkout open — analyzing the tip check-in's file set\n") catch {};
                break :blk tip;
            } else |_| {}
        }
        streams.err.writeAll(
            "zit submanifest: no check-in is open, so there is no file set to work from\n",
        ) catch {};
        return null;
    };
    var fl = (repo.files(gpa, rid) catch {
        streams.err.writeAll("zit submanifest: cannot read the current check-in\n") catch {};
        return null;
    }) orelse {
        streams.err.writeAll("zit submanifest: cannot read the current check-in\n") catch {};
        return null;
    };
    defer fl.deinit(gpa);

    var list: std.ArrayList(artifact.FCard) = .empty;
    var it = fl.iterator();
    while (it.next()) |f| {
        list.append(aa, .{
            .filename = aa.dupe(u8, f.filename) catch return null,
            .hash = if (f.hash) |h| aa.dupe(u8, h) catch return null else null,
            .perm = if (f.perm) |p| aa.dupe(u8, p) catch return null else null,
            .old_name = null, // §6.2 partitions on the filename only
            .mode = f.mode,
        }) catch return null;
    }
    return list.items;
}

/// A newline-separated name list from `path`, as F cards on `aa`.
///
/// §6.1: "The predicate reads the filename only: content hash, permission, and
/// old-name never influence the partition." So a name list is a complete input
/// to the partition; only the BYTE counts need a hash, and those depend on its
/// length, not its value — every entry gets a distinct 64-hex placeholder, the
/// width the SHA3-256 policy this pass measures under emits. Blank lines are
/// skipped; the list must already be in canonical order (§4.5.3), which is what
/// a manifest's F run and `fossil ls` both produce.
fn submanifestNamesFromFile(
    aa: std.mem.Allocator,
    io: std.Io,
    path: []const u8,
    streams: cli.Streams,
) ?[]const artifact.FCard {
    const bytes = std.Io.Dir.cwd().readFileAlloc(io, path, aa, .limited(max_tracked_file_bytes)) catch {
        streams.err.print("zit submanifest: cannot read '{s}'\n", .{path}) catch {};
        return null;
    };
    var list: std.ArrayList(artifact.FCard) = .empty;
    var it = std.mem.splitScalar(u8, bytes, '\n');
    var seq: u64 = 0;
    while (it.next()) |raw| {
        const name = std.mem.trimEnd(u8, raw, "\r");
        if (name.len == 0) continue;
        seq += 1;
        var digest: [32]u8 = undefined;
        std.mem.writeInt(u64, digest[0..8], seq, .little);
        @memset(digest[8..], 0);
        const hex = aa.alloc(u8, 64) catch return null;
        _ = std.fmt.bufPrint(hex, "{x}", .{&digest}) catch return null;
        list.append(aa, .{
            .filename = name,
            .hash = hex,
            .perm = null,
            .old_name = null,
            .mode = .regular,
        }) catch return null;
    }
    const items = list.items;
    // §6.2's precondition: strictly ascending canonical order. Reported rather
    // than sorted — a caller whose list is out of order is measuring a different
    // name set than it thinks it is.
    for (items, 0..) |e, i| {
        if (i != 0 and !std.mem.lessThan(u8, items[i - 1].filename, e.filename)) {
            streams.err.print(
                "zit submanifest: '{s}' is not in canonical order after '{s}' " ++
                    "(the name list must be sorted, with no duplicates)\n",
                .{ e.filename, items[i - 1].filename },
            ) catch {};
            return null;
        }
    }
    return items;
}

fn submanifestOom(s: cli.Streams) cli.Exit {
    s.err.writeAll("zit submanifest: out of memory\n") catch {};
    return .failure;
}