Skip to content
zit Artifact [9606f68dd9]
Login

Artifact [9606f68dd9]

Artifact 9606f68dd98ae7c3eb3538b810942e483061401446e8b9e13e9f6ec7423051bb:


//! Minting one control artifact (a T-card run over a check-in) durably into
//! the store, shared by `commit`, `amend`, `tag` and `branch`.

const std = @import("std");
const zit = @import("zit");
const cli = @import("zit").cli;
const logstore = @import("zit").logstore;
const storage = @import("zit").storage;
const artifact = zit.artifact;

/// `zit amend NAME [--comment TEXT] [--user NAME] [--date ISO] [--branch NAME]`
/// (contracts/amend.md B-amend-1..17). amend NEVER rewrites a check-in: it mints
/// ONE control artifact whose T cards change how the target check-in DISPLAYS
/// (comment/user/date/branch), which the crosslinker applies on the next read
/// (repo-state §4/§5). History stays append-only — the original manifest is
/// untouched (B-amend-5). The one durable write is the control artifact + log
/// fsync; every validation (parse, NAME resolution, `--date` predicate,
/// target-is-a-check-in) precedes it, so a refusal mints nothing.
/// Assemble the ONE control artifact carrying `tags`, serialize it (artifact
/// §5.2: exactly D, T…, U, Z), and store it durably in the log — the single
/// fsync. Returns its 64-hex artifact name, written into `name_buf`.
///
/// This is the mint step shared by `amend` and `tag add`: both compose a T run
/// over a resolved check-in and then need exactly this. Everything a caller does
/// before calling is read-only or in-memory, so a crash before the call mints
/// nothing; after it returns, the control is durable and crosslinks on the next
/// read (B-amend-5/7). The library owns card order, escaping, the Z self-check,
/// and framing. D is the mint time — the §5.3 supersede clock (B-amend-6); U is
/// the author's env login (empty → `anonymous` on read, §4.7.17).
///
/// The error set is `logstore.OpenError`, the widest of the three the body can
/// produce, so one caller-side mapper renders all of them under its own verb.
/// `StoreBusy`: the writer lock stayed held, and stderr already says so.
pub const MintError = logstore.OpenError || error{StoreBusy};

pub fn mintControlArtifact(
    gpa: std.mem.Allocator,
    io: std.Io,
    root_dir: std.Io.Dir,
    amb: cli.Ambient,
    tags: []const artifact.TCard,
    name_buf: *[64]u8,
) MintError![]const u8 {
    std.debug.assert(tags.len >= 1); // a control artifact with no T run says nothing
    var ts_buf: [23]u8 = undefined;
    const ts = cli.formatWriterTimestampMs(amb.now_epoch, amb.now_ms, &ts_buf);
    var m: artifact.Manifest = .{
        .arena_state = std.heap.ArenaAllocator.init(gpa),
        .kind = .control,
        .a = null,
        .b = null,
        .c = null,
        .d = .{ .timestamp = ts },
        .e = null,
        .g = null,
        .h = null,
        .i = null,
        .k = null,
        .l = null,
        .n = null,
        .r = null,
        .u = .{ .login = amb.user_env orelse "" },
        .z = null,
        .w = null,
        .f = &.{},
        .j = &.{},
        .m = &.{},
        .p = &.{},
        .q = &.{},
        .t = tags,
    };
    defer m.deinit(); // frees the empty arena_state; card storage is the caller's
    const bytes = try artifact.create(&m, gpa);
    defer gpa.free(bytes);
    // Correctness self-check (safety builds only): the emitted bytes round-trip
    // to a control artifact. A failure means the CLI mis-populated a card — a bug
    // caught here, never shipped (mirrors commit's self-check).
    if (std.debug.runtime_safety) {
        var check = artifact.parse(gpa, bytes) catch |e|
            std.debug.panic("the control mint produced an unparseable artifact: {s}", .{@errorName(e)});
        defer check.deinit();
        std.debug.assert(check.kind == .control);
    }

    var store_append = cli.openStoreAppend(io, root_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 log_st = file.stat(io) catch return error.Storage;
    var fs = storage.FileStorage.init(io, file, log_st.size);
    var log = try logstore.LogStore.open(gpa, fs.storageFile(), 0);
    defer log.deinit(gpa);

    var cdigest: [zit.digest_name.digest_len]u8 = undefined;
    std.crypto.hash.sha3.Sha3_256.hash(bytes, &cdigest, .{});
    const control_name = artifact.artifactName(.sha3_256, bytes, name_buf);
    _ = try log.putArtifact(&cdigest, bytes, null);
    try log.commit();
    return control_name;
}