Skip to content
zit Artifact [eaa131ea08]
Login

Artifact [eaa131ea08]

Artifact eaa131ea08b7572a3961326d1fb1fd02d309a46dc85aec51098b711ae3a98380:


//! `zit shun`: record, list, sign and cancel shuns and erasures, and reclaim
//! the shunned bytes.

const std = @import("std");
const ErasureAppend = @import("session_erasures.zig").ErasureAppend;
const PackStats = @import("pack.zig").PackStats;
const applySessionErasures = @import("session_erasures.zig").applySessionErasures;
const artifact = zit.artifact;
const checkout = @import("zit").checkout;
const cli = @import("zit").cli;
const diagnostics = @import("../cli/diagnostics.zig");
const digestToWireName = zit.digest_name.digestToWireName;
const digest_len = zit.digest_name.digest_len;
const help_pages = @import("../cli/help.zig");
const holdsBytes = @import("session_erasures.zig").holdsBytes;
const lockRewrite = @import("pack.zig").lockRewrite;
const logProjectCode = @import("session_erasures.zig").logProjectCode;
const logstore = @import("zit").logstore;
const openErasureAppend = @import("session_erasures.zig").openErasureAppend;
const packOpenReadOnly = @import("sync_test_support.zig").packOpenReadOnly;
const packOpenWritable = @import("sync_test_support.zig").packOpenWritable;
const packSeedFullStore = @import("sync_test_support.zig").packSeedFullStore;
const pack_tmp_filename = @import("pack.zig").pack_tmp_filename;
const plural = @import("sync_dialogue.zig").plural;
const pluralEs = @import("sync_dialogue.zig").pluralEs;
const reasonOf = diagnostics.reasonOf;
const repeat = @import("zit").repeat;
const repoReadFail = diagnostics.repoReadFail;
const repo_filename = zit.repo_filename;
const rewriteAndSwap = @import("pack.zig").rewriteAndSwap;
const rewriteBusyFail = @import("pack.zig").rewriteBusyFail;
const rewrite_lock_name = @import("pack.zig").rewrite_lock_name;
const shunHexToDigest = @import("session_erasures.zig").shunHexToDigest;
const shun_help = help_pages.shun_help;
const stateOom = diagnostics.stateOom;
const storage = @import("zit").storage;
const storeReadFail = diagnostics.storeReadFail;
const tailChangedFail = @import("pack.zig").tailChangedFail;
const zit = @import("zit");

// ---------------------------------------------------------------------------
// `zit shun` — record artifacts in this repository's shun table and, by default,
// remove their bytes in the same operation.
//
// NO DRAFT SPECIFIES THIS VERB. sync §3.3 (docs/rfcs/
// draft-fossil-sync-protocol-00.txt L518-519) defines the repository shun table
// as "a persistent, repository-local set keyed by complete artifact name",
// L520-521 grants that "Local administration MAY add or remove names", and
// L527-530 makes the set mask the phantom scan. That is the whole of it: no
// draft names a command, an option, a report, a refusal, or the operation that
// removes a shunned artifact's bytes. Everything below — the refuse-by-default
// policy, the `--force` gate, the unconditional current-checkout stop, the
// per-type diagnostics — is this implementation's decision, and the choices are
// stated at the point that makes them rather than attributed to a section.
//
// The one advisory the plan of record cites for sub-manifests cannot be
// implemented or quoted here: there is no `submanifest` variant in
// `artifact.ArtifactType` on this branch (it runs manifest=1 .. forum=8) and no
// sub-manifest draft in docs/rfcs/. `shunConsequence`'s switch is total over
// that enum, so the day a ninth type lands the compiler demands its diagnostic
// — including the wider-blast-radius warning a sub-manifest deserves.
// ---------------------------------------------------------------------------

pub const NameSet = zit.pack.NameSet;

/// What a `zit shun` run will do about one hash the operator named. Split into
/// three groups by consequence, because the runner acts on the group, not the
/// member: the three `blocking` values stop the whole invocation before anything
/// durable happens; `remove`/`absent` each need a new tombstone; `reclaim` needs
/// no row but still has bytes to remove; `already` needs nothing at all.
const ShunDisposition = enum {
    /// Held here: the rewrite drops its bytes and records its tombstone.
    remove,
    /// Already in the set from an earlier `--defer`, but the BYTES ARE STILL HERE:
    /// no new row to write, and yet the removal the operator just asked for has
    /// genuinely not happened. Grouping this with `already` is what would make
    /// `zit shun --force H` after `zit shun --defer --force H` print "nothing to
    /// do" and exit 0 with the content still readable — the worst sentence this
    /// verb could produce, on the one path where an operator is acting under an
    /// order. So it is its own disposition: no tombstone, but a rewrite.
    reclaim,
    /// Not held here: the tombstone is recorded and nothing is reclaimed. A
    /// pre-emptive shun is meaningful and free — sync §3.3 L553-556 filters the
    /// phantom scan on the set, so a name recorded before the artifact ever
    /// arrives is never requested.
    absent,
    /// Already in the set AND already gone: a true no-op. `putShun` is idempotent
    /// as set membership, so the durable row keeps the epoch and reason it was
    /// written with.
    already,

    /// The manifest of the current checkout. REFUSED, with no `--force`
    /// override — the one hard stop.
    current_checkout,
    /// Not a lowercase-hex artifact-name prefix at all.
    not_a_name,
    /// An abbreviated prefix matching no stored artifact. Refused rather than
    /// recorded: the shun table is keyed by COMPLETE name, so a prefix cannot be
    /// completed and a row keyed on one would name nothing.
    unresolved,
    /// A prefix matching more than one stored artifact.
    ambiguous,

    /// Whether this disposition stops the whole invocation before any durable
    /// write. A total switch so a value added later cannot silently join the
    /// permissive group.
    fn blocks(self: ShunDisposition) bool {
        return switch (self) {
            .current_checkout, .not_a_name, .unresolved, .ambiguous => true,
            .remove, .reclaim, .absent, .already => false,
        };
    }

    /// Whether this disposition needs a new tombstone row.
    fn records(self: ShunDisposition) bool {
        return switch (self) {
            .remove, .absent => true,
            .reclaim, .already, .current_checkout, .not_a_name, .unresolved, .ambiguous => false,
        };
    }

    /// Whether this disposition has BYTES for the rewrite to drop. Separate from
    /// `records` precisely because the two are not the same question: `absent`
    /// records without removing and `reclaim` removes without recording.
    fn reclaims(self: ShunDisposition) bool {
        return switch (self) {
            .remove, .reclaim => true,
            .absent, .already, .current_checkout, .not_a_name, .unresolved, .ambiguous => false,
        };
    }
};

/// One hash the operator named, resolved. `name` is the full lowercase-hex
/// artifact name — or, for the three unresolvable dispositions, the operator's
/// own token, which is all there is to name. `digest` is the raw binary key the
/// shun table and the pack filter both use, empty when there is none. `kind` is
/// null for an opaque blob (an artifact that does not parse as a structural one),
/// which is a first-class answer here exactly as it is for `zit artifact`.
const ShunTarget = struct {
    name: []const u8,
    digest: []const u8 = &.{},
    kind: ?artifact.ArtifactType = null,
    disposition: ShunDisposition,
};

/// The report label for a target's type. Structural artifacts use §5.1 Table 3's
/// external name (`artifact.ArtifactType.externalName`), the same vocabulary
/// `zit artifact` prints, so an operator sees one word per type across the CLI;
/// a blob is "file", matching `zit artifact`'s "type: file".
fn shunTypeLabel(kind: ?artifact.ArtifactType) []const u8 {
    const t = kind orelse return "file";
    return t.externalName();
}

/// The consequence of removing an artifact of this type, in one clause.
///
/// A TOTAL switch on `artifact.ArtifactType`, deliberately: the alternative is a
/// default arm, and a type added later would then get no diagnostic at all while
/// the operator was told the removal was safe. The six types that all lose the
/// same thing share one arm rather than repeating one sentence six times.
///
/// NO COUNTS, and that is a deliberate reduction from the intended report shape.
/// "N descendant check-ins become unresolvable" needs a public descendants
/// accessor over `repostate`'s child map plus a BFS, and "src/secret.key, in 6
/// check-ins" needs a reverse F-card index that exists nowhere in this tree —
/// producing either means decoding every manifest in the repository on the
/// refusal path, which is supposed to be the cheap path. The clause without the
/// count states the same consequence; the count is worth revisiting only
/// alongside the index that would make it cheap.
fn shunConsequence(kind: ?artifact.ArtifactType) []const u8 {
    const t = kind orelse return "file content; every check-in listing it loses that file";
    return switch (t) {
        .manifest => "a check-in; its descendants become unresolvable",
        .cluster => "sync housekeeping only; regenerable",
        .submanifest => "part of a check-in's file list; every check-in whose tree names it stops enumerating",
        .control, .wiki, .ticket, .attachment, .event, .forum => "structural content; what it renders stops rendering",
    };
}

/// Render the hard stops: one line per blocking target, then nothing happens.
/// Every arm of the switch prints, including the non-blocking ones — a renderer
/// with an `unreachable` arm would be undefined behavior in `ReleaseFast`, which
/// is a poor trade for a line of output nobody should ever see.
fn renderShunBlockers(err: *std.Io.Writer, targets: []const ShunTarget) void {
    for (targets) |t| switch (t.disposition) {
        .current_checkout => {
            err.print("zit shun: {s} is the check-in this checkout is on; refusing\n", .{t.name}) catch {};
            err.writeAll("run 'zit update' to a different check-in first\n") catch {};
        },
        .not_a_name => err.print("zit shun: '{s}' is not an artifact name\n", .{t.name}) catch {},
        .unresolved => err.print(
            "zit shun: no artifact matches '{s}'; give the complete name to shun a hash this repository does not hold\n",
            .{t.name},
        ) catch {},
        .ambiguous => err.print("zit shun: hash '{s}' is ambiguous\n", .{t.name}) catch {},
        .remove, .reclaim, .absent, .already => {},
    };
}

/// How many rows already in `src`'s shun table still hold bytes that this run's
/// rewrite would drop, EXCLUDING the ones `targets` names (those are counted as
/// `.reclaim` targets and listed by name, so counting them here too would double
/// them). This is the clause the refusal — the consent gate — would otherwise be
/// silent about: `renderShunStats` is honest that `dropped` can exceed `recorded`,
/// but that honesty arrives after the deletion.
fn deferredStillHeld(src: *const logstore.LogStore, targets: []const ShunTarget) usize {
    var n: usize = 0;
    const all = src.shunList();
    rows: for (all, 0..) |row, i| {
        if (!src.isShunned(row.hash) or !holdsBytes(src, row.hash)) continue;
        // A name folds several rows (an erasure and its cancel); count it once.
        for (all[0..i]) |prev| {
            if (std.mem.eql(u8, prev.hash, row.hash)) continue :rows;
        }
        for (targets) |t| {
            if (std.mem.eql(u8, t.digest, row.hash)) continue :rows;
        }
        n += 1;
    }
    return n;
}

/// Render the default refusal: what this run would do, then stop. The register is
/// `clean`'s (`cleanRefuse` in cmd/tracking.zig) — the counts and the word
/// "refusing" in ONE line, so an operator learns nothing happened before reading
/// six lines of inventory, then the flag that proceeds, and never a prompt.
///
/// THREE counts, because they answer three different questions and only the first
/// used to be stated. How many rows become permanent (`recording` — including the
/// pre-emptive ones, which remove nothing). How much content this invocation's own
/// targets destroy (`removing` — which is NOT a subset of `recording`: a hash
/// shunned earlier with `--defer` records nothing and still has bytes to lose).
/// And `deferred_held`, the content the same rewrite reclaims from rows an EARLIER
/// run recorded — collateral the operator never named, which the success line
/// already admits to and the consent gate must not hide.
///
/// `defer_reclaim` IS A PARAMETER BECAUSE THE TWO RUNS ARE DIFFERENT OPERATIONS,
/// and this block's whole job is to state the operation accurately before an
/// irreversible act. A `--defer` run removes nothing NOW: describing it as "would
/// be permanently removed" overstates it, the `deferred_held` collateral clause is
/// about a rewrite that is not going to happen, and — worst — a suggestion of
/// `zit shun --force` would have an operator who copies it escalate a deferred
/// tombstone into a full-store reclaim of the whole union set, including collateral
/// the run never named. The suggested command is therefore always the one the
/// operator actually asked for, plus `--force`.
fn renderShunRefusal(
    err: *std.Io.Writer,
    targets: []const ShunTarget,
    deferred_held: usize,
    defer_reclaim: bool,
) void {
    var recording: usize = 0;
    var removing: usize = 0;
    for (targets) |t| {
        if (t.disposition.records()) recording += 1;
        if (t.disposition.reclaims()) removing += 1;
    }
    err.writeAll("zit shun: ") catch {};
    if (recording == 0) {
        err.writeAll("no new hash would be recorded") catch {};
    } else {
        err.print("{d} hash{s} would be shunned in this repository", .{ recording, pluralEs(recording) }) catch {};
    }
    if (removing == 0) {
        err.writeAll("; nothing you named holds content to remove") catch {};
    } else if (defer_reclaim) {
        // Named, still held, and deliberately NOT reclaimed by this run. "stays
        // reconstructible" rather than merely "unreclaimed": the mask is on the
        // name, so the plaintext is still materialisable through any surviving
        // delta, which is precisely what an operator under a takedown order would
        // otherwise assume they had already prevented.
        err.print(
            "; the bytes of {d} artifact{s} stay on disk and stay reconstructible until 'zit pack'",
            .{ removing, plural(removing) },
        ) catch {};
    } else {
        err.print("; {d} artifact{s} would be permanently removed", .{ removing, plural(removing) }) catch {};
    }
    // Collateral of the REWRITE, so it is silent on the deferred path: there is no
    // rewrite in a `--defer` run and those rows keep their bytes untouched.
    if (deferred_held != 0 and !defer_reclaim) {
        err.print(
            "; the same rewrite also removes {d} artifact{s} shunned earlier and not yet reclaimed",
            .{ deferred_held, plural(deferred_held) },
        ) catch {};
    }
    err.writeAll("; refusing without --force:\n\n") catch {};
    for (targets) |t| switch (t.disposition) {
        .remove => err.print("  {s}  {s}  {s}\n", .{
            t.name,
            shunTypeLabel(t.kind),
            shunConsequence(t.kind),
        }) catch {},
        .reclaim => if (defer_reclaim) {
            err.print("  {s}  {s}  already shunned; content still here and stays\n", .{
                t.name,
                shunTypeLabel(t.kind),
            }) catch {};
        } else {
            err.print("  {s}  {s}  already shunned; content still here and would be removed\n", .{
                t.name,
                shunTypeLabel(t.kind),
            }) catch {};
        },
        .absent => err.print("  {s}  recorded only (not present in this repository)\n", .{t.name}) catch {},
        .already => err.print("  {s}  already shunned; content already gone\n", .{t.name}) catch {},
        // Unreachable in practice (`renderShunBlockers` ran and the caller
        // exited), but printed rather than asserted: see `renderShunBlockers`.
        .current_checkout, .not_a_name, .unresolved, .ambiguous => err.print(
            "  {s}  cannot be shunned\n",
            .{t.name},
        ) catch {},
    };
    err.writeAll(
        \\
        \\This is irreversible: zit undo does not recover a shun, and the content
        \\cannot be re-fetched from a peer.
        \\
    ) catch {};
    err.print("run 'zit shun {s}--force <HASH>...' to proceed\n", .{
        if (defer_reclaim) "--defer " else "",
    }) catch {};
}

/// One human line summarizing a completed reclaiming shun, in `renderPackStats`'s
/// register. `dropped` can EXCEED `shuns_recorded`, because the same rewrite also
/// reclaims any shun that was deferred earlier — an operator must be told that
/// rather than left to infer it from a byte count. Split out so the exact wording
/// is unit tested without a filesystem.
///
/// EVERY NUMBER HERE COMES FROM THE PACK, none from the caller's intent — which is
/// the whole reason `PackStats.shuns_recorded` exists. The rows this run meant to
/// write and the rows the new generation actually holds are two different facts,
/// and the one an operator is owed after a takedown is the second. `packLog`'s
/// row-count gate makes them equal or fails the pack; if that gate were ever
/// weakened, this line would under-report rather than over-report.
fn renderShunStats(out: *std.Io.Writer, stats: PackStats) void {
    // `dropped` is counted among the source frames walked, so this subtraction
    // cannot underflow. Asserted anyway, and precisely because it is a tautology:
    // it is the only unchecked arithmetic in this verb's reporting, and an
    // underflow would print an absurd remaining count rather than trap.
    std.debug.assert(stats.dropped <= stats.artifacts);
    out.print("shunned: {d} hash{s} recorded, {d} artifact{s} removed, {d} -> {d} remaining, {d} -> {d} bytes\n", .{
        stats.shuns_recorded,
        pluralEs(stats.shuns_recorded),
        stats.dropped,
        plural(stats.dropped),
        stats.artifacts,
        stats.artifacts - stats.dropped,
        stats.bytes_before,
        stats.bytes_after,
    }) catch {};
}

/// `--defer`'s success line. It does NOT promise a byte count: nothing on this
/// path measured one, and the only honest number would require doing the rewrite
/// the operator just declined.
///
/// `recorded == 0` with `holding != 0` is the re-`--defer` of a hash already
/// deferred: no row to add, and yet content still to lose. Saying "0 hashes
/// recorded" there would read as a no-op on a repository that still holds the
/// bytes, so that case gets its own clause naming what is left.
///
/// `repo` is the `-R` the run was given, repeated in the hint so the command
/// it names reaches the same store from the same directory.
fn renderShunDeferred(out: *std.Io.Writer, recorded: usize, holding: usize, repo: ?[]const u8) void {
    if (recorded == 0) {
        out.print(
            "shunned: no new hash to record; {d} artifact{s} still hold{s} content; ",
            .{ holding, plural(holding), if (holding == 1) "s" else "" },
        ) catch {};
    } else {
        out.print("shunned: {d} hash{s} recorded; ", .{ recorded, pluralEs(recorded) }) catch {};
    }
    if (repo) |path| {
        out.print("run 'zit pack -R {s}' to reclaim the space\n", .{path}) catch {};
    } else out.writeAll("run 'zit pack' to reclaim the space\n") catch {};
}

/// The success line for a run with tombstones to write and NOTHING to reclaim —
/// the purely pre-emptive shun. It takes the append path rather than the rewrite
/// (see `runShun`), so there is no byte count to report and, more to the point,
/// nothing was removed: a line ending in a store that had GROWN would be the
/// wrong thing to print under the word "shunned".
fn renderShunRecordedOnly(out: *std.Io.Writer, recorded: usize) void {
    out.print(
        "shunned: {d} hash{s} recorded; none is held here, so nothing was removed\n",
        .{ recorded, pluralEs(recorded) },
    ) catch {};
}

/// `--porcelain`: one `ACTION HASH` line per named hash, in argument order, after
/// the run has done what it reports — the shape `zit frames` uses for its header
/// and trailer lines (a keyword, then fields), so a forge logs exactly what
/// happened to each hash without parsing prose. `rewrote` is whether this run's
/// rewrite swapped in a new generation; it decides whether held content was
/// `reclaimed` or is still `deferred`.
///
///   reclaimed  the bytes were removed (the row is new, or was deferred before)
///   deferred   the row is recorded; the bytes stay on disk until `zit pack`
///   recorded   the row is recorded; nothing was held here to remove
///   gone       already shunned and already removed; nothing was done
///
/// Collateral the same rewrite reclaims from rows an earlier run deferred is not
/// listed: those hashes were reported `deferred` by the run that named them.
fn renderShunPorcelain(out: *std.Io.Writer, targets: []const ShunTarget, rewrote: bool) void {
    for (targets) |t| {
        const action: []const u8 = switch (t.disposition) {
            .remove, .reclaim => if (rewrote) "reclaimed" else "deferred",
            .absent => "recorded",
            .already => "gone",
            // A blocking target stops the run before anything is reported;
            // named rather than `unreachable` for `renderShunBlockers`' reason.
            .current_checkout, .not_a_name, .unresolved, .ambiguous => "refused",
        };
        out.print("{s} {s}\n", .{ action, t.name }) catch {};
    }
}

/// Render shun's failure `err` as `zit shun: <reason>` on stderr, exit 1. On
/// every path that reaches this the store is byte-identical: either nothing was
/// written yet, or every write went to the temp the rewrite's `defer` deletes.
fn shunFail(s: cli.Streams, err: anyerror) cli.Exit {
    s.err.print("zit shun: {s}\n", .{reasonOf(err)}) catch {};
    return .failure;
}

/// The two shun-row rejections (`BadKey`, `ReasonTooLong`) that are unreachable by
/// construction here — every digest passed `isCompleteDigest` and every reason
/// passed the length gate — given a REAL phrase rather than left to `reasonOf`,
/// whose `else` arm renders both as "input/output error". Being unreachable is
/// exactly why the phrase matters: if one ever fires it is a key-width or
/// reason-length bug, and telling the operator their disk failed would send them
/// looking at hardware. Nothing durable has happened on either path.
fn shunRowBug(s: cli.Streams) cli.Exit {
    s.err.writeAll("zit shun: internal error: a shun row was rejected as malformed; nothing was changed\n") catch {};
    return .failure;
}

/// `shunAppendRows`' failure, with its two unreachable-by-construction arms routed
/// to `shunRowBug` instead of through `reasonOf`'s "input/output error" catch-all.
/// A torn append is truncated by the log's own recovery, so a failure here leaves
/// the shun simply absent, never half present.
///
/// `TailChanged` and `RewriteBusy` join the set for the reason `RewriteError`
/// carries them: neither is a failure of the append at all, both leave the store
/// exactly as it was, and both have the same operator-facing meaning here as they
/// do on the rewrite path — which is why they route to the SAME two diagnostics
/// rather than growing a second pair of sentences for the append.
const ShunAppendError = logstore.OpenError || logstore.ShunError || logstore.CommitError ||
    error{ TailChanged, RewriteBusy, StoreBusy };

fn shunAppendFail(s: cli.Streams, err: ShunAppendError) cli.Exit {
    return switch (err) {
        error.OutOfMemory => stateOom(s, "shun"),
        error.BadKey, error.ReasonTooLong => shunRowBug(s),
        error.TailChanged => tailChangedFail(s, "shun"),
        error.RewriteBusy => rewriteBusyFail(s, "shun"),
        error.StoreBusy => .failure, // the lock notice already said it
        else => shunFail(s, err),
    };
}

/// Canonicalize a `zit shun` positional to a lowercase-hex artifact-name prefix,
/// or null when it is not one. The same band `zit artifact` accepts (4..64 hex),
/// deliberately: an operator pastes the same token into both verbs.
fn canonicalizeShunHex(arg: []const u8, out: *[2 * logstore.max_hash_len]u8) ?[]const u8 {
    if (arg.len < 4 or arg.len > out.len) return null;
    for (arg, 0..) |c, i| {
        const lc = std.ascii.toLower(c);
        if (!((lc >= '0' and lc <= '9') or (lc >= 'a' and lc <= 'f'))) return null;
        out[i] = lc;
    }
    return out[0..arg.len];
}

/// Append `rows` to the live store and fsync — `--defer`'s whole effect, and the
/// path a `--force` run with nothing to reclaim takes too. One frame per row plus
/// one `commit`, so a crash mid-append leaves a torn tail the log's existing
/// recovery truncates: the shun is then simply absent, never half present.
/// Deliberately NOT the rewrite path: nothing here is atomic across rows, and
/// nothing needs to be, because each row is independently meaningful.
///
/// IT CARRIES BOTH OF `rewriteAndSwap`'S CONCURRENCY PROTECTIONS, for reasons that
/// are this path's own and not a symmetry argument.
///
/// The LOCK — the same exclusive non-blocking lock on the same fixed
/// `pack_tmp_filename`, so an append and a rewrite exclude each other. Without it a
/// `zit pack` (or another `zit shun --force`) that renames its new generation over
/// `.zit` after our `openFile` leaves us appending to an ORPHANED INODE: the row
/// lands nowhere anyone will ever read, and this run still reports success. On the
/// `--defer` path that means the deferred shun silently does not exist while the
/// help text has just told the operator to run `zit pack` to finish it. A cron'd
/// pack overlapping an operator's shun is an entirely ordinary way to hit that.
///
/// The TAIL RE-VALIDATION against `src_key` — because the caller classified its
/// targets against a snapshot taken before the lock existed, and both success
/// lines this path can print (`renderShunRecordedOnly`'s "none is held here, so
/// nothing was removed", `renderShunDeferred`'s count of what still holds content)
/// are claims about STORE STATE, not about the argument list. A `zit commit`
/// landing a named hash in that window makes the first of them false: the
/// tombstone would be recorded, exit 0, and an operator under a takedown order
/// told nothing was held while the bytes were live. Re-checking the tail on the
/// very handle the append will go through — under the lock, so no rename can have
/// intervened — turns that into an abort. `error.TailChanged` here means nothing
/// was written: the check precedes the first `putShun`.
///
/// The check reads the REOPENED handle rather than the caller's, and that is the
/// stronger of the two: a rewrite that completed just before we took the lock has
/// left the caller's handle pointing at an orphan whose tail still matches its own
/// key, while `.zit` by name is now a different generation. Validating the handle
/// we are about to WRITE is what makes that case an abort instead of an append
/// driven by a stale snapshot.
fn shunAppendRows(
    gpa: std.mem.Allocator,
    io: std.Io,
    dir: std.Io.Dir,
    src_key: logstore.LogStore.LogKey,
    rows: []const logstore.ShunRecord,
) ShunAppendError!void {
    // The rewrite lock, so no `pack` or `shun --force` runs underneath this
    // append, then the writer lock inside it, in the order every rewrite takes
    // them.
    var rewrite_lock = try lockRewrite(io, dir);
    defer rewrite_lock.release(io);

    var store_append = cli.openStoreAppend(io, dir) catch |e| switch (e) {
        error.StoreBusy => return error.StoreBusy,
        else => return error.Storage,
    };
    defer store_append.close(io);
    const file = store_append.file;
    const st = file.stat(io) catch return error.Storage;
    var fs = storage.FileStorage.init(io, file, st.size);
    // A FRESH handle and a FRESH stat, for the same reason `rewriteAndSwap` takes
    // them: the caller's view answers `size()` from the cached watermark its key
    // was derived from, so asking it could never disagree.
    if (!logstore.LogStore.validateTail(fs.storageFile(), src_key)) return error.TailChanged;
    // The header of the existing repo carries the hash kind; `open` reads it from
    // the non-empty file, so the passed value is a don't-care (0).
    var log = try logstore.LogStore.open(gpa, fs.storageFile(), 0);
    defer log.deinit(gpa);
    for (rows) |row| try log.putShun(row.hash, row.reason, row.epoch);
    try log.commit();
}

/// `zit shun` — record one or more artifacts in this repository's shun table and,
/// unless `--defer`, remove their bytes in the same operation.
///
/// POLICY, decided here and not by any draft: refuse by default and name the
/// consequence; require `--force` for BOTH paths, because `--defer` also appends
/// an irreversible tombstone and the read mask hides the content the instant it
/// lands; never prompt; refuse the current checkout's own check-in with no
/// override, because that is the one target whose removal breaks the tree the
/// operator is standing in and `zit update` is a cheap way out.
///
/// CRASH SAFETY. `--force` performs exactly ONE durable transition. When there is
/// content to remove that is the rename inside `rewriteAndSwap`, and the new
/// tombstones are written into the NEW generation (`packLog`'s `extra_shuns`),
/// never appended to `.zit` first — two durable transitions would expose a state
/// where the tombstone exists and the content still does. It also means an aborted
/// run leaves no tombstone at all: the rows were in the temp that the abort
/// deletes. Pinned by "runShun: a --force run the temp lock turns away records NO
/// tombstone".
///
/// When NOTHING is held — every named hash is pre-emptive — the single durable
/// transition is instead the append plus commit, and the rewrite is skipped
/// altogether. It is not load-bearing there: the rule exists to stop a tombstone
/// outliving its content, and with no content to remove the append is already
/// crash-safe under the log's torn-tail recovery. Running a whole-store rewrite to
/// reclaim nothing would cost O(store) plus transient room for both generations and
/// end with a report whose byte count had GROWN.
///
/// The rename is visible to a running `zit serve` DESPITE its held handle:
/// serve's `baseSnapshot` stats the path beside the handle each round and
/// reopens on an inode change, so the round after this swap serves the
/// rewritten generation — shunned content gone — with no restart.
pub fn runShun(
    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.parseShunArgs(arena, verb_args) catch return stateOom(streams, "shun")) {
        .ok => |a| a,
        .unknown_option => |tok| return cli.usageError(streams, "shun", .unknown_option, tok),
        .extra_argument => |tok| return cli.usageError(streams, "shun", .extra_argument, tok),
    };
    if (parsed.help) {
        streams.out.writeAll(shun_help) catch {};
        return .ok;
    }
    if (parsed.hashes.len != 0 and std.mem.eql(u8, parsed.hashes[0], "key")) {
        return runShunKey(gpa, io, arena, parsed, streams, amb);
    }
    if (parsed.hashes.len != 0 and std.mem.eql(u8, parsed.hashes[0], "cancel")) {
        return runShunCancel(gpa, io, arena, parsed, streams, amb);
    }
    if (!parsed.list and parsed.hashes.len == 0) {
        return cli.usageError(streams, "shun", .no_hash, "");
    }
    if (parsed.now and !parsed.sign) {
        streams.err.writeAll("zit shun: --now applies to a signed erasure; add --sign\n") catch {};
        return .usage;
    }
    if (parsed.json and !parsed.list) {
        streams.err.writeAll("zit shun: -F json applies to --list and 'key generate'\n") catch {};
        return .usage;
    }
    // A reason the durable row cannot hold is refused BEFORE anything is opened,
    // and refused rather than truncated: the note on a shun is often the legal
    // reference the operator will be asked for, and silently keeping a prefix of
    // it is worse than making them shorten it themselves.
    //
    // A CONTROL BYTE IS REFUSED THE SAME WAY, and this is the reason `--reason` is
    // validated at all rather than merely bounded. `--list` is the only view of a
    // durable, irreversible, un-removable record, and `renderShunList` prints one
    // row per line: a newline inside a reason forges a row there that is
    // indistinguishable from a real one. Reasons arrive from scripts and from pasted
    // takedown text as often as they are typed, so this is not a hand-typed-only
    // hazard. Rejecting at input rather than escaping at render keeps the fix to one
    // place and keeps the stored bytes exactly what the operator supplied. NO DRAFT
    // SPEAKS TO THIS and `logstore.ShunError` has no arm for it — a local decision,
    // taken the same way the length gate was: refuse rather than mangle.
    if (parsed.reason) |r| {
        if (r.len > logstore.max_shun_reason) {
            streams.err.print(
                "zit shun: --reason is {d} bytes; the recorded note is at most {d}\n",
                .{ r.len, logstore.max_shun_reason },
            ) catch {};
            return .failure;
        }
        for (r) |c| {
            if (c >= 0x20 and c != 0x7f) continue;
            streams.err.writeAll(
                "zit shun: --reason contains a control byte; the recorded note must be a single line of text\n",
            ) catch {};
            return .failure;
        }
        // The prefix that marks a signed statement. A plain note spelled
        // with it would read as a statement that does not verify, and the
        // shun would mask nothing.
        if (std.mem.startsWith(u8, r, zit.erasure.prefix)) {
            streams.err.print("zit shun: --reason may not begin with '{s}'\n", .{zit.erasure.prefix}) catch {};
            return .failure;
        }
        // Nor be the note a store records once an erasure took effect.
        if (zit.erasure.isApplied(r)) {
            streams.err.print("zit shun: --reason may not be '{s}'\n", .{zit.erasure.applied_reason}) catch {};
            return .failure;
        }
    }

    // `-R` names a bare store as readily as a checkout: everything below is
    // store-side except the current-checkout guard, which reads the checkout
    // record of whatever directory was named and is empty on a bare store.
    const root = (cli.resolveRoot(arena, io, amb.repo_override) catch return stateOom(streams, "shun")) orelse {
        diagnostics.reportNoRoot(streams, io, "shun", amb.repo_override);
        return .failure;
    };
    var root_dir = root.dir;
    defer root_dir.close(io);
    // shun is store-scoped end to end: the reads, the pack-tmp lock
    // and the final rename must all land beside the STORE, so a detached
    // worktree resolves its pointer once here and the whole flow inherits it.
    if (cli.storeDirOf(io, root_dir) catch return repoReadFail(streams, "shun")) |resolved| {
        root_dir.close(io);
        root_dir = resolved;
    }

    // Open the source read-only, exactly as `pack` does, and for the same
    // reasons — including the same caveat: this open no longer CRC-verifies
    // payloads (it scans header-only), so a corrupt source aborts during the
    // rewrite's own reads rather than here. Nothing is written either way. The
    // tail key pins the log for the pre-rename re-check. See `runPack`'s doc
    // comment for why that ordering matters to a verb that renames over `.zit`.
    var src_file = cli.openStoreRead(io, root_dir) catch |e| return storeReadFail(streams, "shun", e);
    defer src_file.close(io);
    const src_st = src_file.stat(io) catch return repoReadFail(streams, "shun");
    var src_fs = storage.FileStorage.init(io, src_file, src_st.size);
    var src = logstore.LogStore.openReadOnly(gpa, src_fs.storageFile()) catch |e| switch (e) {
        error.OutOfMemory => return stateOom(streams, "shun"),
        else => |re| return shunFail(streams, re),
    };
    defer src.deinit(gpa);

    if (parsed.list) {
        if (parsed.json) {
            renderShunListJson(streams.out, &src) catch {};
        } else renderShunTable(streams.out, &src);
        return .ok;
    }
    const src_key = src.logKey() catch return shunFail(streams, error.Corrupt);
    // A signed erasure needs the owner key before anything is classified,
    // so a refusal costs nothing.
    var code_buf: [logstore.max_config_str]u8 = undefined;
    const signer: ?ErasureSigner = if (parsed.sign)
        (loadErasureSigner(gpa, io, &src, amb, &code_buf, streams) orelse return .failure)
    else
        null;
    // An erasure that takes effect now is recorded as applied once it has
    // landed, as a session records one it latched (`markErasuresApplied`).
    defer if (signer != null and parsed.now) {
        _ = applySessionErasures(gpa, io, root_dir, null, "shun", null, &.{}, false);
    };

    // The current checkout's own check-in, for the one refusal with no override.
    // A `.zit-checkout` we cannot parse is a hard failure, not an empty answer:
    // the guard would silently become vacuous and the operator would be allowed
    // to delete the check-in they are standing on.
    var ck_buf: [checkout.max_ck_payload + 1]u8 = undefined;
    const ck_state = checkout.read(io, root_dir, &ck_buf) catch |e|
        return diagnostics.checkoutFail(streams, "shun", e);
    const ck_version: []const u8 = if (ck_state) |s| s.version else "";

    // Classified, then DEDUPLICATED BY RESOLVED DIGEST — which is why it cannot be
    // done in the parser. `zit shun --force H <prefix-of-H>` is one artifact named
    // twice, and an operator pasting a takedown list beside an abbreviation from
    // `zit log` cannot see that it is. Left folded in, the duplicate builds two
    // identical rows, `putShun` collapses them, and `packLog`'s row-count gate —
    // whose documented precondition is that `extra_shuns` rows are DISTINCT — fires
    // `error.Corrupt`: the verb would tell the operator their repository is corrupt,
    // on the one occasion they can least afford to doubt it. Deduping here rather
    // than in `packLog` keeps that gate a gate. O(n^2) over an argument list.
    const target_buf = arena.alloc(ShunTarget, parsed.hashes.len) catch return stateOom(streams, "shun");
    var target_count: usize = 0;
    tokens: for (parsed.hashes) |tok| {
        const t = classifyShunTarget(gpa, arena, &src, ck_version, tok) catch |e|
            return shunFail(streams, e);
        // Only a resolved target can be a duplicate: the unresolvable dispositions
        // carry the operator's own token and no digest, and two different bad tokens
        // both deserve their own diagnostic line.
        if (t.digest.len != 0) {
            for (target_buf[0..target_count]) |prev| {
                if (std.mem.eql(u8, prev.digest, t.digest)) continue :tokens;
            }
        }
        target_buf[target_count] = t;
        target_count += 1;
    }
    const targets = target_buf[0..target_count];

    // THE GUARD RUNS BEFORE ANY DURABLE WRITE — the ordering is the point, not an
    // implementation detail. A refused run must leave the store byte-identical,
    // which it cannot do if a tombstone was recorded while deciding.
    for (targets) |t| {
        if (t.disposition.blocks()) {
            renderShunBlockers(streams.err, targets);
            return .failure;
        }
    }

    // Two counts, and they are independent: `absent` records without removing,
    // `reclaim` removes without recording. Either one alone is work to do.
    var recorded: usize = 0;
    var reclaiming: usize = 0;
    for (targets) |t| {
        if (t.disposition.records()) recorded += 1;
        if (t.disposition.reclaims()) reclaiming += 1;
    }
    if (recorded == 0 and reclaiming == 0) {
        // Every named hash was already in the set AND its content already gone: a
        // genuine no-op, so it needs no `--force` and it is not a failure. Reaching
        // this on a hash whose bytes SURVIVED is the defect `.reclaim` exists to
        // prevent — it would report "nothing to do" over content the operator had
        // just been ordered to remove.
        if (parsed.porcelain) {
            renderShunPorcelain(streams.out, targets, false);
        } else streams.out.print(
            "shunned: nothing to do; {d} hash{s} already shunned\n",
            .{ targets.len, pluralEs(targets.len) },
        ) catch {};
        return .ok;
    }
    if (!parsed.force) {
        renderShunRefusal(streams.err, targets, deferredStillHeld(&src, targets), parsed.defer_reclaim);
        return .failure;
    }

    // ONE owned name set drives both the drop predicate and the tombstone list,
    // so a name cannot be recorded without also being dropped. It is the UNION of
    // the source's already-deferred shuns and the hashes named now: `shunFilter`
    // covers only the first half, and half a drop set would relocate into the new
    // generation exactly the bytes this run reports as removed.
    var set: NameSet = .{};
    defer set.deinit(gpa);
    for (src.shunList()) |row| if (src.isShunned(row.hash)) set.add(gpa, row.hash) catch |e| switch (e) {
        error.OutOfMemory => return stateOom(streams, "shun"),
        // A persisted row whose key is not a complete digest is a corrupt store,
        // and that is the one place `BadKey` here can come from.
        error.BadKey => return shunFail(streams, error.Corrupt),
    };

    const row_buf = arena.alloc(logstore.ShunRecord, recorded) catch return stateOom(streams, "shun");
    var n: usize = 0;
    for (targets) |t| {
        if (!t.disposition.records()) continue;
        set.add(gpa, t.digest) catch |e| switch (e) {
            error.OutOfMemory => return stateOom(streams, "shun"),
            error.BadKey => return shunRowBug(streams),
        };
        row_buf[n] = .{ .hash = t.digest, .epoch = amb.now_epoch, .reason = parsed.reason orelse "" };
        if (signer) |sg| {
            const nb = if (parsed.now) amb.now_epoch else amb.now_epoch + zit.erasure.default_delay;
            row_buf[n].reason = sg.sign(arena, t.digest, amb.now_epoch, nb, .erase, parsed.reason orelse "") catch |e| switch (e) {
                error.OutOfMemory => return stateOom(streams, "shun"),
                error.ReasonTooLong => {
                    streams.err.writeAll("zit shun: --reason is too long for a signed erasure, whose signature shares the recorded note's 200 bytes\n") catch {};
                    return .failure;
                },
                else => return shunRowBug(streams),
            };
        }
        n += 1;
    }
    // SLICED, not asserted-and-passed-whole. `recorded` and `n` count the same pure
    // predicate over the same unmutated `targets`, so they cannot differ today — but
    // `row_buf` is arena memory and the FULL buffer used to be what went to
    // `packLog` and `shunAppendRows`. Had they ever differed, `row_buf[n..]` would
    // be undefined `ShunRecord`s whose `hash` is a garbage slice, handed to
    // `putShun` on the way to a durable irreversible write — in `ReleaseFast`, where
    // the assert below does not exist. Taking the slice makes the mismatch
    // unrepresentable and leaves the assert as documentation of the tautology.
    const rows = row_buf[0..n];
    std.debug.assert(rows.len == recorded);

    // Nothing to reclaim: take the append path even without `--defer`. See the
    // crash-safety note in the doc above — the rewrite is not what makes this safe,
    // and running it would cost a whole-store copy to remove nothing.
    if (reclaiming == 0) {
        shunAppendRows(gpa, io, root_dir, src_key, rows) catch |e| return shunAppendFail(streams, e);
        if (parsed.porcelain) {
            renderShunPorcelain(streams.out, targets, false);
        } else if (signer != null) {
            renderErasureSigned(streams.out, rows.len, parsed.now, amb.now_epoch);
        } else renderShunRecordedOnly(streams.out, rows.len);
        return .ok;
    }

    // A signed erasure with a delay masks nothing yet, so nothing is reclaimed
    // now: its bytes go at the first sync, pull or pack past its not-before.
    if (parsed.defer_reclaim or (signer != null and !parsed.now)) {
        // `rows` is empty when every target was already tombstoned and only its
        // bytes remain; skip the append rather than fsync for nothing.
        if (rows.len != 0) {
            shunAppendRows(gpa, io, root_dir, src_key, rows) catch |e| return shunAppendFail(streams, e);
        }
        if (parsed.porcelain) {
            renderShunPorcelain(streams.out, targets, false);
        } else if (signer != null) {
            renderErasureSigned(streams.out, rows.len, parsed.now, amb.now_epoch);
        } else renderShunDeferred(streams.out, rows.len, reclaiming, amb.repo_override);
        return .ok;
    }

    // THE CURRENT-CHECKOUT STOP, RE-ASKED OF THE DROP SET ITSELF — one hashmap
    // lookup, at the point of consequence. `classifyShunTarget` enforces it over the
    // NAMED TOKENS, but `set` is the union of those with every row already in the
    // shun table, and the rewrite deletes the union. A table that already contained
    // this check-in's manifest would therefore have `--force` delete the check-in the
    // operator is standing in while the per-token guard never fired — the refusal
    // line would count it only as an anonymous integer of earlier deferred
    // collateral. That state is not constructible through zit today (`--defer` goes
    // through the same per-token guard, and S1's mask makes `zit update` to a shunned
    // check-in fail), which is exactly why the invariant belongs here as well: the
    // property `shun_help` promises is about what gets deleted, not about the
    // argument list.
    if (ck_version.len != 0) {
        var ck_raw: [logstore.max_hash_len]u8 = undefined;
        if (shunHexToDigest(ck_version, &ck_raw)) |ck_digest| {
            if (set.contains(ck_digest)) {
                renderShunBlockers(streams.err, &.{.{
                    .name = ck_version,
                    .digest = ck_digest,
                    .disposition = .current_checkout,
                }});
                return .failure;
            }
        }
    }

    const stats = rewriteAndSwap(
        gpa,
        io,
        root_dir,
        &src,
        src_key,
        set.filter(),
        rows,
    ) catch |e| switch (e) {
        error.TailChanged => return tailChangedFail(streams, "shun"),
        error.RewriteBusy => return rewriteBusyFail(streams, "shun"),
        else => |pe| return shunFail(streams, pe),
    };
    // Reported from the PACK's observation of the new generation, not from
    // `rows.len`: see `renderShunStats`. They agree or `packLog`'s row-count gate
    // failed the pack, which is why this is an assert rather than a branch.
    std.debug.assert(stats.shuns_recorded == rows.len);
    if (parsed.porcelain) {
        renderShunPorcelain(streams.out, targets, true);
    } else renderShunStats(streams.out, stats);
    return .ok;
}

// ---------------------------------------------------------------------------
// Signed erasures at the CLI: the owner key, `--sign`, `cancel`, the list, and
// the per-session carriage sync adds on top of Fossil's `/shun` rows. The
// statement itself (message, signature, SCOM grammar, key file) lives in
// src/store/erasure.zig; nothing here touches the crypto beyond calling it.
// ---------------------------------------------------------------------------

const erasure = zit.erasure;

/// The owner's private seed for one call, checked against the pinned key.
const ErasureSigner = struct {
    seed: erasure.Seed,
    project_code: []const u8,

    /// The SCOM of a signed row for `digest`, arena-owned.
    fn sign(self: ErasureSigner, arena: std.mem.Allocator, digest: []const u8, epoch: i64, nb: i64, kind: erasure.Kind, reason: []const u8) (erasure.SignError || error{OutOfMemory})![]const u8 {
        var hex_buf: [2 * logstore.max_hash_len]u8 = undefined;
        const hex = digestToWireName(digest, &hex_buf);
        var out: [erasure.max_scom]u8 = undefined;
        const scom = try erasure.sign(self.seed, .{ .project_code = self.project_code, .hash_hex = hex, .epoch = epoch }, nb, kind, reason, &out);
        return arena.dupe(u8, scom);
    }
};

/// The signer for `log`, or null with the reason already on stderr. The key
/// comes from `$ZIT_ERASURE_KEY` (64 hex) when set, so an application that
/// keeps it in a platform keychain hands it over per call, else from the key
/// file `zit shun key generate` wrote.
fn loadErasureSigner(
    gpa: std.mem.Allocator,
    io: std.Io,
    log: *logstore.LogStore,
    amb: cli.Ambient,
    code_buf: *[logstore.max_config_str]u8,
    streams: cli.Streams,
) ?ErasureSigner {
    const pinned = log.erasureKey() orelse {
        streams.err.writeAll("zit shun: no erasure key is pinned in this repository; run 'zit shun key generate' or 'zit shun key pin PUBKEY'\n") catch {};
        return null;
    };
    const code = logProjectCode(gpa, log, code_buf) catch {
        _ = repoReadFail(streams, "shun");
        return null;
    };
    if (code.len == 0) {
        streams.err.writeAll("zit shun: this repository has no project code to sign an erasure for\n") catch {};
        return null;
    }
    const seed: erasure.Seed = if (amb.environ.getPosix("ZIT_ERASURE_KEY")) |text|
        erasure.parseKeyHex(erasure.seed_len, text) orelse {
            streams.err.writeAll("zit shun: ZIT_ERASURE_KEY is not a 64-hex private key\n") catch {};
            return null;
        }
    else
        erasure.readKeyFile(io, amb.environ, code) catch |e| {
            switch (e) {
                error.NotFound, error.NoHome => streams.err.writeAll(
                    "zit shun: no private erasure key on this device; set ZIT_ERASURE_KEY or run 'zit shun key generate'\n",
                ) catch {},
                else => streams.err.writeAll("zit shun: the private erasure key file cannot be read\n") catch {},
            }
            return null;
        };
    const public = erasure.publicKeyOf(seed) catch {
        streams.err.writeAll("zit shun: the private erasure key is not a usable Ed25519 seed\n") catch {};
        return null;
    };
    if (!std.mem.eql(u8, &public, &pinned)) {
        streams.err.writeAll("zit shun: the private erasure key does not match the key pinned in this repository\n") catch {};
        return null;
    }
    return .{ .seed = seed, .project_code = code };
}

fn renderErasureSigned(out: *std.Io.Writer, recorded: usize, now: bool, epoch: i64) void {
    if (now) {
        out.print("erased: {d} hash{s} signed; none is held here, so nothing was removed\n", .{ recorded, pluralEs(recorded) }) catch {};
        return;
    }
    var ts: [19]u8 = undefined;
    out.print(
        "erasure signed: {d} hash{s}; takes effect at {s} UTC; 'zit shun cancel HASH' undoes it before then\n",
        .{ recorded, pluralEs(recorded), cli.formatWriterTimestamp(epoch + erasure.default_delay, &ts) },
    ) catch {};
}

/// The words `--list` uses for one row: its kind, whether its signature
/// verifies, and what its name's fold says.
const ShunListRow = struct {
    kind: []const u8,
    signer: []const u8,
    state: []const u8,
    not_before: ?i64,
};

fn shunListRow(log: *const logstore.LogStore, i: usize) ShunListRow {
    const row = log.shunList()[i];
    const st = log.shunRowState(i);
    const status = log.shunStatus(row.hash);
    const state: []const u8 = switch (status.state) {
        .none, .inert => "inert",
        .pending => "pending",
        .shunned, .erased => "active",
    };
    return switch (st.kind) {
        .plain => .{ .kind = "plain", .signer = "none", .state = state, .not_before = null },
        .applied => .{ .kind = "applied", .signer = "none", .state = state, .not_before = null },
        .erase => .{ .kind = "erase", .signer = "verified", .state = state, .not_before = st.not_before },
        .cancel => .{ .kind = "cancel", .signer = "verified", .state = state, .not_before = st.not_before },
        .unverified => .{ .kind = "signed", .signer = "unverified", .state = state, .not_before = null },
    };
}

/// `--list`: the shun table in persisted order, one row per line — full artifact
/// name, the UTC date it was recorded, and the reason when one was given. The
/// date comes from `cli.formatWriterTimestamp`'s first ten bytes, so this shares
/// the CLI's one epoch formatter rather than growing a second.
fn renderShunList(out: *std.Io.Writer, rows: []const logstore.ShunRecord) void {
    if (rows.len == 0) {
        out.writeAll("the shun table is empty\n") catch {};
        return;
    }
    for (rows) |row| renderShunRow(out, row, null);
}

/// `renderShunList` over the store, which knows what each row's reason says:
/// a signed row names its kind (`erase`, `cancel`), its name's state
/// (`pending`, `active`, `inert`), its not-before, and whether its signature
/// verifies against the pinned key, and its note is the statement's reason.
fn renderShunTable(out: *std.Io.Writer, log: *const logstore.LogStore) void {
    const rows = log.shunList();
    if (rows.len == 0) return renderShunList(out, rows);
    for (rows, 0..) |row, i| renderShunRow(out, row, shunListRow(log, i));
}

fn renderShunRow(out: *std.Io.Writer, row: logstore.ShunRecord, signed: ?ShunListRow) void {
    var hex: [2 * digest_len]u8 = undefined;
    var ts: [19]u8 = undefined;
    const date = cli.formatWriterTimestamp(row.epoch, &ts)[0..10];
    out.print("{s}  {s}", .{ digestToWireName(row.hash, &hex), date }) catch {};
    var reason = row.reason;
    if (signed) |lr| if (!std.mem.eql(u8, lr.kind, "plain")) {
        out.print("  {s}  {s}", .{ lr.kind, lr.state }) catch {};
        if (lr.not_before) |nb| {
            var nb_ts: [19]u8 = undefined;
            out.print("  not-before {s}", .{cli.formatWriterTimestamp(nb, &nb_ts)}) catch {};
        }
        out.print("  signer {s}", .{lr.signer}) catch {};
        reason = switch (erasure.classify(row.reason)) {
            .signed => |stmt| stmt.reason,
            else => "",
        };
    };
    if (reason.len != 0) out.print("  {s}", .{reason}) catch {};
    out.writeAll("\n") catch {};
}

/// `--list -F json`: one array, a row per element, in persisted order.
fn renderShunListJson(out: *std.Io.Writer, log: *const logstore.LogStore) std.Io.Writer.Error!void {
    var jw: std.json.Stringify = .{ .writer = out };
    try jw.beginArray();
    for (log.shunList(), 0..) |row, i| {
        var hex: [2 * digest_len]u8 = undefined;
        const lr = shunListRow(log, i);
        try jw.beginObject();
        try jw.objectField("hash");
        try jw.write(digestToWireName(row.hash, &hex));
        try jw.objectField("epoch");
        try jw.write(row.epoch);
        try jw.objectField("kind");
        try jw.write(lr.kind);
        try jw.objectField("state");
        try jw.write(lr.state);
        try jw.objectField("not_before");
        try jw.write(lr.not_before);
        try jw.objectField("signer");
        try jw.write(lr.signer);
        try jw.objectField("reason");
        try jw.write(switch (erasure.classify(row.reason)) {
            .signed => |stmt| stmt.reason,
            .plain => row.reason,
            .malformed => "",
        });
        try jw.endObject();
    }
    try jw.endArray();
    try out.writeByte('\n');
}

/// The repository a `shun key` or `shun cancel` acts on: the store directory.
fn shunStoreDir(arena: std.mem.Allocator, io: std.Io, streams: cli.Streams, amb: cli.Ambient) ?std.Io.Dir {
    const root = (cli.resolveRoot(arena, io, amb.repo_override) catch {
        _ = stateOom(streams, "shun");
        return null;
    }) orelse {
        diagnostics.reportNoRoot(streams, io, "shun", amb.repo_override);
        return null;
    };
    var dir = root.dir;
    if (cli.storeDirOf(io, dir) catch {
        dir.close(io);
        _ = repoReadFail(streams, "shun");
        return null;
    }) |resolved| {
        dir.close(io);
        dir = resolved;
    }
    return dir;
}

fn erasureAppendFail(streams: cli.Streams, e: anyerror) cli.Exit {
    return switch (e) {
        error.OutOfMemory => stateOom(streams, "shun"),
        error.RewriteBusy => rewriteBusyFail(streams, "shun"),
        error.StoreBusy => .failure, // the lock notice already said it
        else => shunFail(streams, e),
    };
}

/// `zit shun key generate [--print | -F json]`, `zit shun key show`,
/// `zit shun key pin PUBKEY` — the repository's one owner key.
fn runShunKey(
    gpa: std.mem.Allocator,
    io: std.Io,
    arena: std.mem.Allocator,
    parsed: cli.ShunArgs,
    streams: cli.Streams,
    amb: cli.Ambient,
) cli.Exit {
    const args = parsed.hashes[1..];
    if (args.len == 0) {
        streams.err.writeAll("zit shun key: name one of generate, show, pin\n") catch {};
        return .usage;
    }
    const sub = args[0];
    const is_generate = std.mem.eql(u8, sub, "generate");
    const is_show = std.mem.eql(u8, sub, "show");
    const is_pin = std.mem.eql(u8, sub, "pin");
    if (!is_generate and !is_show and !is_pin) return cli.usageError(streams, "shun", .extra_argument, sub);
    const want_args: usize = if (is_pin) 2 else 1;
    if (args.len != want_args) {
        if (args.len > want_args) return cli.usageError(streams, "shun", .extra_argument, args[want_args]);
        streams.err.writeAll("zit shun key pin: name the public key, 64 hex\n") catch {};
        return .usage;
    }
    if ((parsed.print or parsed.json) and !is_generate) {
        streams.err.writeAll("zit shun key: --print and -F json apply to 'key generate'\n") catch {};
        return .usage;
    }

    // `--print` touches no repository and writes no file: the keypair goes to
    // stdout for a caller that keeps the private half in a keychain and pins
    // the public half with `key pin`.
    if (is_generate and (parsed.print or parsed.json)) {
        var seed: erasure.Seed = undefined;
        io.random(&seed);
        defer std.crypto.secureZero(u8, &seed);
        const public = erasure.publicKeyOf(seed) catch return shunFail(streams, error.Corrupt);
        const pub_hex = erasure.keyHex(public);
        var priv_hex = erasure.keyHex(seed);
        defer std.crypto.secureZero(u8, &priv_hex);
        if (parsed.json) {
            streams.out.print("{{\"public\":\"{s}\",\"private\":\"{s}\"}}\n", .{ &pub_hex, &priv_hex }) catch {};
        } else streams.out.print("public {s}\nprivate {s}\n", .{ &pub_hex, &priv_hex }) catch {};
        return .ok;
    }

    var dir = shunStoreDir(arena, io, streams, amb) orelse return .failure;
    defer dir.close(io);

    if (is_show) {
        var src_file = cli.openStoreRead(io, dir) catch |e| return storeReadFail(streams, "shun", e);
        defer src_file.close(io);
        const st = src_file.stat(io) catch return repoReadFail(streams, "shun");
        var fs = storage.FileStorage.init(io, src_file, st.size);
        var log = logstore.LogStore.openReadOnly(gpa, fs.storageFile()) catch |e| return shunFail(streams, e);
        defer log.deinit(gpa);
        const key = log.erasureKey() orelse {
            streams.err.writeAll("zit shun key: no erasure key is pinned in this repository\n") catch {};
            return .failure;
        };
        streams.out.print("{s}\n", .{&erasure.keyHex(key)}) catch {};
        return .ok;
    }

    var pin_key: erasure.PublicKey = undefined;
    if (is_pin) {
        pin_key = erasure.pinnedKey(args[1]) orelse {
            streams.err.print("zit shun key pin: '{s}' is not a 64-hex Ed25519 public key\n", .{args[1]}) catch {};
            return .failure;
        };
    }

    var ap: ErasureAppend = undefined;
    openErasureAppend(gpa, io, dir, &ap) catch |e| return erasureAppendFail(streams, e);
    defer ap.close(gpa, io);

    if (is_generate) {
        // Generating over a pinned key would strand every device that holds
        // the old one; replacing a key is the operator's `key pin`.
        if (ap.log.erasureKey() != null) {
            streams.err.writeAll("zit shun key generate: this repository already pins an erasure key; 'zit shun key pin PUBKEY' replaces it\n") catch {};
            return .failure;
        }
        var code_buf: [logstore.max_config_str]u8 = undefined;
        const code = logProjectCode(gpa, &ap.log, &code_buf) catch return repoReadFail(streams, "shun");
        var seed: erasure.Seed = undefined;
        io.random(&seed);
        defer std.crypto.secureZero(u8, &seed);
        pin_key = erasure.publicKeyOf(seed) catch return shunFail(streams, error.Corrupt);
        var path_buf: [std.fs.max_path_bytes]u8 = undefined;
        const path = erasure.writeKeyFile(io, amb.environ, code, seed, &path_buf) catch |e| {
            switch (e) {
                error.NoHome => streams.err.writeAll("zit shun key generate: no XDG_CONFIG_HOME or HOME to hold the private key; use --print\n") catch {},
                error.Exists => streams.err.writeAll("zit shun key generate: a private key file for this repository already exists\n") catch {},
                error.BadProjectCode => streams.err.writeAll("zit shun key generate: this repository has no usable project code\n") catch {},
                else => streams.err.writeAll("zit shun key generate: the private key file cannot be written\n") catch {},
            }
            return .failure;
        };
        writeErasureKey(&ap.log, pin_key, amb.now_epoch) catch |e| return erasureAppendFail(streams, e);
        streams.out.print("erasure key pinned: {s}\nprivate key written to {s}\n", .{ &erasure.keyHex(pin_key), path }) catch {};
        return .ok;
    }

    writeErasureKey(&ap.log, pin_key, amb.now_epoch) catch |e| return erasureAppendFail(streams, e);
    streams.out.print("erasure key pinned: {s}\n", .{&erasure.keyHex(pin_key)}) catch {};
    return .ok;
}

fn writeErasureKey(log: *logstore.LogStore, key: erasure.PublicKey, now: i64) !void {
    const hex = erasure.keyHex(key);
    try log.putSetting(.{ .name = erasure.setting_name, .value = &hex, .mtime = now });
    try log.commit();
}

/// `zit shun cancel HASH` — sign a cancel for a pending erasure, inside its
/// window. Outside it the erasure has taken effect and nothing can undo it,
/// as nothing undoes a shun.
fn runShunCancel(
    gpa: std.mem.Allocator,
    io: std.Io,
    arena: std.mem.Allocator,
    parsed: cli.ShunArgs,
    streams: cli.Streams,
    amb: cli.Ambient,
) cli.Exit {
    const args = parsed.hashes[1..];
    if (args.len != 1) {
        if (args.len > 1) return cli.usageError(streams, "shun", .extra_argument, args[1]);
        return cli.usageError(streams, "shun", .no_hash, "");
    }
    var dir = shunStoreDir(arena, io, streams, amb) orelse return .failure;
    defer dir.close(io);
    var ap: ErasureAppend = undefined;
    openErasureAppend(gpa, io, dir, &ap) catch |e| return erasureAppendFail(streams, e);
    defer ap.close(gpa, io);

    var canon_buf: [2 * logstore.max_hash_len]u8 = undefined;
    const canon = canonicalizeShunHex(args[0], &canon_buf) orelse {
        streams.err.print("zit shun cancel: '{s}' is not an artifact name\n", .{args[0]}) catch {};
        return .failure;
    };
    // The name is the table's, not the store's: a pending erasure of a hash
    // this repository never held is as cancellable as one it holds.
    var digest: ?[]const u8 = null;
    for (ap.log.shunList()) |row| {
        var hex: [2 * logstore.max_hash_len]u8 = undefined;
        if (!std.mem.startsWith(u8, digestToWireName(row.hash, &hex), canon)) continue;
        if (digest) |d| if (!std.mem.eql(u8, d, row.hash)) {
            streams.err.print("zit shun cancel: hash '{s}' is ambiguous\n", .{args[0]}) catch {};
            return .failure;
        };
        digest = row.hash;
    }
    const target = arena.dupe(u8, digest orelse {
        streams.err.print("zit shun cancel: {s} has no erasure to cancel\n", .{args[0]}) catch {};
        return .failure;
    }) catch return stateOom(streams, "shun");
    var hex_buf: [2 * logstore.max_hash_len]u8 = undefined;
    const name = digestToWireName(target, &hex_buf);
    const status = ap.log.shunStatus(target);
    var ts: [19]u8 = undefined;
    switch (status.state) {
        .pending => {},
        .erased => {
            streams.err.print("zit shun cancel: the erasure of {s} took effect at {s} UTC and cannot be cancelled\n", .{ name, cli.formatWriterTimestamp(status.not_before, &ts) }) catch {};
            return .failure;
        },
        else => {
            streams.err.print("zit shun cancel: {s} has no pending erasure to cancel\n", .{name}) catch {};
            return .failure;
        },
    }

    var code_buf: [logstore.max_config_str]u8 = undefined;
    const signer = loadErasureSigner(gpa, io, &ap.log, amb, &code_buf, streams) orelse return .failure;
    // A cancel is newer than the erasure it cancels and older than its
    // not-before; a clock that disagrees is nudged into the window, and an
    // erasure with no window left cannot be cancelled at all.
    var newest_erase: i64 = std.math.minInt(i64);
    for (ap.log.shunList(), 0..) |row, i| {
        if (std.mem.eql(u8, row.hash, target) and ap.log.shunRowState(i).kind == .erase) newest_erase = @max(newest_erase, row.epoch);
    }
    const epoch = @max(amb.now_epoch, newest_erase + 1);
    if (epoch >= status.not_before) {
        streams.err.print("zit shun cancel: the erasure of {s} takes effect at {s} UTC; it is too late to cancel\n", .{ name, cli.formatWriterTimestamp(status.not_before, &ts) }) catch {};
        return .failure;
    }
    const scom = signer.sign(arena, target, epoch, epoch, .cancel, "") catch return shunRowBug(streams);
    ap.log.putShun(target, scom, epoch) catch |e| return erasureAppendFail(streams, e);
    ap.log.commit() catch |e| return erasureAppendFail(streams, e);
    streams.out.print("cancelled: the erasure of {s}\n", .{name}) catch {};
    return .ok;
}

/// Resolve one operator token against `src` into a `ShunTarget`. Impure only in
/// that it reads the store: no policy, no output, no durable write, so the
/// runner's whole decision is a fold over the results.
///
/// RESOLUTION RULE. Every token is offered to prefix resolution FIRST, at every
/// width in `canonicalizeShunHex`'s band — the same band and the same resolver
/// `zit artifact` uses (cmd/artifact.zig), which is what makes "paste the same
/// token into both verbs" true rather than merely intended. Only when nothing
/// matches does a COMPLETE name (40 or 64 hex — artifact-format §3.2's two forms)
/// fall back to being used literally, because a hash this repository does not hold
/// is precisely the pre-emptive case worth recording; an ABBREVIATED prefix that
/// matches nothing is refused, since the shun table is keyed by complete name
/// (sync §3.3 L544-545), a prefix cannot be completed, and a row keyed on one would
/// read as a removal while naming nothing.
///
/// TRYING RESOLUTION FIRST IS THE LOAD-BEARING PART, not an optimisation. Treating
/// a complete-WIDTH token as a complete NAME without asking the store means a
/// 40-hex abbreviation of a 64-hex artifact (and a 64-hex abbreviation in a sha1
/// repository) records a tombstone naming nothing, reports success, and leaves the
/// content the operator was ordered to remove still readable — the `unresolved`
/// refusal exists to stop exactly that, and a width-first rule walks past it.
/// It also un-hides the current-checkout guard, which cannot fire on a token that
/// never resolved to the check-in's name.
fn classifyShunTarget(
    gpa: std.mem.Allocator,
    arena: std.mem.Allocator,
    src: *logstore.LogStore,
    ck_version: []const u8,
    tok: []const u8,
) (logstore.ContentError || error{OutOfMemory})!ShunTarget {
    var canon_buf: [2 * logstore.max_hash_len]u8 = undefined;
    const canon = canonicalizeShunHex(tok, &canon_buf) orelse
        return .{ .name = tok, .disposition = .not_a_name };

    var raw_buf: [logstore.max_hash_len]u8 = undefined;
    var digest: []const u8 = undefined;
    if (src.resolveHexPrefix(canon) catch |e| switch (e) {
        error.Ambiguous => return .{ .name = tok, .disposition = .ambiguous },
    }) |rid| {
        digest = src.hashOf(rid);
    } else if (shunHexToDigest(canon, &raw_buf)) |d| {
        digest = d;
    } else {
        return .{ .name = tok, .disposition = .unresolved };
    }
    std.debug.assert(logstore.isCompleteDigest(digest.len));

    const owned_digest = try arena.dupe(u8, digest);
    var hex_buf: [2 * digest_len]u8 = undefined;
    const name = try arena.dupe(u8, digestToWireName(owned_digest, &hex_buf));

    // THE CURRENT-CHECKOUT STOP IS CHECKED FIRST, ahead of the shun table. An
    // already-tombstoned check-in whose bytes survive is otherwise `.reclaim`, and
    // reclaiming it would delete the check-in the operator is standing on — the one
    // thing this verb refuses outright. `--defer` goes through this same guard, so
    // the state cannot arise through zit today; the ordering is what keeps that
    // true if it ever does.
    if (std.mem.eql(u8, name, ck_version)) return .{
        .name = name,
        .digest = owned_digest,
        .disposition = .current_checkout,
    };
    const already = src.isShunned(owned_digest);

    const rid = src.lookup(owned_digest) orelse return .{
        .name = name,
        .digest = owned_digest,
        .disposition = if (already) .already else .absent,
    };
    // THROUGH THE MAINTENANCE READER, deliberately. `content` applies the shun
    // mask, so an already-shunned artifact whose bytes are still on disk would read
    // as absent and be reported as nothing left to do — which is the whole defect
    // `.reclaim` exists to prevent. Shunning is maintenance, not an artifact read.
    //
    // A phantom is an announced name with no frame: there are no bytes to reclaim,
    // so it is the `absent` case with a rid attached.
    const content = (try src.contentUnmasked(gpa, rid, null)) orelse return .{
        .name = name,
        .digest = owned_digest,
        .disposition = if (already) .already else .absent,
    };
    defer gpa.free(content);

    // The type verdict, through the same door `zit artifact` uses: a structural
    // artifact classifies (`parseWindow` runs §5's `classify` internally), and
    // anything that does not parse is an opaque blob — a first-class answer, not
    // an error. A blob is by far the common shun target.
    const held: ShunDisposition = if (already) .reclaim else .remove;
    var m = artifact.parseWindow(gpa, content) catch |e| switch (e) {
        error.OutOfMemory => return error.OutOfMemory,
        else => return .{ .name = name, .digest = owned_digest, .kind = null, .disposition = held },
    };
    defer m.deinit();
    return .{ .name = name, .digest = owned_digest, .kind = m.kind, .disposition = held };
}

// --- `zit shun`'s pure renderers -------------------------------------------
//
// Every operator-visible byte this verb emits is produced by a function of data
// alone, for the same reason `renderPackStats` is: the exact wording of a
// refusal that precedes irreversible deletion is the part most worth pinning,
// and pinning it through a subprocess would make the e2e tests the only place
// it is stated.

const shun_name_a = "1c04b7" ++ repeat("0", 58);

const shun_name_b = "7bd1e0" ++ repeat("1", 58);

const shun_name_c = "9f2a1c" ++ repeat("2", 58);

test "renderShunRefusal: the counts and the word refusing share the first line, then one line per hash" {
    // The register is `clean`'s (`cleanRefuse`): an operator must not have to read
    // six lines of inventory to discover that nothing happened.
    var buf: [1024]u8 = undefined;
    var w: std.Io.Writer = .fixed(&buf);
    renderShunRefusal(&w, &.{
        .{ .name = shun_name_a, .kind = .manifest, .disposition = .remove },
        .{ .name = shun_name_b, .kind = null, .disposition = .remove },
        .{ .name = shun_name_c, .disposition = .absent },
    }, 0, false);
    try std.testing.expectEqualStrings(
        "zit shun: 3 hashes would be shunned in this repository; 2 artifacts would be permanently removed; refusing without --force:\n" ++
            "\n" ++
            "  " ++ shun_name_a ++ "  checkin  a check-in; its descendants become unresolvable\n" ++
            "  " ++ shun_name_b ++ "  file  file content; every check-in listing it loses that file\n" ++
            "  " ++ shun_name_c ++ "  recorded only (not present in this repository)\n" ++
            "\n" ++
            "This is irreversible: zit undo does not recover a shun, and the content\n" ++
            "cannot be re-fetched from a peer.\n" ++
            "run 'zit shun --force <HASH>...' to proceed\n",
        w.buffered(),
    );
}

test "renderShunRefusal: singular agreement, an already-shunned line, and the nothing-held wording" {
    var buf: [1024]u8 = undefined;
    {
        // One target, held here: "1 hash", "1 artifact".
        var w: std.Io.Writer = .fixed(&buf);
        renderShunRefusal(&w, &.{
            .{ .name = shun_name_a, .kind = .wiki, .disposition = .remove },
            .{ .name = shun_name_b, .disposition = .already },
        }, 0, false);
        try std.testing.expectEqualStrings(
            "zit shun: 1 hash would be shunned in this repository; 1 artifact would be permanently removed; refusing without --force:\n" ++
                "\n" ++
                "  " ++ shun_name_a ++ "  wiki  structural content; what it renders stops rendering\n" ++
                "  " ++ shun_name_b ++ "  already shunned; content already gone\n" ++
                "\n" ++
                "This is irreversible: zit undo does not recover a shun, and the content\n" ++
                "cannot be re-fetched from a peer.\n" ++
                "run 'zit shun --force <HASH>...' to proceed\n",
            w.buffered(),
        );
    }
    {
        // A purely pre-emptive run: the tombstones are still irreversible, so the
        // refusal stands, but nothing would be removed and the line says so
        // instead of claiming a removal that is not going to happen.
        var w: std.Io.Writer = .fixed(&buf);
        renderShunRefusal(&w, &.{.{ .name = shun_name_c, .disposition = .absent }}, 0, false);
        try std.testing.expectEqualStrings(
            "zit shun: 1 hash would be shunned in this repository; nothing you named holds content to remove; refusing without --force:\n" ++
                "\n" ++
                "  " ++ shun_name_c ++ "  recorded only (not present in this repository)\n" ++
                "\n" ++
                "This is irreversible: zit undo does not recover a shun, and the content\n" ++
                "cannot be re-fetched from a peer.\n" ++
                "run 'zit shun --force <HASH>...' to proceed\n",
            w.buffered(),
        );
    }
}

test "renderShunRefusal: a reclaim-only run, and the collateral an earlier --defer left behind" {
    // THE CONSENT GATE MUST NAME EVERYTHING THE REWRITE DESTROYS, including what the
    // operator did not name. `renderShunStats` is honest after the fact that
    // `dropped` can exceed `recorded`; a refusal that only counted this
    // invocation's own targets would have the operator consent to one deletion and
    // get several.
    var buf: [1024]u8 = undefined;
    var w: std.Io.Writer = .fixed(&buf);
    renderShunRefusal(&w, &.{
        .{ .name = shun_name_a, .kind = null, .disposition = .reclaim },
    }, 2, false);
    try std.testing.expectEqualStrings(
        "zit shun: no new hash would be recorded; 1 artifact would be permanently removed; " ++
            "the same rewrite also removes 2 artifacts shunned earlier and not yet reclaimed; " ++
            "refusing without --force:\n" ++
            "\n" ++
            "  " ++ shun_name_a ++ "  file  already shunned; content still here and would be removed\n" ++
            "\n" ++
            "This is irreversible: zit undo does not recover a shun, and the content\n" ++
            "cannot be re-fetched from a peer.\n" ++
            "run 'zit shun --force <HASH>...' to proceed\n",
        w.buffered(),
    );
}

test "renderShunRefusal: a --defer run is described as a --defer run, and suggests --defer --force" {
    // THE CONSENT GATE MUST DESCRIBE THE OPERATION THE OPERATOR ASKED FOR. A
    // `--defer` run removes nothing now, so it must not say "would be permanently
    // removed"; it must not attribute rewrite collateral to a run that performs no
    // rewrite; and — the reason this is pinned byte for byte — the command it
    // suggests must be the deferred one. An operator who copies `zit shun --force`
    // out of a `--defer` refusal escalates a tombstone into a full-store reclaim of
    // the whole union set, including collateral this run never named.
    var buf: [1024]u8 = undefined;
    {
        // `deferred_held` is 2 here and the clause must NOT appear: nothing on this
        // path reclaims those rows.
        var w: std.Io.Writer = .fixed(&buf);
        renderShunRefusal(&w, &.{
            .{ .name = shun_name_a, .kind = .manifest, .disposition = .remove },
            .{ .name = shun_name_b, .kind = null, .disposition = .remove },
            .{ .name = shun_name_c, .disposition = .absent },
        }, 2, true);
        try std.testing.expectEqualStrings(
            "zit shun: 3 hashes would be shunned in this repository; " ++
                "the bytes of 2 artifacts stay on disk and stay reconstructible until 'zit pack'; " ++
                "refusing without --force:\n" ++
                "\n" ++
                "  " ++ shun_name_a ++ "  checkin  a check-in; its descendants become unresolvable\n" ++
                "  " ++ shun_name_b ++ "  file  file content; every check-in listing it loses that file\n" ++
                "  " ++ shun_name_c ++ "  recorded only (not present in this repository)\n" ++
                "\n" ++
                "This is irreversible: zit undo does not recover a shun, and the content\n" ++
                "cannot be re-fetched from a peer.\n" ++
                "run 'zit shun --defer --force <HASH>...' to proceed\n",
            w.buffered(),
        );
    }
    {
        // Singular agreement on the deferred clause, and the `.reclaim` line: under
        // `--defer` the content stays rather than being removed.
        var w: std.Io.Writer = .fixed(&buf);
        renderShunRefusal(&w, &.{
            .{ .name = shun_name_a, .kind = .wiki, .disposition = .reclaim },
        }, 0, true);
        try std.testing.expectEqualStrings(
            "zit shun: no new hash would be recorded; " ++
                "the bytes of 1 artifact stay on disk and stay reconstructible until 'zit pack'; " ++
                "refusing without --force:\n" ++
                "\n" ++
                "  " ++ shun_name_a ++ "  wiki  already shunned; content still here and stays\n" ++
                "\n" ++
                "This is irreversible: zit undo does not recover a shun, and the content\n" ++
                "cannot be re-fetched from a peer.\n" ++
                "run 'zit shun --defer --force <HASH>...' to proceed\n",
            w.buffered(),
        );
        // The escalating suggestion must be ABSENT, not merely reworded: this is the
        // one substring an operator is most likely to paste.
        try std.testing.expect(std.mem.indexOf(u8, w.buffered(), "run 'zit shun --force") == null);
    }
    {
        // Nothing named holds content: the wording is the same on both paths, and
        // only the suggested command differs.
        var w: std.Io.Writer = .fixed(&buf);
        renderShunRefusal(&w, &.{.{ .name = shun_name_c, .disposition = .absent }}, 0, true);
        try std.testing.expectEqualStrings(
            "zit shun: 1 hash would be shunned in this repository; " ++
                "nothing you named holds content to remove; refusing without --force:\n" ++
                "\n" ++
                "  " ++ shun_name_c ++ "  recorded only (not present in this repository)\n" ++
                "\n" ++
                "This is irreversible: zit undo does not recover a shun, and the content\n" ++
                "cannot be re-fetched from a peer.\n" ++
                "run 'zit shun --defer --force <HASH>...' to proceed\n",
            w.buffered(),
        );
    }
}

test "shunConsequence/shunTypeLabel: one arm per consequence, total over ArtifactType" {
    // The per-type diagnostic, pinned type by type. The switch is total, so this
    // test and the compiler together guarantee a type added later cannot ship
    // with no warning attached to its removal.
    try std.testing.expectEqualStrings("file", shunTypeLabel(null));
    try std.testing.expectEqualStrings(
        "file content; every check-in listing it loses that file",
        shunConsequence(null),
    );
    try std.testing.expectEqualStrings("checkin", shunTypeLabel(.manifest));
    try std.testing.expectEqualStrings(
        "a check-in; its descendants become unresolvable",
        shunConsequence(.manifest),
    );
    try std.testing.expectEqualStrings("cluster", shunTypeLabel(.cluster));
    try std.testing.expectEqualStrings("sync housekeeping only; regenerable", shunConsequence(.cluster));
    // The six that all stop rendering share one arm; their LABELS still differ,
    // so the operator can tell a ticket from a forum post.
    const rendering = "structural content; what it renders stops rendering";
    inline for (.{ .control, .wiki, .ticket, .attachment, .event, .forum }) |k| {
        try std.testing.expectEqualStrings(rendering, shunConsequence(k));
    }
    try std.testing.expectEqualStrings("tag", shunTypeLabel(.control));
    try std.testing.expectEqualStrings("technote", shunTypeLabel(.event));
    try std.testing.expectEqualStrings("forumpost", shunTypeLabel(.forum));
}

test "renderShunBlockers: the unconditional stops, one line each, with no --force offered" {
    // The current-checkout stop is the only refusal in this verb with no
    // override, so its text must NOT mention --force — an operator who reads a
    // flag out of it will try the flag and be refused twice.
    var buf: [1024]u8 = undefined;
    var w: std.Io.Writer = .fixed(&buf);
    renderShunBlockers(&w, &.{
        .{ .name = shun_name_a, .kind = .manifest, .disposition = .current_checkout },
        .{ .name = "nothex", .disposition = .not_a_name },
        .{ .name = "1c04", .disposition = .unresolved },
        .{ .name = "7bd1", .disposition = .ambiguous },
        // A permissive target contributes nothing to this block.
        .{ .name = shun_name_c, .disposition = .remove },
    });
    try std.testing.expectEqualStrings(
        "zit shun: " ++ shun_name_a ++ " is the check-in this checkout is on; refusing\n" ++
            "run 'zit update' to a different check-in first\n" ++
            "zit shun: 'nothex' is not an artifact name\n" ++
            "zit shun: no artifact matches '1c04'; give the complete name to shun a hash this repository does not hold\n" ++
            "zit shun: hash '7bd1' is ambiguous\n",
        w.buffered(),
    );
    try std.testing.expect(std.mem.indexOf(u8, w.buffered(), "--force") == null);
}

test "renderShunStats/renderShunDeferred: the two success lines" {
    var buf: [256]u8 = undefined;
    {
        var w: std.Io.Writer = .fixed(&buf);
        renderShunStats(&w, .{
            .artifacts = 12,
            .deltas = 4,
            .dropped = 3,
            .shuns_recorded = 3,
            .bytes_before = 481232,
            .bytes_after = 402118,
        });
        try std.testing.expectEqualStrings(
            "shunned: 3 hashes recorded, 3 artifacts removed, 12 -> 9 remaining, 481232 -> 402118 bytes\n",
            w.buffered(),
        );
    }
    {
        // `dropped` legitimately EXCEEDS `recorded`: the same rewrite reclaims
        // shuns deferred by earlier runs, and an operator must be told that
        // rather than left to infer it from the byte count.
        var w: std.Io.Writer = .fixed(&buf);
        renderShunStats(&w, .{
            .artifacts = 12,
            .deltas = 4,
            .dropped = 4,
            .shuns_recorded = 1,
            .bytes_before = 8192,
            .bytes_after = 4096,
        });
        try std.testing.expectEqualStrings(
            "shunned: 1 hash recorded, 4 artifacts removed, 12 -> 8 remaining, 8192 -> 4096 bytes\n",
            w.buffered(),
        );
    }
    {
        // THE RECORDED COUNT IS THE PACK'S, NOT THE CALLER'S. `shuns_recorded` is
        // measured off the new generation's own shun table, so this line cannot
        // over-report a takedown even if a caller's intent and the pack's result ever
        // diverged. Two tombstones, and this rewrite reclaimed nothing.
        var w: std.Io.Writer = .fixed(&buf);
        renderShunStats(&w, .{
            .artifacts = 12,
            .deltas = 4,
            .dropped = 0,
            .shuns_recorded = 2,
            .bytes_before = 8192,
            .bytes_after = 8320,
        });
        try std.testing.expectEqualStrings(
            "shunned: 2 hashes recorded, 0 artifacts removed, 12 -> 12 remaining, 8192 -> 8320 bytes\n",
            w.buffered(),
        );
    }
    {
        // --defer promises no byte count: nothing on that path measured one.
        var w: std.Io.Writer = .fixed(&buf);
        renderShunDeferred(&w, 2, 2, null);
        try std.testing.expectEqualStrings(
            "shunned: 2 hashes recorded; run 'zit pack' to reclaim the space\n",
            w.buffered(),
        );
    }
    {
        var w: std.Io.Writer = .fixed(&buf);
        renderShunDeferred(&w, 1, 1, null);
        try std.testing.expectEqualStrings(
            "shunned: 1 hash recorded; run 'zit pack' to reclaim the space\n",
            w.buffered(),
        );
    }
    {
        // On a bare store the hint names the store the run was given.
        var w: std.Io.Writer = .fixed(&buf);
        renderShunDeferred(&w, 1, 1, "forge/s.zit");
        try std.testing.expectEqualStrings(
            "shunned: 1 hash recorded; run 'zit pack -R forge/s.zit' to reclaim the space\n",
            w.buffered(),
        );
    }
    {
        // Re-deferring a hash already deferred: no row to add, and yet content still
        // to lose. "0 hashes recorded" would read as a no-op over live bytes.
        var w: std.Io.Writer = .fixed(&buf);
        renderShunDeferred(&w, 0, 1, null);
        try std.testing.expectEqualStrings(
            "shunned: no new hash to record; 1 artifact still holds content; run 'zit pack' to reclaim the space\n",
            w.buffered(),
        );
    }
    {
        // The purely pre-emptive success line: no rewrite ran, so it claims no byte
        // count AND does not claim a removal.
        var w: std.Io.Writer = .fixed(&buf);
        renderShunRecordedOnly(&w, 1);
        try std.testing.expectEqualStrings(
            "shunned: 1 hash recorded; none is held here, so nothing was removed\n",
            w.buffered(),
        );
    }
}

test "renderShunList: persisted order, the recorded date, and the reason only when given" {
    var buf: [512]u8 = undefined;
    {
        var w: std.Io.Writer = .fixed(&buf);
        renderShunList(&w, &.{});
        try std.testing.expectEqualStrings("the shun table is empty\n", w.buffered());
    }
    {
        // 1753660800 = 2025-07-28T00:00:00Z; 1752192000 = 2025-07-11T00:00:00Z.
        // A row with no reason prints no trailing separator at all.
        var w: std.Io.Writer = .fixed(&buf);
        renderShunList(&w, &.{
            .{ .hash = "\x9f\x2a\x1c" ++ repeat("\x00", 29), .epoch = 1753660800, .reason = "legal takedown ref #4417" },
            .{ .hash = "\x1c\x04\xb7" ++ repeat("\x00", 17), .epoch = 1753660800, .reason = "" },
            .{ .hash = "\x7b\xd1\xe0" ++ repeat("\x00", 29), .epoch = 1752192000, .reason = "committed credential" },
        });
        try std.testing.expectEqualStrings(
            "9f2a1c" ++ repeat("00", 29) ++ "  2025-07-28  legal takedown ref #4417\n" ++
                "1c04b7" ++ repeat("00", 17) ++ "  2025-07-28\n" ++
                "7bd1e0" ++ repeat("00", 29) ++ "  2025-07-11  committed credential\n",
            w.buffered(),
        );
    }
}

/// How many rows the store in `dir` holds in its shun table.
fn shunRowsIn(gpa: std.mem.Allocator, io: std.Io, dir: std.Io.Dir) !usize {
    var fs: storage.FileStorage = undefined;
    var log = try packOpenReadOnly(gpa, io, dir, &fs);
    defer fs.file.close(io);
    defer log.deinit(gpa);
    return log.shunList().len;
}

test "shunAppendRows: the append aborts on a changed tail and on a held temp lock, recording nothing" {
    // THE APPEND PATH'S TWO CONCURRENCY GUARDS, driven directly because neither is
    // reachable from the CLI in one process: both windows open between the moment
    // `runShun` classified its targets and the moment this function commits.
    //
    // The TAIL guard is what makes the append path's success lines honest. They are
    // claims about STORE STATE — "none is held here, so nothing was removed" — and a
    // `zit commit` landing a named hash in that window falsifies them: the tombstone
    // would be recorded, exit 0, and an operator under a takedown order told nothing
    // was held while the bytes were live and unreclaimed.
    //
    // The LOCK guard is what stops the row being written to an ORPHANED INODE. A
    // `zit pack` renaming its new generation over `.zit` after our `openFile` takes
    // the append with it, and the run would still report success — a deferred shun
    // that silently does not exist, having just told the operator to run `zit pack`
    // to finish it.
    const gpa = std.testing.allocator;
    const io = std.testing.io;
    var tmp = std.testing.tmpDir(.{});
    defer tmp.cleanup();

    var tip: [64]u8 = undefined;
    {
        var wfs: storage.FileStorage = undefined;
        var wlog = try packOpenWritable(gpa, io, tmp.dir, &wfs);
        defer wfs.file.close(io);
        defer wlog.deinit(gpa);
        try packSeedFullStore(gpa, &wlog, &tip);
    }

    const digest_a = @as([digest_len]u8, @splat(0xab));
    const digest_b = @as([digest_len]u8, @splat(0xcd));
    const rows_a = [_]logstore.ShunRecord{.{ .hash = &digest_a, .epoch = 1_753_660_800, .reason = "" }};
    const rows_b = [_]logstore.ShunRecord{.{ .hash = &digest_b, .epoch = 1_753_660_800, .reason = "" }};

    // The key the runner would have captured off its read-only snapshot.
    var key_1: logstore.LogStore.LogKey = undefined;
    {
        var sfs: storage.FileStorage = undefined;
        var src = try packOpenReadOnly(gpa, io, tmp.dir, &sfs);
        defer sfs.file.close(io);
        defer src.deinit(gpa);
        key_1 = try src.logKey();
    }

    // Control: with a current key the append lands, so the guards below are failing
    // for the reason under test rather than because this path never works.
    try shunAppendRows(gpa, io, tmp.dir, key_1, &rows_a);
    try std.testing.expectEqual(@as(usize, 1), try shunRowsIn(gpa, io, tmp.dir));
    // No temp left behind: the lock file is removed on the success path too.
    try std.testing.expectError(error.FileNotFound, tmp.dir.openFile(io, pack_tmp_filename, .{}));

    // That append is itself the "concurrent writer": `key_1` is now stale.
    const before = try tmp.dir.readFileAlloc(io, repo_filename, gpa, .limited(1 << 24));
    defer gpa.free(before);
    try std.testing.expectError(error.TailChanged, shunAppendRows(gpa, io, tmp.dir, key_1, &rows_b));
    // NOTHING WRITTEN: the check precedes the first `putShun`.
    try std.testing.expectEqual(@as(usize, 1), try shunRowsIn(gpa, io, tmp.dir));
    {
        const after = try tmp.dir.readFileAlloc(io, repo_filename, gpa, .limited(1 << 24));
        defer gpa.free(after);
        try std.testing.expectEqualSlices(u8, before, after);
    }

    var key_2: logstore.LogStore.LogKey = undefined;
    {
        var sfs: storage.FileStorage = undefined;
        var src = try packOpenReadOnly(gpa, io, tmp.dir, &sfs);
        defer sfs.file.close(io);
        defer src.deinit(gpa);
        key_2 = try src.logKey();
    }

    {
        // Stand in for the concurrent rewrite with a rewrite lock naming a live
        // process that is not this one (this test's parent), which makes this
        // deterministic rather than a race.
        var host_buf: [std.posix.HOST_NAME_MAX]u8 = undefined;
        const host = try std.posix.gethostname(&host_buf);
        const parent: i64 = if (@import("builtin").os.tag == .linux) std.os.linux.getppid() else std.c.getppid();
        var rec_buf: [256]u8 = undefined;
        const rec = try std.fmt.bufPrint(&rec_buf, "pid={d} host={s} time=1\n", .{ parent, host });
        try tmp.dir.writeFile(io, .{ .sub_path = rewrite_lock_name, .data = rec });
        defer tmp.dir.deleteFile(io, rewrite_lock_name) catch {};
        try std.testing.expectError(error.RewriteBusy, shunAppendRows(gpa, io, tmp.dir, key_2, &rows_b));
        try std.testing.expectEqual(@as(usize, 1), try shunRowsIn(gpa, io, tmp.dir));
        const after = try tmp.dir.readFileAlloc(io, repo_filename, gpa, .limited(1 << 24));
        defer gpa.free(after);
        try std.testing.expectEqualSlices(u8, before, after);
    }
    // Released and current: the same call now lands.
    try shunAppendRows(gpa, io, tmp.dir, key_2, &rows_b);
    try std.testing.expectEqual(@as(usize, 2), try shunRowsIn(gpa, io, tmp.dir));
}