//! 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;
}