Skip to content
zit Artifact [751e4a8568]
Login

Artifact [751e4a8568]

Artifact 751e4a8568dab1bd2c74817346ce87bf9b3cb70b7e8744fd683c6b646b83419c:


const std = @import("std");
const repeat = @import("zit").repeat;
const logstore = @import("zit").logstore;
const storage = @import("zit").storage;
const support = @import("support.zig");
const addManaged = support.addManaged;
const adoptStore = support.adoptStore;
const checkinHash = support.checkinHash;
const expectContains = support.expectContains;
const expectExit = support.expectExit;
const expectExitDiag = support.expectExitDiag;
const freeResult = support.freeResult;
const initRepo = support.initRepo;
const parseCheckin = support.parseCheckin;
const readFile = support.readFile;
const readSubmanifestSettings = support.readSubmanifestSettings;
const runCommitEnv = support.runCommitEnv;
const runZit = support.runZit;
const seedManyFiles = support.seedManyFiles;
const statField = support.statField;
const touch = support.touch;
const writeFile = support.writeFile;

/// Reads the internal cache marker only to prove conservative invalidation. It
/// is not an RFC setting; the surrounding enable/retune behavior is §6.3/§6.4.
fn readSubmanifestSettledCostShape(
    gpa: std.mem.Allocator,
    io: std.Io,
    dir: std.Io.Dir,
) !?[32]u8 {
    var file = try dir.openFile(io, ".zit", .{ .mode = .read_only });
    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);
    var oc = (try log.readConfig(gpa)) orelse return error.TestUnexpectedResult;
    defer oc.deinit(gpa);
    return oc.config.submanifest_settled_cost_shape;
}

/// Overwrite the pinned k directly in the config frame, bypassing the verb.
/// The ONLY way to reach §6.3's out-of-range state: `zit submanifest` refuses
/// to pin one, so a repository can only get there by a hand-edited config or a
/// writer from another implementation — which is exactly the case §6.3's
/// fallback rule exists for.
fn forcePinnedK(gpa: std.mem.Allocator, io: std.Io, dir: std.Io.Dir, k: u8) !void {
    var file = try dir.openFile(io, ".zit", .{ .mode = .read_write });
    defer file.close(io);
    const st = try file.stat(io);
    var fs = storage.FileStorage.init(io, file, st.size);
    var log = try logstore.LogStore.open(gpa, fs.storageFile(), 0);
    defer log.deinit(gpa);
    var oc = (try log.readConfig(gpa)) orelse return error.TestUnexpectedResult;
    defer oc.deinit(gpa);
    var next = oc.config;
    next.submanifest_k = k;
    try log.putConfig(next);
    try log.commit();
}

test "cli submanifests §6.3/§6.4: retune clears stale cache when checkout resolution fails" {
    const gpa = std.testing.allocator;
    const io = std.testing.io;
    var tmp = std.testing.tmpDir(.{});
    defer tmp.cleanup();
    try initRepo(gpa, io, tmp.dir);
    try seedManyFiles(gpa, io, tmp.dir, 2);

    var root = try runCommitEnv(gpa, io, tmp.dir, .{ .user = "u" }, &.{ "commit", "-m", "root" });
    defer freeResult(gpa, &root);
    try expectExitDiag(root.term, 0, root);

    var enable = try runZit(gpa, io, tmp.dir, &.{ "submanifest", "enable", "--k", "3" });
    defer freeResult(gpa, &enable);
    try expectExitDiag(enable.term, 0, enable);
    try std.testing.expect((try readSubmanifestSettledCostShape(gpa, io, tmp.dir)) != null);

    // Deliberately make the checkout unreadable after the cache was populated.
    // §6.3 permits retuning; failure to reconstruct its effective F-set must
    // conservatively invalidate the implementation-only cache.
    try writeFile(io, tmp.dir, ".zit-checkout", "corrupt\n");
    var retune = try runZit(gpa, io, tmp.dir, &.{ "submanifest", "retune", "--k", "4" });
    defer freeResult(gpa, &retune);
    try expectExitDiag(retune.term, 0, retune);
    try std.testing.expect((try readSubmanifestSettledCostShape(gpa, io, tmp.dir)) == null);
}

test "cli submanifests §6.3: enable clears stale cache when checkout resolution fails" {
    const gpa = std.testing.allocator;
    const io = std.testing.io;
    var tmp = std.testing.tmpDir(.{});
    defer tmp.cleanup();
    try initRepo(gpa, io, tmp.dir);
    try seedManyFiles(gpa, io, tmp.dir, 2);

    var root = try runCommitEnv(gpa, io, tmp.dir, .{ .user = "u" }, &.{ "commit", "-m", "root" });
    defer freeResult(gpa, &root);
    try expectExitDiag(root.term, 0, root);
    var enable = try runZit(gpa, io, tmp.dir, &.{ "submanifest", "enable", "--k", "3" });
    defer freeResult(gpa, &enable);
    try expectExitDiag(enable.term, 0, enable);
    try std.testing.expect((try readSubmanifestSettledCostShape(gpa, io, tmp.dir)) != null);

    var disable = try runZit(gpa, io, tmp.dir, &.{ "submanifest", "disable" });
    defer freeResult(gpa, &disable);
    try expectExitDiag(disable.term, 0, disable);
    try writeFile(io, tmp.dir, ".zit-checkout", "corrupt\n");

    var reenable = try runZit(gpa, io, tmp.dir, &.{ "submanifest", "enable", "--k", "3" });
    defer freeResult(gpa, &reenable);
    try expectExitDiag(reenable.term, 0, reenable);
    try std.testing.expect((try readSubmanifestSettledCostShape(gpa, io, tmp.dir)) == null);
}

test "cli submanifests §8.1: emission is OFF by default and a default repository mints no S card" {
    // THE default-off proof, at the only layer that can prove it: a repository
    // that nobody configured, committed through the real binary, whose minted
    // manifest carries a full flat F run and an EMPTY S run.
    const gpa = std.testing.allocator;
    const io = std.testing.io;
    var tmp = std.testing.tmpDir(.{});
    defer tmp.cleanup();
    try initRepo(gpa, io, tmp.dir);

    // The stored settings are off and unpinned before anything is asked of them.
    const settings = try readSubmanifestSettings(gpa, io, tmp.dir);
    try std.testing.expect(!settings.enabled);
    try std.testing.expect(!settings.pinned());

    try seedManyFiles(gpa, io, tmp.dir, 40);
    var ci = try runCommitEnv(gpa, io, tmp.dir, .{ .user = "u" }, &.{ "commit", "-m", "flat" });
    defer freeResult(gpa, &ci);
    try expectExitDiag(ci.term, 0, ci);
    const hash = try checkinHash(ci.stdout);

    var m = try parseCheckin(gpa, io, tmp.dir, hash);
    defer m.deinit();
    try std.testing.expectEqual(@as(usize, 0), m.m.s.len); // §8.1 — no S card
    try std.testing.expectEqual(@as(usize, 40), m.m.f.len); // the whole flat run

    // …and the §8.1 seen-submanifest indicator is untouched, so this repository
    // is not treated as one that holds trees.
    var file = try tmp.dir.openFile(io, ".zit", .{ .mode = .read_only });
    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);
    var oc = (try log.readConfig(gpa)).?;
    defer oc.deinit(gpa);
    try std.testing.expect(!oc.config.seen_submanifest);
}

test "cli submanifests §6.3/§8.1: a one-name check-in has no candidate, and enabling refuses atomically" {
    // The minimal no-candidate scenario: one name makes the height-0 scan flat
    // at every k (§6.2 step 2 needs at least two groups), so §6.3's automatic
    // selection "has no result" and §8.1's rule fires — "the writer MUST refuse
    // the request atomically: enable-submanifests and submanifest-k retain
    // their pre-request values, and no S card is emitted." Distinct from the
    // no-check-in case below: here the name set exists and is analyzed, and the
    // analysis is what comes back empty.
    const gpa = std.testing.allocator;
    const io = std.testing.io;
    var tmp = std.testing.tmpDir(.{});
    defer tmp.cleanup();
    try initRepo(gpa, io, tmp.dir);
    try touch(io, tmp.dir, "only.txt");
    {
        var a = try runZit(gpa, io, tmp.dir, &.{ "add", "only.txt" });
        defer freeResult(gpa, &a);
        try expectExitDiag(a.term, 0, a);
    }
    {
        var ci = try runCommitEnv(gpa, io, tmp.dir, .{ .user = "u" }, &.{ "commit", "-m", "one" });
        defer freeResult(gpa, &ci);
        try expectExitDiag(ci.term, 0, ci);
    }

    // The analysis pass agrees there is no candidate, and says so without failing.
    {
        var a = try runZit(gpa, io, tmp.dir, &.{ "submanifest", "analyze" });
        defer freeResult(gpa, &a);
        try expectExitDiag(a.term, 0, a);
        try std.testing.expect(std.mem.indexOf(u8, a.stdout, "no k partitions") != null);
    }

    var r = try runZit(gpa, io, tmp.dir, &.{ "submanifest", "enable" });
    defer freeResult(gpa, &r);
    try expectExit(r.term, 1);
    try std.testing.expect(std.mem.indexOf(u8, r.stderr, "no k partitions") != null);
    try std.testing.expect(std.mem.indexOf(u8, r.stderr, "--k") != null);

    // "retain their pre-request values" — atomically, so BOTH settings are as
    // they were, not just the one the refusal is about.
    const after = try readSubmanifestSettings(gpa, io, tmp.dir);
    try std.testing.expect(!after.enabled);
    try std.testing.expect(!after.pinned());

    // §8.1's escape hatch is still open: an explicit in-range k pins and enables
    // on the very same repository, which is what proves the refusal was about
    // the absent selection and not about the name set being unusable.
    var e = try runZit(gpa, io, tmp.dir, &.{ "submanifest", "enable", "--k", "4" });
    defer freeResult(gpa, &e);
    try expectExitDiag(e.term, 0, e);
    const pinned = try readSubmanifestSettings(gpa, io, tmp.dir);
    try std.testing.expect(pinned.enabled);
    try std.testing.expectEqual(@as(u8, 4), pinned.k);
}

test "cli submanifests §8.1: enabling is refused when no parameter can be selected" {
    // §6.3 has the writer select k on enabling, so the bare verb analyzes
    // rather than demanding a number. With no check-in open there is no name
    // set to select from — and §8.1's "MUST NOT enable emission on a repository
    // with no pinned parameter" then makes this a refusal, not a fallback to
    // some value of the implementation's own.
    const gpa = std.testing.allocator;
    const io = std.testing.io;
    var tmp = std.testing.tmpDir(.{});
    defer tmp.cleanup();
    try initRepo(gpa, io, tmp.dir);

    var r = try runZit(gpa, io, tmp.dir, &.{ "submanifest", "enable" });
    defer freeResult(gpa, &r);
    try expectExit(r.term, 1);
    try std.testing.expect(std.mem.indexOf(u8, r.stderr, "no file set") != null);
    try std.testing.expect(std.mem.indexOf(u8, r.stderr, "--k") != null);
    const after = try readSubmanifestSettings(gpa, io, tmp.dir);
    try std.testing.expect(!after.enabled); // refused means NOT written
    try std.testing.expect(!after.pinned());
}

test "cli submanifest show reads the config through the saved log index, building it once" {
    // Goal: `show` answers one config value, so its cost must not grow with
    // the log. Method: with no index, `show` must leave one behind; with an
    // index present, a damaged header in a frame `show` never needs must not
    // matter, which a header-by-header walk of the log would trip over.
    const gpa = std.testing.allocator;
    const io = std.testing.io;
    var tmp = std.testing.tmpDir(.{});
    defer tmp.cleanup();
    try initRepo(gpa, io, tmp.dir);
    try writeFile(io, tmp.dir, "a", "a\n");
    var add_a = try runZit(gpa, io, tmp.dir, &.{"addremove"});
    defer freeResult(gpa, &add_a);
    try expectExitDiag(add_a.term, 0, add_a);
    var c1 = try runCommitEnv(gpa, io, tmp.dir, .{ .user = "u" }, &.{ "commit", "-m", "one" });
    defer freeResult(gpa, &c1);
    try expectExitDiag(c1.term, 0, c1);
    try writeFile(io, tmp.dir, "b", "b\n");
    var add_b = try runZit(gpa, io, tmp.dir, &.{"addremove"});
    defer freeResult(gpa, &add_b);
    try expectExitDiag(add_b.term, 0, add_b);
    var c2 = try runCommitEnv(gpa, io, tmp.dir, .{ .user = "u" }, &.{ "commit", "-m", "two" });
    defer freeResult(gpa, &c2);
    try expectExitDiag(c2.term, 0, c2);

    tmp.dir.deleteFile(io, ".zit-cache/index") catch {};
    var cold = try runZit(gpa, io, tmp.dir, &.{ "submanifest", "show" });
    defer freeResult(gpa, &cold);
    try expectExitDiag(cold.term, 0, cold);
    try expectContains(cold.stdout, "enable-submanifests: off\n");
    try expectContains(cold.stdout, "seen-submanifest:    no\n");
    _ = try tmp.dir.statFile(io, ".zit-cache/index", .{});

    // The first frame of blob `a` (named by the SHA3-256 of its bytes) is
    // neither the config frame nor the tail the index is checked against.
    var digest: [32]u8 = undefined;
    std.crypto.hash.sha3.Sha3_256.hash("a\n", &digest, .{});
    {
        const store = try readFile(gpa, io, tmp.dir, ".zit");
        defer gpa.free(store);
        const at = std.mem.indexOf(u8, store, &digest) orelse return error.TestUnexpectedResult;
        var file = try tmp.dir.openFile(io, ".zit", .{ .mode = .read_write });
        defer file.close(io);
        try file.writePositionalAll(io, &.{store[at] ^ 0xff}, at);
    }
    var warm = try runZit(gpa, io, tmp.dir, &.{ "submanifest", "show" });
    defer freeResult(gpa, &warm);
    try expectExitDiag(warm.term, 0, warm);
    try std.testing.expectEqualStrings(cold.stdout, warm.stdout);
}

test "cli submanifests §6.3: an out-of-range k is refused at the pin, at every value outside 1..12" {
    const gpa = std.testing.allocator;
    const io = std.testing.io;
    var tmp = std.testing.tmpDir(.{});
    defer tmp.cleanup();
    try initRepo(gpa, io, tmp.dir);

    for ([_][]const u8{ "0", "13", "200" }) |k| {
        var r = try runZit(gpa, io, tmp.dir, &.{ "submanifest", "enable", "--k", k });
        defer freeResult(gpa, &r);
        try std.testing.expect(r.term.exited != 0);
        const after = try readSubmanifestSettings(gpa, io, tmp.dir);
        try std.testing.expect(!after.enabled);
        try std.testing.expect(!after.pinned());
    }
    // Both ends of §6.3's supported range are accepted.
    for ([_][]const u8{ "1", "12" }) |k| {
        var r = try runZit(gpa, io, tmp.dir, &.{ "submanifest", "retune", "--k", k });
        defer freeResult(gpa, &r);
        try expectExitDiag(r.term, 0, r);
    }
}

test "cli submanifests §8.1/§6.2: enabling warns, pins k, and the next commit mints a tree" {
    const gpa = std.testing.allocator;
    const io = std.testing.io;
    var tmp = std.testing.tmpDir(.{});
    defer tmp.cleanup();
    try initRepo(gpa, io, tmp.dir);
    try seedManyFiles(gpa, io, tmp.dir, 40);

    {
        // k = 3 is the Appendix A.5 conformance vector's value, pinned here for
        // the same reason: a test must never take its input from a measurement.
        var r = try runZit(gpa, io, tmp.dir, &.{ "submanifest", "enable", "--k", "3" });
        defer freeResult(gpa, &r);
        try expectExitDiag(r.term, 0, r);
        // §8.1/§7.2 — the consequence is shown, not implied. Both irreversible
        // halves must appear: the refusal of peers that do not announce
        // sub-manifest support, and the fact that disabling later cannot
        // retire what was written. So must the flag-day rule that follows: a
        // repository such a peer serves must not have the setting on.
        try std.testing.expect(std.mem.indexOf(u8, r.stdout, "do not announce sub-manifest support") != null);
        try std.testing.expect(std.mem.indexOf(u8, r.stdout, "cannot retire") != null);
        try std.testing.expect(std.mem.indexOf(u8, r.stdout, "must not have the setting enabled") != null);
        // §6.3's project scope is stated to the operator, both halves: a clone
        // adopts these settings, an existing repository is not refreshed.
        try std.testing.expect(std.mem.indexOf(u8, r.stdout, "a CLONE adopts these settings") != null);
        try std.testing.expect(std.mem.indexOf(u8, r.stdout, "An EXISTING repository is not refreshed") != null);
    }
    const settings = try readSubmanifestSettings(gpa, io, tmp.dir);
    try std.testing.expect(settings.enabled);
    try std.testing.expectEqual(@as(u8, 3), settings.k);

    var ci = try runCommitEnv(gpa, io, tmp.dir, .{ .user = "u" }, &.{ "commit", "-m", "tree" });
    defer freeResult(gpa, &ci);
    try expectExitDiag(ci.term, 0, ci);
    const hash = try checkinHash(ci.stdout);

    var m = try parseCheckin(gpa, io, tmp.dir, hash);
    defer m.deinit();
    // §6.2 step 3 — the manifest carries its S run and NO F run: "the file set
    // is conveyed by the F run or the S run", never both.
    try std.testing.expect(m.m.s.len >= 2);
    try std.testing.expectEqual(@as(usize, 0), m.m.f.len);

    // §8.1 — "When the first S-bearing artifact is stored, an implementation
    // SHOULD record a local seen-submanifest indicator". The commit path is one
    // of the two places S-bearing artifacts enter a log; the indicator is what
    // keeps the §7.2 transfer gate armed after the setting is turned back off.
    {
        var file = try tmp.dir.openFile(io, ".zit", .{ .mode = .read_only });
        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);
        var oc = (try log.readConfig(gpa)).?;
        defer oc.deinit(gpa);
        try std.testing.expect(oc.config.seen_submanifest);
    }

    // §5.1 — the tree enumerates back to the complete file set, so the check-in
    // is not merely well-formed but readable as the 40 files it was built from.
    var listed = try runZit(gpa, io, tmp.dir, &.{ "ls", hash });
    defer freeResult(gpa, &listed);
    try expectExitDiag(listed.term, 0, listed);
    var lines: usize = 0;
    var it = std.mem.splitScalar(u8, listed.stdout, '\n');
    while (it.next()) |l| {
        if (l.len != 0) lines += 1;
    }
    try std.testing.expectEqual(@as(usize, 40), lines);
}

test "cli submanifests: enable pins k from replayed history and cites the evidence" {
    const gpa = std.testing.allocator;
    const io = std.testing.io;
    var tmp = std.testing.tmpDir(.{});
    defer tmp.cleanup();
    try initRepo(gpa, io, tmp.dir);
    try seedManyFiles(gpa, io, tmp.dir, 40);

    // Churn history: the same file rewritten across several commits, so the
    // replay has real subtree reuse to measure the candidates against.
    for (0..6) |i| {
        const content = try std.fmt.allocPrint(gpa, "revision {d}\n", .{i});
        defer gpa.free(content);
        try writeFile(io, tmp.dir, "f000.txt", content);
        var ci = try runCommitEnv(gpa, io, tmp.dir, .{ .user = "u" }, &.{ "commit", "-m", "churn" });
        defer freeResult(gpa, &ci);
        try expectExitDiag(ci.term, 0, ci);
    }

    var r = try runZit(gpa, io, tmp.dir, &.{ "submanifest", "enable" });
    defer freeResult(gpa, &r);
    try expectExitDiag(r.term, 0, r);
    // The pin was chosen by the replay, and the output says so — the churn-aware
    // shape: better k from measured history, no verdict, no gate.
    try std.testing.expect(std.mem.indexOf(u8, r.stdout, "by replaying") != null);
    const settings = try readSubmanifestSettings(gpa, io, tmp.dir);
    try std.testing.expect(settings.enabled);
    try std.testing.expect(settings.k >= 1 and settings.k <= 12);
}

test "cli submanifests: enable on a fresh single-commit repository still proceeds — the snapshot objective selects" {
    const gpa = std.testing.allocator;
    const io = std.testing.io;
    var tmp = std.testing.tmpDir(.{});
    defer tmp.cleanup();
    try initRepo(gpa, io, tmp.dir);
    try seedManyFiles(gpa, io, tmp.dir, 40);
    var ci = try runCommitEnv(gpa, io, tmp.dir, .{ .user = "u" }, &.{ "commit", "-m", "only" });
    defer freeResult(gpa, &ci);
    try expectExitDiag(ci.term, 0, ci);

    var r = try runZit(gpa, io, tmp.dir, &.{ "submanifest", "enable" });
    defer freeResult(gpa, &r);
    try expectExitDiag(r.term, 0, r);
    const settings = try readSubmanifestSettings(gpa, io, tmp.dir);
    try std.testing.expect(settings.enabled);
}

test "cli submanifests §8.1: enable keeps a valid pin, refuses a differing --k, and replaces an out-of-range stored value only under an explicit --k" {
    const gpa = std.testing.allocator;
    const io = std.testing.io;
    var tmp = std.testing.tmpDir(.{});
    defer tmp.cleanup();
    try initRepo(gpa, io, tmp.dir);
    try seedManyFiles(gpa, io, tmp.dir, 40);
    var ci = try runCommitEnv(gpa, io, tmp.dir, .{ .user = "u" }, &.{ "commit", "-m", "only" });
    defer freeResult(gpa, &ci);
    try expectExitDiag(ci.term, 0, ci);

    // No pin: --k pins.
    {
        var r = try runZit(gpa, io, tmp.dir, &.{ "submanifest", "enable", "--k", "3" });
        defer freeResult(gpa, &r);
        try expectExitDiag(r.term, 0, r);
        const s = try readSubmanifestSettings(gpa, io, tmp.dir);
        try std.testing.expect(s.enabled);
        try std.testing.expectEqual(@as(u8, 3), s.k);
    }
    // Valid pin, same value: harmless.
    {
        var r = try runZit(gpa, io, tmp.dir, &.{ "submanifest", "enable", "--k", "3" });
        defer freeResult(gpa, &r);
        try expectExitDiag(r.term, 0, r);
        try std.testing.expectEqual(@as(u8, 3), (try readSubmanifestSettings(gpa, io, tmp.dir)).k);
    }
    // Valid pin, differing value: a re-tune, which is a different verb.
    {
        var r = try runZit(gpa, io, tmp.dir, &.{ "submanifest", "enable", "--k", "4" });
        defer freeResult(gpa, &r);
        try std.testing.expect(r.term != .exited or r.term.exited != 0);
        try std.testing.expect(std.mem.indexOf(u8, r.stderr, "already pinned to 3") != null);
        try std.testing.expect(std.mem.indexOf(u8, r.stderr, "retune --k 4") != null);
        try std.testing.expectEqual(@as(u8, 3), (try readSubmanifestSettings(gpa, io, tmp.dir)).k);
    }
    // Out-of-range stored value: no pin to keep, and not absent either.
    try forcePinnedK(gpa, io, tmp.dir, 13);
    {
        var r = try runZit(gpa, io, tmp.dir, &.{ "submanifest", "enable" });
        defer freeResult(gpa, &r);
        try std.testing.expect(r.term != .exited or r.term.exited != 0);
        try std.testing.expect(std.mem.indexOf(u8, r.stderr, "stored submanifest-k 13 is outside") != null);
        try std.testing.expectEqual(@as(u8, 13), (try readSubmanifestSettings(gpa, io, tmp.dir)).k);
    }
    {
        var r = try runZit(gpa, io, tmp.dir, &.{ "submanifest", "enable", "--k", "4" });
        defer freeResult(gpa, &r);
        try expectExitDiag(r.term, 0, r);
        try std.testing.expectEqual(@as(u8, 4), (try readSubmanifestSettings(gpa, io, tmp.dir)).k);
    }
}

test "cli submanifests: analyze prints the replay on a repository and calls it unavailable under --names" {
    const gpa = std.testing.allocator;
    const io = std.testing.io;
    var tmp = std.testing.tmpDir(.{});
    defer tmp.cleanup();
    try initRepo(gpa, io, tmp.dir);
    try seedManyFiles(gpa, io, tmp.dir, 40);
    for (0..3) |i| {
        const content = try std.fmt.allocPrint(gpa, "rev {d}\n", .{i});
        defer gpa.free(content);
        try writeFile(io, tmp.dir, "f000.txt", content);
        var ci = try runCommitEnv(gpa, io, tmp.dir, .{ .user = "u" }, &.{ "commit", "-m", "c" });
        defer freeResult(gpa, &ci);
        try expectExitDiag(ci.term, 0, ci);
    }

    {
        var r = try runZit(gpa, io, tmp.dir, &.{ "submanifest", "analyze" });
        defer freeResult(gpa, &r);
        try expectExitDiag(r.term, 0, r);
        try std.testing.expect(std.mem.indexOf(u8, r.stdout, "replayed over the last") != null);
        try std.testing.expect(std.mem.indexOf(u8, r.stdout, "flat (actual):") != null);
        try std.testing.expect(std.mem.indexOf(u8, r.stdout, "verdict:") != null);
        try std.testing.expect(std.mem.indexOf(u8, r.stdout, "bootstrap") != null);
    }
    {
        try writeFile(io, tmp.dir, "names.txt", "a.txt\nb.txt\nc.txt\n");
        var r = try runZit(gpa, io, tmp.dir, &.{ "submanifest", "analyze", "--names", "names.txt" });
        defer freeResult(gpa, &r);
        try expectExitDiag(r.term, 0, r);
        try std.testing.expect(std.mem.indexOf(u8, r.stdout, "replay: unavailable with --names") != null);
    }
}

test "cli submanifests §8.1: disabling stops new trees, keeps the pin, and says what it cannot undo" {
    const gpa = std.testing.allocator;
    const io = std.testing.io;
    var tmp = std.testing.tmpDir(.{});
    defer tmp.cleanup();
    try initRepo(gpa, io, tmp.dir);
    try seedManyFiles(gpa, io, tmp.dir, 40);
    {
        var r = try runZit(gpa, io, tmp.dir, &.{ "submanifest", "enable", "--k", "3" });
        defer freeResult(gpa, &r);
        try expectExitDiag(r.term, 0, r);
    }
    {
        var ci = try runCommitEnv(gpa, io, tmp.dir, .{ .user = "u" }, &.{ "commit", "-m", "tree" });
        defer freeResult(gpa, &ci);
        try expectExitDiag(ci.term, 0, ci);
    }
    {
        var r = try runZit(gpa, io, tmp.dir, &.{ "submanifest", "disable" });
        defer freeResult(gpa, &r);
        try expectExitDiag(r.term, 0, r);
        // §8.1 — "Disabling the setting stops the emission of new tree
        // manifests; it cannot retire existing ones."
        try std.testing.expect(std.mem.indexOf(u8, r.stdout, "cannot retire") != null);
    }
    // The pin SURVIVES a disable: it is the repository's content-sharing
    // identity, and clearing it would silently make a later re-enable a §6.4
    // re-tune (an every-leaf rewrite) instead of a resume.
    const after = try readSubmanifestSettings(gpa, io, tmp.dir);
    try std.testing.expect(!after.enabled);
    try std.testing.expectEqual(@as(u8, 3), after.k);

    // …and the next commit is flat again.
    try writeFile(io, tmp.dir, "later.txt", "y\n");
    {
        var add = try runZit(gpa, io, tmp.dir, &.{ "add", "later.txt" });
        defer freeResult(gpa, &add);
        try expectExitDiag(add.term, 0, add);
    }
    var ci2 = try runCommitEnv(gpa, io, tmp.dir, .{ .user = "u" }, &.{ "commit", "-m", "flat again" });
    defer freeResult(gpa, &ci2);
    try expectExitDiag(ci2.term, 0, ci2);
    var m = try parseCheckin(gpa, io, tmp.dir, try checkinHash(ci2.stdout));
    defer m.deinit();
    try std.testing.expectEqual(@as(usize, 0), m.m.s.len);
    try std.testing.expectEqual(@as(usize, 41), m.m.f.len);
}

test "cli submanifests §6.3: an out-of-range pinned k falls back to a flat manifest and reports it" {
    // "on receiving a value outside 1..12 it MUST fall back to emitting flat
    // manifests rather than substitute a parameter of its own, and SHOULD report
    // the fallback to the operator." Reached by writing the bad value straight
    // into the config, because the verb refuses to pin one.
    const gpa = std.testing.allocator;
    const io = std.testing.io;
    var tmp = std.testing.tmpDir(.{});
    defer tmp.cleanup();
    try initRepo(gpa, io, tmp.dir);
    try seedManyFiles(gpa, io, tmp.dir, 40);
    {
        var r = try runZit(gpa, io, tmp.dir, &.{ "submanifest", "enable", "--k", "3" });
        defer freeResult(gpa, &r);
        try expectExitDiag(r.term, 0, r);
    }
    try forcePinnedK(gpa, io, tmp.dir, 13);

    var ci = try runCommitEnv(gpa, io, tmp.dir, .{ .user = "u" }, &.{ "commit", "-m", "fallback" });
    defer freeResult(gpa, &ci);
    try expectExitDiag(ci.term, 0, ci); // the commit SUCCEEDS — a fallback, not a failure
    try std.testing.expect(std.mem.indexOf(u8, ci.stderr, "out of range") != null); // the SHOULD-report
    var m = try parseCheckin(gpa, io, tmp.dir, try checkinHash(ci.stdout));
    defer m.deinit();
    try std.testing.expectEqual(@as(usize, 0), m.m.s.len); // flat, with no substituted parameter
    try std.testing.expectEqual(@as(usize, 40), m.m.f.len);

    // `show` reports the same fallback, from the same decision.
    var r = try runZit(gpa, io, tmp.dir, &.{"submanifest"});
    defer freeResult(gpa, &r);
    try expectExitDiag(r.term, 0, r);
    try std.testing.expect(std.mem.indexOf(u8, r.stdout, "out of range") != null);
    try std.testing.expect(std.mem.indexOf(u8, r.stdout, "commits emit: flat manifests") != null);
}

test "cli submanifests §6.4: a re-tune is manual, needs an explicit value, and warns about the leaf rewrite" {
    // "A re-tune MUST be manual and operator-initiated ... an implementation MAY
    // advise of drift from the analyzed optimum but MUST NOT re-tune
    // automatically." A bare `retune` therefore must NOT consult the analysis
    // pass — it must fail and ask for a value.
    const gpa = std.testing.allocator;
    const io = std.testing.io;
    var tmp = std.testing.tmpDir(.{});
    defer tmp.cleanup();
    try initRepo(gpa, io, tmp.dir);
    try seedManyFiles(gpa, io, tmp.dir, 40);
    {
        var r = try runZit(gpa, io, tmp.dir, &.{ "submanifest", "enable", "--k", "3" });
        defer freeResult(gpa, &r);
        try expectExitDiag(r.term, 0, r);
    }
    {
        var r = try runZit(gpa, io, tmp.dir, &.{ "submanifest", "retune" });
        defer freeResult(gpa, &r);
        try expectExit(r.term, 1);
        try std.testing.expect(std.mem.indexOf(u8, r.stderr, "explicit value") != null);
        // Nothing moved.
        const after = try readSubmanifestSettings(gpa, io, tmp.dir);
        try std.testing.expectEqual(@as(u8, 3), after.k);
    }
    {
        var r = try runZit(gpa, io, tmp.dir, &.{ "submanifest", "retune", "--k", "4" });
        defer freeResult(gpa, &r);
        try expectExitDiag(r.term, 0, r);
        // §6.4 — the next commit "share[s] exactly the sub-manifest artifacts
        // whose bytes are identical under the two full constructions".
        try std.testing.expect(std.mem.indexOf(u8, r.stdout, "unchanged under") != null);
        const after = try readSubmanifestSettings(gpa, io, tmp.dir);
        try std.testing.expectEqual(@as(u8, 4), after.k);
        try std.testing.expect(after.enabled); // a re-tune does not touch the gate
    }
    // `enable --k N` refuses to silently re-pin: that is what `retune` is for.
    var r = try runZit(gpa, io, tmp.dir, &.{ "submanifest", "enable", "--k", "5" });
    defer freeResult(gpa, &r);
    try expectExit(r.term, 1);
    try std.testing.expect(std.mem.indexOf(u8, r.stderr, "re-tune") != null);
    const after = try readSubmanifestSettings(gpa, io, tmp.dir);
    try std.testing.expectEqual(@as(u8, 4), after.k);
}

test "cli submanifests §6.3: the analysis pass reports every k, changes nothing, and never pins" {
    const gpa = std.testing.allocator;
    const io = std.testing.io;
    var tmp = std.testing.tmpDir(.{});
    defer tmp.cleanup();
    try initRepo(gpa, io, tmp.dir);
    try seedManyFiles(gpa, io, tmp.dir, 40);
    {
        var ci = try runCommitEnv(gpa, io, tmp.dir, .{ .user = "u" }, &.{ "commit", "-m", "seed" });
        defer freeResult(gpa, &ci);
        try expectExitDiag(ci.term, 0, ci);
    }

    var r = try runZit(gpa, io, tmp.dir, &.{ "submanifest", "analyze" });
    defer freeResult(gpa, &r);
    try expectExitDiag(r.term, 0, r);
    try std.testing.expect(std.mem.indexOf(u8, r.stdout, "names: 40") != null);
    try std.testing.expect(std.mem.indexOf(u8, r.stdout, "analyzed optimum: k=") != null);
    // §6.5's prediction is printed beside the measurement, so drift between the
    // two is visible rather than assumed away.
    try std.testing.expect(std.mem.indexOf(u8, r.stdout, "§6.5 prediction") != null);
    // §6.3/§6.4 — advisory, and it pins nothing: the settings are untouched.
    const after = try readSubmanifestSettings(gpa, io, tmp.dir);
    try std.testing.expect(!after.enabled);
    try std.testing.expect(!after.pinned());
}

test "cli submanifests §6.3: enabling selects the parameter it analyzes, without an operator value" {
    // "The partition parameter k is selected once, when the enable-submanifests
    // setting is first turned on for a repository, and pinned" — by the writer,
    // minimizing §6.3's objective over the current name set. So the bare verb
    // succeeds, and the value it pins is the value `analyze` reports: both go
    // through one cost pass, and this is what holds them together.
    const gpa = std.testing.allocator;
    const io = std.testing.io;
    var tmp = std.testing.tmpDir(.{});
    defer tmp.cleanup();
    try initRepo(gpa, io, tmp.dir);
    try seedManyFiles(gpa, io, tmp.dir, 40);
    {
        var ci = try runCommitEnv(gpa, io, tmp.dir, .{ .user = "u" }, &.{ "commit", "-m", "seed" });
        defer freeResult(gpa, &ci);
        try expectExitDiag(ci.term, 0, ci);
    }

    // What the advisory pass reports.
    var analyzed_k: u8 = 0;
    {
        var a = try runZit(gpa, io, tmp.dir, &.{ "submanifest", "analyze" });
        defer freeResult(gpa, &a);
        try expectExitDiag(a.term, 0, a);
        const marker = "analyzed optimum: k=";
        const at = std.mem.indexOf(u8, a.stdout, marker) orelse return error.TestUnexpectedResult;
        const rest = a.stdout[at + marker.len ..];
        const end = std.mem.indexOfNone(u8, rest, "0123456789") orelse rest.len;
        analyzed_k = try std.fmt.parseInt(u8, rest[0..end], 10);
        try std.testing.expect(analyzed_k >= 1 and analyzed_k <= 12);
    }

    var r = try runZit(gpa, io, tmp.dir, &.{ "submanifest", "enable" });
    defer freeResult(gpa, &r);
    try expectExitDiag(r.term, 0, r);
    // It says the value was selected rather than defaulted, and what from.
    try std.testing.expect(std.mem.indexOf(u8, r.stdout, "selected by the §6.3 analysis") != null);
    try std.testing.expect(std.mem.indexOf(u8, r.stdout, "40 names") != null);

    const after = try readSubmanifestSettings(gpa, io, tmp.dir);
    try std.testing.expect(after.enabled);
    try std.testing.expect(after.pinned());
    try std.testing.expectEqual(analyzed_k, after.k);

    // §6.3: "k is selected ONCE ... and pinned". A second enable re-measures
    // nothing and leaves the pin where it is — moving it is a re-tune (§6.4).
    var again = try runZit(gpa, io, tmp.dir, &.{ "submanifest", "enable" });
    defer freeResult(gpa, &again);
    try expectExitDiag(again.term, 0, again);
    try std.testing.expect(std.mem.indexOf(u8, again.stdout, "selected by the §6.3 analysis") == null);
    const twice = try readSubmanifestSettings(gpa, io, tmp.dir);
    try std.testing.expectEqual(analyzed_k, twice.k);
}

test "cli submanifests §6.1: the analysis pass measures a name list, and rejects one out of canonical order" {
    // §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, which is how a name set from a repository zit cannot open gets
    // measured. §6.2's precondition (strictly ascending canonical order) is
    // reported rather than silently repaired.
    const gpa = std.testing.allocator;
    const io = std.testing.io;
    var tmp = std.testing.tmpDir(.{});
    defer tmp.cleanup();
    try initRepo(gpa, io, tmp.dir);

    var sorted: std.ArrayList(u8) = .empty;
    defer sorted.deinit(gpa);
    for (0..40) |i| try sorted.print(gpa, "src/f{d:0>3}.zig\n", .{i});
    try writeFile(io, tmp.dir, "names.txt", sorted.items);
    {
        var r = try runZit(gpa, io, tmp.dir, &.{ "submanifest", "analyze", "--names", "names.txt" });
        defer freeResult(gpa, &r);
        try expectExitDiag(r.term, 0, r);
        try std.testing.expect(std.mem.indexOf(u8, r.stdout, "names: 40") != null);
    }
    try writeFile(io, tmp.dir, "unsorted.txt", "b.txt\na.txt\n");
    var r = try runZit(gpa, io, tmp.dir, &.{ "submanifest", "analyze", "--names", "unsorted.txt" });
    defer freeResult(gpa, &r);
    try expectExit(r.term, 1);
    try std.testing.expect(std.mem.indexOf(u8, r.stderr, "canonical order") != null);
}

test "cli submanifest analyze -R: a bare store measures at its tip; settings actions refuse -R" {
    // Goal: the conversion pre-flight. `analyze -R` over a store with NO
    // checkout measures the tip check-in's file set and (with --replay-all)
    // replays the whole history; `enable -R` refuses naming the rule;
    // `--replay-all` outside analyze is a usage error.
    const gpa = std.testing.allocator;
    const io = std.testing.io;
    var tmp = std.testing.tmpDir(.{});
    defer tmp.cleanup();
    try initRepo(gpa, io, tmp.dir);
    try tmp.dir.createDir(io, "src", .default_dir);
    try writeFile(io, tmp.dir, "src/a.zig", "a\n");
    try writeFile(io, tmp.dir, "src/b.zig", "b\n");
    try writeFile(io, tmp.dir, "README", "r\n");
    try addManaged(gpa, io, tmp.dir, &.{ "src/a.zig", "src/b.zig", "README" });
    var c1 = try runCommitEnv(gpa, io, tmp.dir, .{ .user = "u" }, &.{ "commit", "-m", "one" });
    defer freeResult(gpa, &c1);
    try expectExit(c1.term, 0);
    try writeFile(io, tmp.dir, "src/b.zig", "b2\n");
    var c2 = try runCommitEnv(gpa, io, tmp.dir, .{ .user = "u" }, &.{ "commit", "-m", "two" });
    defer freeResult(gpa, &c2);
    try expectExit(c2.term, 0);

    // A BARE copy: the store adopted into a fresh dir, never opened.
    var bare = std.testing.tmpDir(.{});
    defer bare.cleanup();
    try initRepo(gpa, io, bare.dir);
    try adoptStore(gpa, io, tmp.dir, bare.dir);
    const cwd = try std.process.currentPathAlloc(io, gpa);
    defer gpa.free(cwd);
    const bare_abs = try std.fs.path.join(gpa, &.{ cwd, ".zig-cache", "tmp", &bare.sub_path });
    defer gpa.free(bare_abs);
    var away = std.testing.tmpDir(.{});
    defer away.cleanup();

    var an = try runZit(gpa, io, away.dir, &.{ "submanifest", "analyze", "-R", bare_abs, "--replay-all" });
    defer freeResult(gpa, &an);
    try expectExitDiag(an.term, 0, an);
    try std.testing.expect(std.mem.indexOf(u8, an.stdout, "analyzing the tip check-in's file set") != null);
    try std.testing.expect(std.mem.indexOf(u8, an.stdout, "names: 3") != null);

    var en = try runZit(gpa, io, away.dir, &.{ "submanifest", "enable", "-R", bare_abs });
    defer freeResult(gpa, &en);
    try expectExit(en.term, 1);
    try std.testing.expect(std.mem.indexOf(u8, en.stderr, "works with 'analyze' only") != null);

    var ra = try runZit(gpa, io, tmp.dir, &.{ "submanifest", "show", "--replay-all" });
    defer freeResult(gpa, &ra);
    try expectExit(ra.term, 2);
    try std.testing.expect(std.mem.indexOf(u8, ra.stderr, "--replay-all is an 'analyze' option") != null);
}

test "cli submanifest convert: the converted store is delta-encoded as it is written, near its packed size" {
    const gpa = std.testing.allocator;
    const io = std.testing.io;
    var tmp = std.testing.tmpDir(.{});
    defer tmp.cleanup();
    try tmp.dir.createDirPath(io, "flat/src/x");
    try tmp.dir.createDirPath(io, "flat/src/y");
    try tmp.dir.createDirPath(io, "flat/doc");
    var flat = try tmp.dir.openDir(io, "flat", .{});
    defer flat.close(io);
    try initRepo(gpa, io, flat);
    // Forty versions of three files: every blob has a same-path predecessor
    // and every manifest a parent, which is what a delta base needs.
    var text: std.ArrayList(u8) = .empty;
    defer text.deinit(gpa);
    var i: usize = 1;
    while (i <= 40) : (i += 1) {
        try text.print(gpa, "line {d} {s}\n", .{ i, repeat("x", 200) });
        try writeFile(io, flat, "src/x/a.txt", text.items);
        try writeFile(io, flat, "src/y/b.txt", text.items);
        try writeFile(io, flat, "doc/c.txt", text.items);
        if (i == 1) try addManaged(gpa, io, flat, &.{ "src/x/a.txt", "src/y/b.txt", "doc/c.txt" });
        var c = try runCommitEnv(gpa, io, flat, .{ .user = "u" }, &.{ "commit", "-m", "v" });
        defer freeResult(gpa, &c);
        try expectExitDiag(c.term, 0, c);
    }
    var conv = try runZit(gpa, io, tmp.dir, &.{ "submanifest", "convert", "flat", "sub", "--k", "1" });
    defer freeResult(gpa, &conv);
    try expectExitDiag(conv.term, 0, conv);
    var st = try runZit(gpa, io, tmp.dir, &.{ "stat", "-R", "sub" });
    defer freeResult(gpa, &st);
    try expectExitDiag(st.term, 0, st);
    const deltas = try statField(st.stdout, "deltas");
    const before = try statField(st.stdout, "store-bytes");
    // At least as many deltas as the flat source carries: the source's own
    // chains and each manifest's parent are the hints, so nothing is lost.
    var flat_st = try runZit(gpa, io, tmp.dir, &.{ "stat", "-R", "flat" });
    defer freeResult(gpa, &flat_st);
    const flat_deltas = try statField(flat_st.stdout, "deltas");
    try std.testing.expect(deltas > 0 and deltas >= flat_deltas);
    var sub_dir = try tmp.dir.openDir(io, "sub", .{});
    defer sub_dir.close(io);
    var pk = try runZit(gpa, io, sub_dir, &.{"pack"});
    defer freeResult(gpa, &pk);
    try expectExitDiag(pk.term, 0, pk);
    var st2 = try runZit(gpa, io, tmp.dir, &.{ "stat", "-R", "sub" });
    defer freeResult(gpa, &st2);
    const after = try statField(st2.stdout, "store-bytes");
    try std.testing.expect(before < after * 2); // pack trims, it does not transform
}

test "cli submanifest convert: the converter under its proper name — no checkout needed, diagnostics carry the verb, enable says what it does not do" {
    const gpa = std.testing.allocator;
    const io = std.testing.io;
    var tmp = std.testing.tmpDir(.{});
    defer tmp.cleanup();
    try tmp.dir.createDir(io, "src-repo", .default_dir);
    var src = try tmp.dir.openDir(io, "src-repo", .{});
    defer src.close(io);
    try initRepo(gpa, io, src);
    inline for (.{ "alpha", "beta" }) |d| {
        try src.createDir(io, d, .default_dir);
        try writeFile(io, src, d ++ "/one.txt", d ++ " one\n");
        try writeFile(io, src, d ++ "/two.txt", d ++ " two\n");
    }
    try addManaged(gpa, io, src, &.{ "alpha/one.txt", "alpha/two.txt", "beta/one.txt", "beta/two.txt" });
    var c1 = try runCommitEnv(gpa, io, src, .{ .user = "u" }, &.{ "commit", "-m", "one" });
    defer freeResult(gpa, &c1);
    try expectExitDiag(c1.term, 0, c1);

    // From the parent directory, with no checkout of its own.
    var conv = try runZit(gpa, io, tmp.dir, &.{ "submanifest", "convert", "src-repo", "converted", "--k", "2" });
    defer freeResult(gpa, &conv);
    try expectExitDiag(conv.term, 0, conv);
    try std.testing.expect(std.mem.indexOf(u8, conv.stdout, "k=2 pinned by --k") != null);
    try std.testing.expect(std.mem.indexOf(u8, conv.stdout, "1 check-ins re-minted as sub-manifest trees (k=2)") != null);
    try std.testing.expect(std.mem.indexOf(u8, conv.stdout, "store: flat source ") != null);
    try std.testing.expect(std.mem.indexOf(u8, conv.stderr, "import-fossil:") != null); // the phase lines keep the converter's name
    var dst = try tmp.dir.openDir(io, "converted", .{});
    defer dst.close(io);
    var vf = try runZit(gpa, io, dst, &.{"verify"});
    defer freeResult(gpa, &vf);
    try expectExitDiag(vf.term, 0, vf);

    // Usage: missing operands, a source that is neither URL nor store.
    var noargs = try runZit(gpa, io, tmp.dir, &.{ "submanifest", "convert" });
    defer freeResult(gpa, &noargs);
    try expectExit(noargs.term, 2);
    try std.testing.expect(std.mem.indexOf(u8, noargs.stderr, "zit submanifest convert: wants SRC") != null);
    var nosrc = try runZit(gpa, io, tmp.dir, &.{ "submanifest", "convert", "nowhere", "x" });
    defer freeResult(gpa, &nosrc);
    try expectExit(nosrc.term, 1);
    try std.testing.expect(std.mem.indexOf(u8, nosrc.stderr, "zit submanifest convert: 'nowhere' is neither a sync URL nor a zit repository") != null);

    // enable on the flat source says what it does NOT do, and names convert.
    var en = try runZit(gpa, io, src, &.{ "submanifest", "enable", "--k", "2" });
    defer freeResult(gpa, &en);
    try expectExitDiag(en.term, 0, en);
    try std.testing.expect(std.mem.indexOf(u8, en.stdout, "existing check-ins stay flat") != null);
    try std.testing.expect(std.mem.indexOf(u8, en.stdout, "zit submanifest convert SRC DEST") != null);
}