Skip to content
zit Artifact [27bbed8318]
Login

Artifact [27bbed8318]

Artifact 27bbed831895b41f3f2bbf6caf38510cd0c5544448e288e1b03b951c19e6a4cb:


const std = @import("std");
const artifact = @import("zit").artifact;
const support = @import("support.zig");
const addManaged = support.addManaged;
const appendArtifact = support.appendArtifact;
const checkinHash = support.checkinHash;
const expectExit = support.expectExit;
const expectNonzeroExit = support.expectNonzeroExit;
const freeResult = support.freeResult;
const initRepo = support.initRepo;
const runCommitEnv = support.runCommitEnv;
const runZit = support.runZit;
const writeFile = support.writeFile;

// --- tag verb (repo-state §5.1/§5.2, read-only enumeration) ----------------

/// An independent transcription of the `zit tag` §Help block (must match
/// `help.zig`'s `tag_help` byte-for-byte; drift fails the test).
const tag_help_expected =
    \\usage: zit tag list [--raw] [CHECKIN] [--no-cache]
    \\       zit tag add [--raw] [--propagate] NAME CHECKIN [VALUE]
    \\       zit tag cancel [--raw] NAME CHECKIN
    \\
    \\List tags, name a check-in, or attach a property to one. Plain list prints
    \\active singleton symbolic release names across the repository or on
    \\CHECKIN, one per line, sorted. Branch names, raw properties, and
    \\propagating tags are excluded. List --raw prints every active tag with
    \\its stored prefix and value.
    \\
    \\A tag is one of two things, and --raw is what picks between them.
    \\
    \\Without --raw, NAME is a symbolic NAME for one check-in: it resolves to
    \\that check-in everywhere a check-in name is accepted, and it stays put —
    \\unlike a branch name, later check-ins do not inherit it. Use it for
    \\release names. Two check-ins carrying one name make that name ambiguous.
    \\
    \\With --raw, NAME is written verbatim as a PROPERTY, outside name
    \\resolution entirely. Use it for a fact many check-ins may carry — a CI
    \\verdict, a review marker — optionally with a VALUE. Because raw tags are
    \\not names, plain list does not show them; list --raw does.
    \\
    \\cancel retracts a tag from a check-in. It takes the same --raw choice as
    \\the add that created it: cancelling 'v1' and cancelling '--raw v1' are
    \\different tags.
    \\
    \\Names beginning wiki-, tkt-, or event- are refused: fossil crosslinks
    \\wiki pages, tickets, and technotes through them.
    \\
    \\  ls          alias for list
    \\
    \\options:
    \\      --raw        NAME is a raw tag name, not a symbolic check-in name;
    \\                   on list, show every tag with its prefix intact
    \\      --propagate  add only: descendants inherit the tag (mint '*', not
    \\                   '+'). Hazardous without --raw: an inherited symbolic
    \\                   name drifts to the newest descendant carrying it.
    \\      --no-cache  bypass every derived sidecar (the cache AND the rebuild
    \\                  checkpoint) and re-derive from the full log, re-verifying
    \\                  whole-log integrity (the cache is refreshed)
    \\  -R, --repo <path>
    \\                read this repository instead of the one found from the
    \\                current directory; <path> is the directory holding '.zit'
    \\                (or the '.zit' file itself). No working tree is required.
    \\  -h, --help  show this help
    \\
    \\exit status:
    \\  0  success
    \\  1  operational failure (not a repository, unreadable state, a refused
    \\     action) — the diagnostic on stderr names it
    \\  2  usage error (an unknown option or unexpected argument)
    \\
;

/// Builds a raw check-in manifest with an injected T-card block and appends it
/// to `.zit`, returning its 64-hex artifact name (caller frees). The card run
/// C/D/F/<t>/U/Z is a valid check-in skeleton; a malformed `t_block` makes
/// `artifact.parse` reject the whole frame, so the loader skips it. Mirrors
/// `appendRawCheckinWithUppercaseParent`'s hand-framed, self-checksummed shape.
fn appendRawManifestWithT(
    gpa: std.mem.Allocator,
    io: std.Io,
    dir: std.Io.Dir,
    comment: []const u8,
    t_block: []const u8,
) ![]u8 {
    var body_buf: [512]u8 = undefined;
    const body = try std.fmt.bufPrint(
        &body_buf,
        "C {s}\n" ++
            "D 2020-01-01T00:00:00\n" ++
            "F f 0000000000000000000000000000000000000000000000000000000000000000\n" ++
            "{s}" ++
            "U u\n",
        .{ comment, t_block },
    );
    var raw_buf: [576]u8 = undefined;
    @memcpy(raw_buf[0..body.len], body);
    var checksum: [32]u8 = undefined;
    const digest = artifact.selfChecksum(body, &checksum);
    raw_buf[body.len] = 'Z';
    raw_buf[body.len + 1] = ' ';
    @memcpy(raw_buf[body.len + 2 ..][0..digest.len], digest);
    raw_buf[body.len + 34] = '\n';
    return appendArtifact(gpa, io, dir, raw_buf[0 .. body.len + 35]);
}

/// Builds a valid cluster artifact (card run M/Z — a legitimate non-check-in
/// artifact type the crosslink loader admits then skips) and appends it,
/// returning its 64-hex name (caller frees).
fn appendCluster(gpa: std.mem.Allocator, io: std.Io, dir: std.Io.Dir) ![]u8 {
    var body_buf: [128]u8 = undefined;
    const body = try std.fmt.bufPrint(
        &body_buf,
        "M 1111111111111111111111111111111111111111111111111111111111111111\n",
        .{},
    );
    var raw_buf: [192]u8 = undefined;
    @memcpy(raw_buf[0..body.len], body);
    var checksum: [32]u8 = undefined;
    const digest = artifact.selfChecksum(body, &checksum);
    raw_buf[body.len] = 'Z';
    raw_buf[body.len + 1] = ' ';
    @memcpy(raw_buf[body.len + 2 ..][0..digest.len], digest);
    raw_buf[body.len + 34] = '\n';
    return appendArtifact(gpa, io, dir, raw_buf[0 .. body.len + 35]);
}

test "cli tag §2: plain list excludes propagating branch 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 writeFile(io, tmp.dir, "a.txt", "root\n");
    try addManaged(gpa, io, tmp.dir, &.{"a.txt"});

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

    // §2: branch identity is stored as propagating `branch` and `sym-trunk`
    // machinery. Neither is a singleton release name.
    var res = try runZit(gpa, io, tmp.dir, &.{ "tag", "list" });
    defer freeResult(gpa, &res);
    try expectExit(res.term, 0);
    try std.testing.expectEqualStrings("", res.stdout);
    try std.testing.expectEqualStrings("", res.stderr);
}

test "cli tag §5.2: plain CHECKIN list excludes branch machinery" {
    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.txt", "root\n");
    try addManaged(gpa, io, tmp.dir, &.{"a.txt"});

    var commit = try runCommitEnv(gpa, io, tmp.dir, .{ .user = "u" }, &.{ "commit", "-m", "root" });
    defer freeResult(gpa, &commit);
    try expectExit(commit.term, 0);
    const hash = try gpa.dupe(u8, try checkinHash(commit.stdout));
    defer gpa.free(hash);

    // §5.1/§5.2/§6.4: the root carries active propagating `branch` and
    // `sym-trunk` rows, but neither belongs in the singleton release view.
    var res = try runZit(gpa, io, tmp.dir, &.{ "tag", "list", hash });
    defer freeResult(gpa, &res);
    try expectExit(res.term, 0);
    try std.testing.expectEqualStrings("", res.stdout);
    try std.testing.expectEqualStrings("", res.stderr);
}

test "cli tag regression: plain list shows only singleton symbolic release tags" {
    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.txt", "root\n");
    try addManaged(gpa, io, tmp.dir, &.{"a.txt"});

    var commit = try runCommitEnv(gpa, io, tmp.dir, .{ .user = "u" }, &.{ "commit", "-m", "root" });
    defer freeResult(gpa, &commit);
    try expectExit(commit.term, 0);
    const hash = try gpa.dupe(u8, try checkinHash(commit.stdout));
    defer gpa.free(hash);

    for ([_][]const []const u8{
        &.{ "tag", "add", "release-1", hash },
        &.{ "tag", "add", "--raw", "ci-pass", hash, "yes" },
        &.{ "tag", "add", "--propagate", "moving-name", hash },
    }) |args| {
        var add = try runZit(gpa, io, tmp.dir, args);
        defer freeResult(gpa, &add);
        try expectExit(add.term, 0);
        try std.testing.expectEqualStrings("", add.stderr);
    }

    for ([_][]const []const u8{
        &.{ "tag", "list" },
        &.{ "tag", "list", hash },
    }) |args| {
        var plain = try runZit(gpa, io, tmp.dir, args);
        defer freeResult(gpa, &plain);
        try expectExit(plain.term, 0);
        try std.testing.expectEqualStrings("release-1\n", plain.stdout);
        try std.testing.expectEqualStrings("", plain.stderr);
    }

    var raw_names = try runZit(gpa, io, tmp.dir, &.{ "tag", "list", "--raw" });
    defer freeResult(gpa, &raw_names);
    try expectExit(raw_names.term, 0);
    try std.testing.expectEqualStrings(
        "branch\nci-pass\nsym-moving-name\nsym-release-1\nsym-trunk\n",
        raw_names.stdout,
    );
    try std.testing.expectEqualStrings("", raw_names.stderr);

    var raw_checkin = try runZit(gpa, io, tmp.dir, &.{ "tag", "list", "--raw", hash });
    defer freeResult(gpa, &raw_checkin);
    try expectExit(raw_checkin.term, 0);
    try std.testing.expectEqualStrings(
        "branch trunk\nci-pass yes\nsym-moving-name\nsym-release-1\nsym-trunk\n",
        raw_checkin.stdout,
    );
    try std.testing.expectEqualStrings("", raw_checkin.stderr);
}

test "cli tag: a raw tag is a property, not a name — two check-ins carry it with distinct values" {
    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.txt", "root\n");
    try addManaged(gpa, io, tmp.dir, &.{"a.txt"});

    var c1 = try runCommitEnv(gpa, io, tmp.dir, .{ .user = "u" }, &.{ "commit", "-m", "one" });
    defer freeResult(gpa, &c1);
    try expectExit(c1.term, 0);
    const h1 = try gpa.dupe(u8, try checkinHash(c1.stdout));
    defer gpa.free(h1);

    try writeFile(io, tmp.dir, "a.txt", "second\n");
    var c2 = try runCommitEnv(gpa, io, tmp.dir, .{ .user = "u" }, &.{ "commit", "-m", "two" });
    defer freeResult(gpa, &c2);
    try expectExit(c2.term, 0);
    const h2 = try gpa.dupe(u8, try checkinHash(c2.stdout));
    defer gpa.free(h2);

    // The quarry §6 verdict shape: the SAME property on both check-ins, each
    // with its own run reference. Under the old sym-only mint this was the
    // corruption — `ci-pass` became an ambiguous check-in name.
    for ([_][2][]const u8{ .{ h1, "run-41" }, .{ h2, "run-42" } }) |pair| {
        var add = try runZit(gpa, io, tmp.dir, &.{ "tag", "add", "--raw", "ci-pass", pair[0], pair[1] });
        defer freeResult(gpa, &add);
        try expectExit(add.term, 0);
        try std.testing.expectEqualStrings("", add.stderr);
    }

    // Each check-in reports its own value through the raw property view.
    for ([_][2][]const u8{ .{ h1, "ci-pass run-41" }, .{ h2, "ci-pass run-42" } }) |pair| {
        var list = try runZit(gpa, io, tmp.dir, &.{ "tag", "list", "--raw", pair[0] });
        defer freeResult(gpa, &list);
        try expectExit(list.term, 0);
        try std.testing.expect(std.mem.indexOf(u8, list.stdout, pair[1]) != null);
    }

    // ...and the property is NOT a check-in name: resolution never sees it.
    var info = try runZit(gpa, io, tmp.dir, &.{ "info", "ci-pass" });
    defer freeResult(gpa, &info);
    try expectNonzeroExit(info.term);
    try std.testing.expectEqualStrings("", info.stdout);

    // Plain list is the name space, so a property is absent from it; --raw is
    // the read half of the write, and shows it with its prefixless name.
    var names = try runZit(gpa, io, tmp.dir, &.{ "tag", "list" });
    defer freeResult(gpa, &names);
    try expectExit(names.term, 0);
    try std.testing.expect(std.mem.indexOf(u8, names.stdout, "ci-pass") == null);

    var raw = try runZit(gpa, io, tmp.dir, &.{ "tag", "list", "--raw" });
    defer freeResult(gpa, &raw);
    try expectExit(raw.term, 0);
    try std.testing.expect(std.mem.indexOf(u8, raw.stdout, "ci-pass") != null);
    try std.testing.expect(std.mem.indexOf(u8, raw.stdout, "sym-trunk") != null);

    // cancel retracts it from one check-in only.
    var cancel = try runZit(gpa, io, tmp.dir, &.{ "tag", "cancel", "--raw", "ci-pass", h2 });
    defer freeResult(gpa, &cancel);
    try expectExit(cancel.term, 0);

    var after2 = try runZit(gpa, io, tmp.dir, &.{ "tag", "list", "--raw", h2 });
    defer freeResult(gpa, &after2);
    try std.testing.expect(std.mem.indexOf(u8, after2.stdout, "ci-pass") == null);

    var after1 = try runZit(gpa, io, tmp.dir, &.{ "tag", "list", "--raw", h1 });
    defer freeResult(gpa, &after1);
    try std.testing.expect(std.mem.indexOf(u8, after1.stdout, "ci-pass run-41") != null);
}

test "cli tag: bare add still mints a symbolic name (the surface is backward compatible)" {
    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.txt", "root\n");
    try addManaged(gpa, io, tmp.dir, &.{"a.txt"});

    var commit = try runCommitEnv(gpa, io, tmp.dir, .{ .user = "u" }, &.{ "commit", "-m", "root" });
    defer freeResult(gpa, &commit);
    try expectExit(commit.term, 0);
    const hash = try gpa.dupe(u8, try checkinHash(commit.stdout));
    defer gpa.free(hash);

    var add = try runZit(gpa, io, tmp.dir, &.{ "tag", "add", "rel-1", hash });
    defer freeResult(gpa, &add);
    try expectExit(add.term, 0);

    // Still a NAME: it resolves, and it lists prefix-stripped among the names.
    var info = try runZit(gpa, io, tmp.dir, &.{ "info", "rel-1" });
    defer freeResult(gpa, &info);
    try expectExit(info.term, 0);
    try std.testing.expect(std.mem.indexOf(u8, info.stdout, hash) != null);

    var names = try runZit(gpa, io, tmp.dir, &.{ "tag", "list" });
    defer freeResult(gpa, &names);
    try std.testing.expect(std.mem.indexOf(u8, names.stdout, "rel-1") != null);

    // And its cancel is the sym-namespace one: the name stops resolving.
    var cancel = try runZit(gpa, io, tmp.dir, &.{ "tag", "cancel", "rel-1", hash });
    defer freeResult(gpa, &cancel);
    try expectExit(cancel.term, 0);

    var gone = try runZit(gpa, io, tmp.dir, &.{ "info", "rel-1" });
    defer freeResult(gpa, &gone);
    try expectNonzeroExit(gone.term);
}

test "cli tag: refused mints — reserved prefixes, an empty VALUE, and --propagate off add" {
    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.txt", "root\n");
    try addManaged(gpa, io, tmp.dir, &.{"a.txt"});

    var commit = try runCommitEnv(gpa, io, tmp.dir, .{ .user = "u" }, &.{ "commit", "-m", "root" });
    defer freeResult(gpa, &commit);
    try expectExit(commit.term, 0);
    const hash = try gpa.dupe(u8, try checkinHash(commit.stdout));
    defer gpa.free(hash);

    // fossil crosslinks wiki pages, tickets and technotes through these
    // prefixes; minting one here would forge that association.
    for ([_][]const u8{ "wiki-Home", "tkt-1234", "event-abc" }) |name| {
        var res = try runZit(gpa, io, tmp.dir, &.{ "tag", "add", "--raw", name, hash });
        defer freeResult(gpa, &res);
        try expectNonzeroExit(res.term);
        try std.testing.expectEqualStrings("", res.stdout);
        try std.testing.expect(res.stderr.len != 0);
    }

    // §4.7.16's value is `[ SP value ]`: "present but empty" has no spelling.
    var empty = try runZit(gpa, io, tmp.dir, &.{ "tag", "add", "--raw", "unminted-prop", hash, "" });
    defer freeResult(gpa, &empty);
    try expectNonzeroExit(empty.term);
    try std.testing.expectEqualStrings("", empty.stdout);

    // A flag that cannot apply is named, never accepted and ignored (exit 2).
    var prop = try runZit(gpa, io, tmp.dir, &.{ "tag", "cancel", "--propagate", "unminted-prop", hash });
    defer freeResult(gpa, &prop);
    try expectExit(prop.term, 2);
    try std.testing.expectEqualStrings("", prop.stdout);

    // None of the refusals minted anything.
    var raw = try runZit(gpa, io, tmp.dir, &.{ "tag", "list", "--raw" });
    defer freeResult(gpa, &raw);
    try expectExit(raw.term, 0);
    for ([_][]const u8{ "wiki-", "tkt-", "event-", "unminted-prop" }) |needle| {
        try std.testing.expect(std.mem.indexOf(u8, raw.stdout, needle) == null);
    }
}

test "cli tag B-tag-11: --help / -h / 'help tag' print the verbatim help (stdout, exit 0)" {
    const gpa = std.testing.allocator;
    const io = std.testing.io;
    var tmp = std.testing.tmpDir(.{});
    defer tmp.cleanup();

    for ([_][]const u8{ "--help", "-h" }) |flag| {
        var res = try runZit(gpa, io, tmp.dir, &.{ "tag", flag });
        defer freeResult(gpa, &res);
        try expectExit(res.term, 0);
        try std.testing.expectEqualStrings(tag_help_expected, res.stdout);
        try std.testing.expectEqualStrings("", res.stderr);
    }
    var routed = try runZit(gpa, io, tmp.dir, &.{ "help", "tag" });
    defer freeResult(gpa, &routed);
    try expectExit(routed.term, 0);
    try std.testing.expectEqualStrings(tag_help_expected, routed.stdout);
}

test "cli tag B-tag-12: no subcommand is a usage error (exit 2, stderr, empty stdout)" {
    const gpa = std.testing.allocator;
    const io = std.testing.io;
    var tmp = std.testing.tmpDir(.{});
    defer tmp.cleanup();

    var res = try runZit(gpa, io, tmp.dir, &.{"tag"});
    defer freeResult(gpa, &res);
    try expectExit(res.term, 2);
    try std.testing.expectEqualStrings("", res.stdout);
    try std.testing.expectEqualStrings(
        "zit tag: no subcommand given\ntry 'zit tag --help'\n",
        res.stderr,
    );
}

test "cli tag B-tag-13: an unknown subcommand is a usage error (exit 2, stderr, empty stdout)" {
    const gpa = std.testing.allocator;
    const io = std.testing.io;
    var tmp = std.testing.tmpDir(.{});
    defer tmp.cleanup();

    // Each stand-in for "not a subcommand" has in turn become one: `add` at
    // REGRESSION B6, `cancel` at the tag rework. `find` is fossil's, and is not ours.
    var res = try runZit(gpa, io, tmp.dir, &.{ "tag", "find" });
    defer freeResult(gpa, &res);
    try expectExit(res.term, 2);
    try std.testing.expectEqualStrings("", res.stdout);
    try std.testing.expectEqualStrings(
        "zit tag: unknown subcommand 'find'\ntry 'zit tag --help'\n",
        res.stderr,
    );
}

test "cli tag B-tag-14: an unresolvable CHECKIN fails exit 1 on stderr, empty stdout" {
    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 res = try runZit(gpa, io, tmp.dir, &.{ "tag", "list", "nosuchname" });
    defer freeResult(gpa, &res);
    try expectExit(res.term, 1);
    try std.testing.expectEqualStrings("", res.stdout);
    try std.testing.expectEqualStrings("zit tag: check-in 'nosuchname' not found\n", res.stderr);
}

test "cli tag B-tag-15: 'tag' is listed in the command help and suggested for a near-miss" {
    const gpa = std.testing.allocator;
    const io = std.testing.io;
    var tmp = std.testing.tmpDir(.{});
    defer tmp.cleanup();

    var help = try runZit(gpa, io, tmp.dir, &.{"help"});
    defer freeResult(gpa, &help);
    try expectExit(help.term, 0);
    try std.testing.expect(std.mem.indexOf(u8, help.stdout, "tag") != null);

    var typo = try runZit(gpa, io, tmp.dir, &.{"tags"});
    defer freeResult(gpa, &typo);
    try expectExit(typo.term, 2);
    try std.testing.expect(std.mem.indexOf(u8, typo.stderr, "did you mean 'tag'?") != null);
}

test "cli tag B-tag-16 (ls): the ls alias equals list; data on stdout only" {
    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.txt", "root\n");
    try addManaged(gpa, io, tmp.dir, &.{"a.txt"});

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

    var list = try runZit(gpa, io, tmp.dir, &.{ "tag", "list" });
    defer freeResult(gpa, &list);
    var ls = try runZit(gpa, io, tmp.dir, &.{ "tag", "ls" });
    defer freeResult(gpa, &ls);
    try expectExit(ls.term, 0);
    try std.testing.expectEqualStrings("", ls.stdout);
    try std.testing.expectEqualStrings("", ls.stderr);
    try std.testing.expectEqualStrings(list.stdout, ls.stdout);
}

test "cli tag B-tag-17: an unborn repository lists no tags (empty stdout, exit 0)" {
    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 res = try runZit(gpa, io, tmp.dir, &.{ "tag", "list" });
    defer freeResult(gpa, &res);
    try expectExit(res.term, 0);
    try std.testing.expectEqualStrings("", res.stdout);
    try std.testing.expectEqualStrings("", res.stderr);
}

test "cli tag §5.1: an accepted self-tag T-card surfaces in the raw view" {
    const gpa = std.testing.allocator;
    const io = std.testing.io;
    var tmp = std.testing.tmpDir(.{});
    defer tmp.cleanup();
    try initRepo(gpa, io, tmp.dir);

    // Anchors the raw skeleton: a valid `*sym-alpha` self-tag (§5.1 propagate
    // sign) crosslinks and surfaces with its stored prefix under --raw. The
    // rejection tests below reuse this skeleton, changing only the T-card.
    const hash = try appendRawManifestWithT(gpa, io, tmp.dir, "tagged", "T *sym-alpha *\n");
    defer gpa.free(hash);

    var res = try runZit(gpa, io, tmp.dir, &.{ "tag", "list", "--raw", hash });
    defer freeResult(gpa, &res);
    try expectExit(res.term, 0);
    try std.testing.expectEqualStrings("sym-alpha\n", res.stdout);
    try std.testing.expectEqualStrings("", res.stderr);
}

test "cli tag §5.1: a T-card with a bad leading char contributes no tag" {
    const gpa = std.testing.allocator;
    const io = std.testing.io;
    var tmp = std.testing.tmpDir(.{});
    defer tmp.cleanup();
    try initRepo(gpa, io, tmp.dir);

    // §5.1: a leading char other than +/-/* is a fatal crosslink error, so the
    // manifest is rejected at parse and never becomes a resolvable check-in.
    const hash = try appendRawManifestWithT(gpa, io, tmp.dir, "bad", "T Qsym-bogus *\n");
    defer gpa.free(hash);

    var res = try runZit(gpa, io, tmp.dir, &.{ "tag", "list", hash });
    defer freeResult(gpa, &res);
    try expectExit(res.term, 1);
    try std.testing.expectEqualStrings("", res.stdout);
    try std.testing.expect(std.mem.indexOf(u8, res.stderr, "not found") != null);
}

test "cli tag §4.3: an unsigned T-card name contributes no tag" {
    const gpa = std.testing.allocator;
    const io = std.testing.io;
    var tmp = std.testing.tmpDir(.{});
    defer tmp.cleanup();
    try initRepo(gpa, io, tmp.dir);

    // §4.3: a tag name lacking a -, +, or * prefix is rejected at parse time.
    const hash = try appendRawManifestWithT(gpa, io, tmp.dir, "bad", "T sym-bogus *\n");
    defer gpa.free(hash);

    var res = try runZit(gpa, io, tmp.dir, &.{ "tag", "list", hash });
    defer freeResult(gpa, &res);
    try expectExit(res.term, 1);
    try std.testing.expectEqualStrings("", res.stdout);
    try std.testing.expect(std.mem.indexOf(u8, res.stderr, "not found") != null);
}

test "cli tag §4.3: an all-hex tag name contributes no tag" {
    const gpa = std.testing.allocator;
    const io = std.testing.io;
    var tmp = std.testing.tmpDir(.{});
    defer tmp.cleanup();
    try initRepo(gpa, io, tmp.dir);

    // §4.3: a tag name that is entirely hexadecimal after prefix removal is
    // rejected (it must stay distinguishable from a hash prefix).
    const hash = try appendRawManifestWithT(gpa, io, tmp.dir, "bad", "T +deadbeef *\n");
    defer gpa.free(hash);

    var res = try runZit(gpa, io, tmp.dir, &.{ "tag", "list", hash });
    defer freeResult(gpa, &res);
    try expectExit(res.term, 1);
    try std.testing.expectEqualStrings("", res.stdout);
    try std.testing.expect(std.mem.indexOf(u8, res.stderr, "not found") != null);
}

test "cli tag §4.3: a non-ascending T-card manifest applies none of its tags" {
    const gpa = std.testing.allocator;
    const io = std.testing.io;
    var tmp = std.testing.tmpDir(.{});
    defer tmp.cleanup();
    try initRepo(gpa, io, tmp.dir);

    // §4.3: a T-card sequence not strictly ascending by (name, uuid) is
    // rejected, and no crosslink effect is applied on the manifest's behalf.
    const hash = try appendRawManifestWithT(gpa, io, tmp.dir, "bad", "T *sym-zebra *\nT *sym-apple *\n");
    defer gpa.free(hash);

    var res = try runZit(gpa, io, tmp.dir, &.{ "tag", "list", hash });
    defer freeResult(gpa, &res);
    try expectExit(res.term, 1);
    try std.testing.expectEqualStrings("", res.stdout);
    try std.testing.expect(std.mem.indexOf(u8, res.stderr, "not found") != null);
}

test "cli tag §4.2: a non-control/manifest artifact contributes no tag" {
    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.txt", "root\n");
    try addManaged(gpa, io, tmp.dir, &.{"a.txt"});

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

    // §4.2 step 2: the tag loop runs only for control/manifest/event artifacts;
    // a cluster is another type, so it contributes no tag. Plain listing stays
    // empty because the real commit contributes branch machinery, not a
    // singleton release tag.
    const cluster = try appendCluster(gpa, io, tmp.dir);
    defer gpa.free(cluster);

    var res = try runZit(gpa, io, tmp.dir, &.{ "tag", "list" });
    defer freeResult(gpa, &res);
    try expectExit(res.term, 0);
    try std.testing.expectEqualStrings("", res.stdout);
    try std.testing.expectEqualStrings("", res.stderr);
}