//! `zit submanifest`: show, enable, disable, retune and analyze sub-manifests.
const std = @import("std");
const zit = @import("zit");
const cli = @import("zit").cli;
const cmd_tracking = @import("tracking.zig");
const logstore = @import("zit").logstore;
const storage = @import("zit").storage;
const checkout = @import("zit").checkout;
const Repository = @import("zit").Repository;
const artifact = zit.artifact;
const diagnostics = @import("../diagnostics.zig");
const help_pages = @import("../help.zig");
const max_tracked_file_bytes = cmd_tracking.max_tracked_file_bytes;
// ---------------------------------------------------------------------------
// `zit submanifest [show|enable|disable|retune|analyze]` — the sub-manifest
// operator surface (draft-fossil-submanifests-00 §6.3, §6.4, §8.1).
//
// Four actions over two settings. `show` reports them; `enable`/`disable` move
// §8.1's emission gate, `enable` pinning §6.3's partition parameter the first
// time and printing the consequence warning; `retune` performs §6.4's manual,
// forward-only re-pin; `analyze` runs §6.3's selection pass and writes nothing.
//
// §8.1's flag day makes enabling an act with real consequences: the card
// alphabet is closed, so a peer that does not announce support (§7.2) sees a
// truncated check-in graph from the first tree on. Enabling is therefore
// opt-in with the warning printed, not a silent toggle and not an
// indefinite refusal: the maintainer's compatibility contract says zit 0.2.0
// stays backwards compatible with fossil, and it does — the DEFAULT is off, and
// §7.2's transfer gate refuses every S-bearing artifact to a peer that has not
// sent `send-submanifests` rather than hand it something it cannot read.
// ---------------------------------------------------------------------------
pub fn runSubmanifest(
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.parseSubmanifestArgs(verb_args)) {
.ok => |p| p,
.unknown_option => |tok| return cli.usageError(streams, "submanifest", .unknown_option, tok),
.extra_argument => |tok| return cli.usageError(streams, "submanifest", .extra_argument, tok),
.bad_k => |tok| {
streams.err.print(
"zit submanifest: --k wants an integer {d}..{d} (got '{s}')\n",
.{ artifact.min_k, artifact.max_k, tok },
) catch {};
streams.err.writeAll("try 'zit submanifest --help'\n") catch {};
return .usage;
},
.missing_value => |tok| {
streams.err.print("zit submanifest: {s} wants a path\n", .{tok}) catch {};
streams.err.writeAll("try 'zit submanifest --help'\n") catch {};
return .usage;
},
};
if (parsed.help) {
streams.out.writeAll(help_pages.submanifest_help) catch {};
return .ok;
}
// Settings-writing actions operate on the repository the checkout names;
// only `analyze` (a pure measurement) honors -R -- the conversion
// gate's pre-flight runs against a bare cloned store.
if (amb.repo_override != null and parsed.action != .analyze) {
streams.err.writeAll("zit submanifest: -R/--repo works with 'analyze' only; settings live in the repository the checkout names\n") catch {};
return .failure;
}
if (parsed.replay_all and parsed.action != .analyze) {
streams.err.writeAll("zit submanifest: --replay-all is an 'analyze' option\n") catch {};
return .usage;
}
const root = (cli.resolveRoot(arena, io, amb.repo_override) catch return submanifestOom(streams)) orelse {
diagnostics.reportNoRoot(streams, io, "submanifest", amb.repo_override);
return .failure;
};
var root_dir = root.dir;
defer root_dir.close(io);
return switch (parsed.action) {
.show => submanifestShow(gpa, io, root_dir, streams),
.enable => submanifestEnable(gpa, io, root_dir, parsed.k, streams),
.disable => submanifestDisable(gpa, io, root_dir, streams),
.retune => submanifestRetune(gpa, io, root_dir, parsed.k, streams),
.analyze => submanifestAnalyze(gpa, io, root_dir, parsed.names_path, parsed.replay_all, streams),
// Routed by main.zig before a checkout is resolved.
.convert => .usage,
};
}
/// Read the repository's config frame. A missing or unreadable frame is a
/// repository-level failure here (unlike on the commit path, where the safe
/// default is simply "off"): every action below either reports the settings or
/// rewrites them, and both would be lies over a config that did not load.
fn submanifestConfig(
gpa: std.mem.Allocator,
io: std.Io,
root_dir: std.Io.Dir,
streams: cli.Streams,
) ?logstore.OwnedConfig {
var file = cli.openStoreRead(io, root_dir) catch |e| {
streams.err.print("zit submanifest: cannot read the repository: {s}\n", .{diagnostics.reasonOf(e)}) catch {};
return null;
};
defer file.close(io);
const st = file.stat(io) catch {
streams.err.writeAll("zit submanifest: cannot read the repository\n") catch {};
return null;
};
var fs = storage.FileStorage.init(io, file, st.size);
// Through the saved log index, as `info` opens, so one config value does
// not cost a header read per frame; a missing index is built here once.
var resolved = checkout.storeDirOf(io, root_dir) catch null;
defer if (resolved) |*r| r.close(io);
var log = Repository.openLogIndexed(gpa, io, resolved orelse root_dir, fs.storageFile(), false) catch {
streams.err.writeAll("zit submanifest: cannot read the repository\n") catch {};
return null;
};
defer log.deinit(gpa);
const oc = log.readConfig(gpa) catch {
streams.err.writeAll("zit submanifest: cannot read the repository\n") catch {};
return null;
};
if (oc == null) {
streams.err.writeAll("zit submanifest: the repository carries no configuration\n") catch {};
return null;
}
return oc;
}
/// An outer null preserves the cached value; an outer non-null writes its inner
/// value, including null to conservatively clear an unreadable checkout's cache.
/// This is implementation-only state, not an RFC setting.
pub fn replaceSettledCostShape(shape: ?[32]u8) ??[32]u8 {
return shape;
}
/// Read-modify-write of the sub-manifest settings, preserving every unrelated
/// config field (plan E last-frame-wins). `settled_cost_shape` is tri-state so only
/// disable may preserve its cache; enable and retune replace it even with null.
pub fn submanifestWrite(
gpa: std.mem.Allocator,
io: std.Io,
root_dir: std.Io.Dir,
enabled: ?bool,
k: ?u8,
settled_cost_shape: ??[32]u8,
streams: cli.Streams,
) bool {
var store_append = cli.openStoreAppend(io, root_dir) catch |e| {
if (e == error.StoreBusy) return false; // the lock notice already said it
streams.err.writeAll("zit submanifest: cannot write the repository\n") catch {};
return false;
};
defer store_append.close(io);
const file = store_append.file;
const st = file.stat(io) catch {
streams.err.writeAll("zit submanifest: cannot write the repository\n") catch {};
return false;
};
var fs = storage.FileStorage.init(io, file, st.size);
var log = logstore.LogStore.open(gpa, fs.storageFile(), 0) catch {
streams.err.writeAll("zit submanifest: cannot write the repository\n") catch {};
return false;
};
defer log.deinit(gpa);
var oc = (log.readConfig(gpa) catch null) orelse {
streams.err.writeAll("zit submanifest: the repository carries no configuration\n") catch {};
return false;
};
defer oc.deinit(gpa);
var next = oc.config;
if (enabled) |value| next.enable_submanifests = value;
if (k) |value| next.submanifest_k = value;
if (settled_cost_shape) |shape| next.submanifest_settled_cost_shape = shape;
log.putConfig(next) catch {
streams.err.writeAll("zit submanifest: cannot write the repository\n") catch {};
return false;
};
log.commit() catch {
streams.err.writeAll("zit submanifest: cannot write the repository\n") catch {};
return false;
};
return true;
}
fn submanifestShow(
gpa: std.mem.Allocator,
io: std.Io,
root_dir: std.Io.Dir,
streams: cli.Streams,
) cli.Exit {
var oc = submanifestConfig(gpa, io, root_dir, streams) orelse return .failure;
defer oc.deinit(gpa);
const s: zit.submanifest.Settings = .of(oc.config);
streams.out.print("enable-submanifests: {s}\n", .{if (s.enabled) "on" else "off"}) catch {};
if (s.pinned()) {
streams.out.print("submanifest-k: {d}\n", .{s.k}) catch {};
} else {
streams.out.writeAll("submanifest-k: (not pinned)\n") catch {};
}
// §6.4's `submanifest-auto-retune` — shown because it is now a PROPAGATED
// setting: a clone adopts it from its origin over sync §9.3, so an operator
// can arrive at a repository that re-tunes on commit without ever having
// set it here. A setting that can reach a repository without the operator's
// act has to be visible to the operator.
streams.out.print(
"submanifest-auto-retune: {s}\n",
.{if (oc.config.submanifest_auto_retune) "on" else "off"},
) catch {};
// §8.1's local indicator, the thing that arms the §7.2 transfer gate even
// after the setting is turned back off. Worth showing: it is the durable
// record that peers unable to read trees no longer see this repository's
// whole history.
streams.out.print(
"seen-submanifest: {s}\n",
.{if (oc.config.seen_submanifest) "yes (this repository holds S-bearing artifacts)" else "no"},
) catch {};
switch (zit.submanifest.emission(s)) {
.off => streams.out.writeAll("commits emit: flat manifests\n") catch {},
.out_of_range => |v| streams.out.print(
"commits emit: flat manifests — {s} ({d}; must be {d}..{d})\n",
.{ zit.submanifest.out_of_range_report_prefix, v, artifact.min_k, artifact.max_k },
) catch {},
.tree => |v| streams.out.print("commits emit: tree manifests, partitioned at k={d}\n", .{v}) catch {},
}
// §6.3's project-scope requirement is not met; say so where an operator will
// read it rather than only in a source comment.
streams.out.writeAll(submanifest_scope_gap) catch {};
return .ok;
}
/// §6.3 — "Project scope (configuration propagating to clones) is REQUIRED".
/// A clone now adopts these settings over [FossilSync] §9.3's scalar `/config`
/// channel, so the shortfall is narrower than it was: what remains is that a
/// repository already in existence never re-reads them from a peer. Printed by
/// `show` and by `enable`, and kept honest about which half works.
const submanifest_scope_gap =
"\nscope: a CLONE adopts these settings from its origin (§6.3 project scope, over\n" ++
"the sync §9.3 configuration exchange), so a fresh clone partitions the way this\n" ++
"repository does. An EXISTING repository is not refreshed by a later pull or\n" ++
"sync — change it here and on each peer. Repositories pinned differently still\n" ++
"exchange artifacts correctly (§6.4) — they just stop sharing sub-manifests.\n";
/// The cache key is an effective F-set shape, never a checkout filename list.
/// Failure to read the current check-in leaves the setting change valid but
/// uncached; the following commit then conservatively scans.
fn submanifestSettledShape(
gpa: std.mem.Allocator,
io: std.Io,
root_dir: std.Io.Dir,
) ?[32]u8 {
var arena_state = std.heap.ArenaAllocator.init(gpa);
defer arena_state.deinit();
const arena = arena_state.allocator();
var repo: Repository = undefined;
repo.open(gpa, io, root_dir, .{ .mode = .full }) catch return null;
defer repo.deinit(gpa);
const rid = repo.currentCheckoutRid() orelse return null;
var files = (repo.files(gpa, rid) catch return null) orelse return null;
defer files.deinit(gpa);
var entries: std.ArrayList(artifact.FCard) = .empty;
defer entries.deinit(arena);
var it = files.iterator();
while (it.next()) |entry| entries.append(arena, entry) catch return null;
var digest: [32]u8 = undefined;
_ = zit.submanifest.costShapeDigest(entries.items, &digest);
return digest;
}
fn submanifestEnable(
gpa: std.mem.Allocator,
io: std.Io,
root_dir: std.Io.Dir,
k_arg: ?u8,
streams: cli.Streams,
) cli.Exit {
var oc = submanifestConfig(gpa, io, root_dir, streams) orelse return .failure;
defer oc.deinit(gpa);
const s: zit.submanifest.Settings = .of(oc.config);
// §6.3: "The partition parameter k is selected once, when the
// enable-submanifests setting is first turned on for a repository, and
// pinned". A repository that already has one keeps it — re-pinning is a
// re-tune (§6.4), which is a different verb with a different consequence.
// Only a value in range is a pin, though: a stored value outside 1..12 came
// from a hand edit or another writer, and §8.1 says it is neither kept nor
// treated as absent — without --k the request is refused naming it, and an
// explicit in-range --k replaces it.
const valid_pin = s.pinned() and zit.submanifest.inRange(s.k);
if (valid_pin and k_arg != null and k_arg.? != s.k) {
streams.err.print(
"zit submanifest: k is already pinned to {d}; changing it is a re-tune — " ++
"use 'zit submanifest retune --k {d}'\n",
.{ s.k, k_arg.? },
) catch {};
return .failure;
}
if (s.pinned() and !valid_pin and k_arg == null) {
streams.err.print(
"zit submanifest: the stored submanifest-k {d} is outside {d}..{d}; " ++
"pass --k N to replace it\n",
.{ s.k, artifact.min_k, artifact.max_k },
) catch {};
return .failure;
}
// §6.3: "The partition parameter k is selected once, when the
// enable-submanifests setting ... is first turned on" — and the draft names
// the objective it is selected BY, so selecting it is the writer's job. An
// explicit --k overrides; an already-pinned repository keeps its value
// (re-pinning is a re-tune); otherwise the analysis pass answers, and
// §8.1's "MUST NOT enable emission ... with no pinned parameter" is
// satisfied by pinning rather than by refusing.
var analyzed_over: ?usize = null;
const k: u8 = if (k_arg) |v| v else if (valid_pin) s.k else blk: {
const sel = submanifestSelectK(gpa, io, root_dir, streams) orelse return .failure;
analyzed_over = sel.names;
// History outranks the snapshot when both can speak. The
// snapshot objective is theory over ONE file set; the replay is the
// same choice measured against this repository's own recent commits
// (argmin of realized steady-state materialization). No verdict, no
// gate — the one decision that stays with the operator is the
// compatibility spend, stated below as it always was.
break :blk submanifestReplayK(gpa, io, root_dir, sel.k, streams) orelse sel.k;
};
// §6.3: "MUST support every value from 1 to 12 inclusive (the pinned value
// MUST lie in that range)". Refuse to PIN an out-of-range value; the
// fallback-and-report rule exists for a value that reaches a writer some
// other way, not as a licence to store one here.
if (!zit.submanifest.inRange(k)) {
streams.err.print(
"zit submanifest: k must be {d}..{d} (got {d})\n",
.{ artifact.min_k, artifact.max_k, k },
) catch {};
return .failure;
}
const settled_shape = submanifestSettledShape(gpa, io, root_dir);
if (!submanifestWrite(
gpa,
io,
root_dir,
true,
k,
replaceSettledCostShape(settled_shape),
streams,
)) return .failure;
// §8.1/§7.2 — the consequence, stated before the operator's next commit,
// not buried in documentation.
streams.out.print("enable-submanifests: on (submanifest-k pinned to {d})\n", .{k}) catch {};
// What this does NOT do, said here rather than discovered
// later — existing history is untouched, and every fossil peer stops
// receiving new check-ins.
streams.out.writeAll(
"existing check-ins stay flat; from the next commit, peers that do not announce\n" ++
"sub-manifest support (every fossil) receive nothing new from this repository.\n" ++
"To re-mint the whole history as trees in a new repository:\n" ++
"'zit submanifest convert SRC DEST'.\n",
) catch {};
if (analyzed_over) |names| {
// §6.3: "The selection is advisory rather than canonical -- any pinned
// k yields conforming artifacts". Say what it was measured over, so the
// operator can tell a selection from a default.
streams.out.print(
"submanifest-k was selected by the §6.3 analysis over this check-in's {d} names;\n" ++
"'zit submanifest analyze' shows the full table, 'retune --k N' moves the pin.\n",
.{names},
) catch {};
}
streams.out.print("\nWARNING: {s}\n", .{zit.sync.submanifest_enable_warning}) catch {};
streams.out.writeAll(submanifest_scope_gap) catch {};
return .ok;
}
fn submanifestDisable(
gpa: std.mem.Allocator,
io: std.Io,
root_dir: std.Io.Dir,
streams: cli.Streams,
) cli.Exit {
// §8.1: "Disabling the setting stops the emission of new tree manifests; it
// cannot retire existing ones (artifact names are immutable)." The pin is
// deliberately left in place — it is the repository's identity for content
// sharing, and clearing it would silently make a later re-enable a re-tune.
if (!submanifestWrite(gpa, io, root_dir, false, null, null, streams)) return .failure;
streams.out.writeAll("enable-submanifests: off\n") catch {};
var oc = submanifestConfig(gpa, io, root_dir, streams) orelse return .ok;
defer oc.deinit(gpa);
if (oc.config.seen_submanifest) {
streams.out.writeAll(
"note: this repository already holds S-bearing artifacts. Disabling stops new\n" ++
"tree manifests; it cannot retire the existing ones, and peers that do not\n" ++
"announce sub-manifest support are still refused every one of them.\n",
) catch {};
}
return .ok;
}
fn submanifestRetune(
gpa: std.mem.Allocator,
io: std.Io,
root_dir: std.Io.Dir,
k_arg: ?u8,
streams: cli.Streams,
) cli.Exit {
// §6.4: "A re-tune MUST be manual and operator-initiated". The value is
// never inferred here — no argument is a usage failure, not a call into the
// analysis pass.
const k = k_arg orelse {
streams.err.writeAll(
"zit submanifest: retune needs an explicit value: 'zit submanifest retune --k N'.\n" ++
"A re-tune is always manual; run 'zit submanifest analyze' first if you want the " ++
"analyzed optimum.\n",
) catch {};
return .failure;
};
if (!zit.submanifest.inRange(k)) {
streams.err.print(
"zit submanifest: k must be {d}..{d} (got {d})\n",
.{ artifact.min_k, artifact.max_k, k },
) catch {};
return .failure;
}
var oc = submanifestConfig(gpa, io, root_dir, streams) orelse return .failure;
defer oc.deinit(gpa);
const s: zit.submanifest.Settings = .of(oc.config);
if (s.k == k) {
streams.out.print("submanifest-k: already {d} — nothing to do\n", .{k}) catch {};
return .ok;
}
const settled_shape = submanifestSettledShape(gpa, io, root_dir);
if (!submanifestWrite(
gpa,
io,
root_dir,
null,
k,
replaceSettledCostShape(settled_shape),
streams,
)) return .failure;
streams.out.print("submanifest-k: {d} -> {d}\n", .{ s.k, k }) catch {};
// §6.4: "If both it and its parent are trees, they share exactly the
// sub-manifest artifacts whose bytes are identical under the two full
// constructions; this can be every, some, or none of the parent's
// sub-manifests". The unshared ones land in the next commit, so the cost
// is said now rather than met at an arbitrary moment.
if (s.enabled) {
streams.out.writeAll(
"note: the next commit shares only the sub-manifests whose bytes are unchanged under\n" ++
"the new k: all, some or none. No history is rewritten and no reader behaves differently.\n",
) catch {};
}
return .ok;
}
/// §6.3's objective at every k in `min_k..max_k`, in order, into `out`; returns
/// how many rows were filled. The shared core of `analyze` (which prints the
/// whole table) and `enable` (which pins only the winner), so the value the
/// operator is shown is by construction the value that gets pinned.
fn submanifestCosts(
gpa: std.mem.Allocator,
entries: []const artifact.FCard,
out: *[artifact.max_k - artifact.min_k + 1]zit.submanifest.Cost,
) std.mem.Allocator.Error!usize {
var n: usize = 0;
var k: u4 = artifact.min_k;
while (true) : (k += 1) {
out[n] = try zit.submanifest.cost(gpa, entries, k, .sha3_256);
n += 1;
// Explicit terminator: `k` is a u4, so raising `max_k` to 15 would make
// `k += 1` wrap to 0 and spin forever on a `k <= max_k` condition.
if (k == artifact.max_k) break;
}
return n;
}
/// §6.3's selection: the k minimizing the objective over the repository's
/// current name set. This is the writer's choice, not the operator's — the
/// draft has the parameter "selected once, when the enable-submanifests setting
/// is first turned on", and names the objective it is selected by. Returns null
/// after reporting why no value could be selected; the caller then refuses to
/// enable rather than substituting one.
fn submanifestSelectK(
gpa: std.mem.Allocator,
io: std.Io,
root_dir: std.Io.Dir,
streams: cli.Streams,
) ?struct { k: u8, names: usize } {
var arena_state = std.heap.ArenaAllocator.init(gpa);
defer arena_state.deinit();
const entries = submanifestNamesFromCheckout(gpa, arena_state.allocator(), io, root_dir, false, streams) orelse {
streams.err.writeAll(
"zit submanifest: no file set to select a partition parameter from — " ++
"pin one explicitly with 'zit submanifest enable --k N'.\n",
) catch {};
return null;
};
if (entries.len == 0) {
streams.err.writeAll(
"zit submanifest: the current check-in holds no files, so there is nothing to\n" ++
"select a partition parameter from — pin one with 'zit submanifest enable --k N'.\n",
) catch {};
return null;
}
var costs: [artifact.max_k - artifact.min_k + 1]zit.submanifest.Cost = undefined;
const n = submanifestCosts(gpa, entries, &costs) catch {
_ = submanifestOom(streams);
return null;
};
const winner = zit.submanifest.best(costs[0..n]) orelse {
// Every k leaves this name set flat (§6.2 step 2), so the objective has
// no candidate to minimize and there is no analyzed value to pin. Not a
// reason to invent one: the set will not stay this small, and §6.3
// leaves the choice to the operator when the pass cannot make it.
streams.err.print(
"zit submanifest: no k partitions this repository's {d} names into a tree " ++
"(§6.2 step 2),\nso no parameter can be selected — pin one with " ++
"'zit submanifest enable --k N' if you want one anyway.\n",
.{entries.len},
) catch {};
return null;
};
return .{ .k = winner.k, .names = entries.len };
}
/// The §6.3 analysis pass over a name set: k = 1..12, the objective for each,
/// and the §6.5 prediction beside the measured optimum.
///
/// Writes nothing. §6.4: "an implementation MAY advise of drift from the
/// analyzed optimum but MUST NOT re-tune automatically" — so this reports and
/// stops, and moving the pin is the operator's separate `retune` act.
fn submanifestAnalyze(
gpa: std.mem.Allocator,
io: std.Io,
root_dir: std.Io.Dir,
names_path: ?[]const u8,
replay_all: bool,
streams: cli.Streams,
) cli.Exit {
var arena_state = std.heap.ArenaAllocator.init(gpa);
defer arena_state.deinit();
const aa = arena_state.allocator();
const entries = (if (names_path) |p|
submanifestNamesFromFile(aa, io, p, streams)
else
submanifestNamesFromCheckout(gpa, aa, io, root_dir, true, streams)) orelse {
if (names_path == null) {
streams.err.writeAll("zit submanifest: analyze a name list instead with '--names PATH'\n") catch {};
}
return .failure;
};
if (entries.len == 0) {
streams.err.writeAll("zit submanifest: the name set is empty — nothing to analyze\n") catch {};
return .failure;
}
streams.out.print("names: {d}\n", .{entries.len}) catch {};
streams.out.writeAll("\n k leaves depth S-bytes wmean-leaf total flat-F-bytes\n") catch {};
var costs: [artifact.max_k - artifact.min_k + 1]zit.submanifest.Cost = undefined;
const n = submanifestCosts(gpa, entries, &costs) catch return submanifestOom(streams);
for (costs[0..n]) |c| {
if (c.flat) {
streams.out.print(
"{d:>3} {s:>44} {d:>12}\n",
.{ c.k, "(flat: fewer than two groups, §6.2 step 2)", c.flat_bytes },
) catch {};
} else {
streams.out.print(
"{d:>3} {d:>6} {d:>5} {d:>8} {d:>10.1} {d:>8.1} {d:>12}\n",
.{ c.k, c.leaves, c.heights, c.s_bytes, c.weighted_mean_leaf_bytes, c.total, c.flat_bytes },
) catch {};
}
}
// Stated before any early return: a name list carries no history,
// and history is the replay's whole subject.
if (names_path != null) {
streams.out.writeAll(
"\nreplay: unavailable with --names — a name list carries no commit history,\n" ++
"and history is what decides whether enabling pays (see 'zit submanifest --help').\n",
) catch {};
}
const winner = zit.submanifest.best(costs[0..n]) orelse {
streams.out.writeAll(
"\nno k partitions this name set into a tree (§6.2 step 2) — commits stay flat at every k.\n",
) catch {};
return .ok;
};
streams.out.print(
"\nanalyzed optimum: k={d} (objective {d:.1})\n",
.{ winner.k, winner.total },
) catch {};
// §6.5, informative: "the analyzed optimum tracks roughly half the base-2
// logarithm of the file count". Printed beside the measurement so drift
// between the two is visible rather than assumed away.
streams.out.print(
"§6.5 prediction: ~{d:.1} (half the base-2 log of {d} names)\n",
.{ zit.submanifest.predictedK(entries.len), entries.len },
) catch {};
// The replay — the static table above is theory over ONE snapshot;
// whether enabling would have PAID on this repository is a property of
// its history (churn/reuse), so it is measured by replaying that history
// through the real builder and the real delta encoder.
if (names_path == null) {
submanifestReplaySection(gpa, io, root_dir, winner.k, if (replay_all) std.math.maxInt(usize) else replay_window, streams);
}
streams.out.writeAll(
"\nAdvisory only — any pinned k yields conforming artifacts (§6.3). Nothing was\n" ++
"changed; move the pin with 'zit submanifest retune --k N' (§6.4, manual only).\n",
) catch {};
return .ok;
}
/// The replay window: enough steady-state commits for churn structure to
/// show, small enough that analyze stays an offline-audit-scale wait.
const replay_window: usize = 200;
/// Render the replay for the static winner and its in-range neighbours. Any
/// failure is reported and skipped — the replay is evidence for a decision,
/// never a gate on printing the static analysis above it.
fn submanifestReplaySection(
gpa: std.mem.Allocator,
io: std.Io,
root_dir: std.Io.Dir,
winner_k: u4,
window: usize,
streams: cli.Streams,
) void {
var ks_buf: [3]u4 = undefined;
var n_ks: usize = 0;
if (winner_k > artifact.min_k) {
ks_buf[n_ks] = winner_k - 1;
n_ks += 1;
}
ks_buf[n_ks] = winner_k;
n_ks += 1;
if (winner_k < artifact.max_k) {
ks_buf[n_ks] = winner_k + 1;
n_ks += 1;
}
var repo: Repository = undefined;
Repository.open(&repo, gpa, io, root_dir, .{ .mode = .full }) catch {
streams.out.writeAll("\nreplay: cannot open the repository — skipped.\n") catch {};
return;
};
defer repo.deinit(gpa);
var rep = zit.submanifest.replay(gpa, &repo, window, ks_buf[0..n_ks]) catch {
streams.out.writeAll("\nreplay: failed reading history — skipped.\n") catch {};
return;
};
defer rep.deinit(gpa);
renderReplay(&rep, streams);
}
/// The replay table: flat actuals first, then each arm's steady-state deltas
/// on BOTH axes with bootstrap and breakeven separate — the verdict gates on
/// full-form/materialization (where the F-card wall actually breaks people),
/// with store inflation reported as the price.
fn renderReplay(rep: *const zit.submanifest.Replay, streams: cli.Streams) void {
if (rep.commits < 2) {
streams.out.print(
"\nreplay: only {d} replayable commit(s) — too little history to measure; not evidence either way.\n",
.{rep.commits},
) catch {};
return;
}
streams.out.print(
"\nreplayed over the last {d} commits (this repository's own history):\n" ++
"flat (actual): store {d} bytes, full-form {d} bytes\n",
.{ rep.commits, rep.flat_store, rep.flat_full },
) catch {};
const steady_commits: u64 = @intCast(rep.commits - 1);
const flat_first_store = rep.flat_store - rep.flat_store_steady;
for (rep.arms) |arm| {
if (arm.all_flat) {
streams.out.print("k={d:<2} every replayed commit built flat (§6.2 step 2) — no evidence at this k\n", .{arm.k}) catch {};
continue;
}
const full_pct = signedPct(arm.steady_full, rep.flat_full_steady);
const store_pct = signedPct(arm.steady_store, rep.flat_store_steady);
streams.out.print(
"k={d:<2} steady state: full-form {d:>6.1}%, store {d:>6.1}%; bootstrap {d} bytes",
.{ arm.k, full_pct, store_pct, arm.bootstrap_store },
) catch {};
// Breakeven on the STORE axis: commits until the bootstrap's extra
// stored bytes are repaid by the steady-state per-commit saving.
if (arm.bootstrap_store > flat_first_store and rep.flat_store_steady > arm.steady_store) {
const extra = arm.bootstrap_store - flat_first_store;
const saving_per_commit = (rep.flat_store_steady - arm.steady_store) / steady_commits;
if (saving_per_commit > 0) {
streams.out.print(", breakeven ~{d} commits", .{extra / saving_per_commit + 1}) catch {};
}
} else if (arm.steady_store >= rep.flat_store_steady) {
streams.out.writeAll(", breakeven: never on store bytes") catch {};
}
streams.out.writeAll("\n") catch {};
}
if (rep.bestArm()) |w| {
if (w.steady_full < rep.flat_full_steady) {
const full_pct = signedPct(w.steady_full, rep.flat_full_steady);
streams.out.print(
"verdict: k={d} — steady-state full-form {d:.1}% vs flat over this window.\n",
.{ w.k, full_pct },
) catch {};
if (rep.insideDesignEnvelope()) {
streams.out.print(
"note: flat materialization averages {d} KB/commit — inside the format's design\n" ++
"envelope, so the absolute saving is small; the real decision is the permanent\n" ++
"compatibility spend, and that one is yours.\n",
.{rep.flatFullSteadyPerCommit() / 1024},
) catch {};
}
} else {
streams.out.writeAll(
"verdict: no replayed k beat the flat arm's steady-state full-form cost over\n" ++
"this window — this churn pattern favors flat manifests.\n",
) catch {};
}
}
}
/// The k-selector for `enable`: replay the snapshot winner and its
/// in-range neighbours over recent history and return the argmin of realized
/// steady-state materialization — the k this repository's own churn actually
/// rewards — or null when the replay cannot speak (no history, every arm
/// flat, unopenable repository), leaving the snapshot winner standing. Prints
/// which evidence chose the pin. Never refuses anything: choosing k is this
/// function's whole authority.
fn submanifestReplayK(
gpa: std.mem.Allocator,
io: std.Io,
root_dir: std.Io.Dir,
snapshot_k: u8,
streams: cli.Streams,
) ?u8 {
if (!zit.submanifest.inRange(snapshot_k)) return null;
const winner_k: u4 = @intCast(snapshot_k);
var ks_buf: [3]u4 = undefined;
var n_ks: usize = 0;
if (winner_k > artifact.min_k) {
ks_buf[n_ks] = winner_k - 1;
n_ks += 1;
}
ks_buf[n_ks] = winner_k;
n_ks += 1;
if (winner_k < artifact.max_k) {
ks_buf[n_ks] = winner_k + 1;
n_ks += 1;
}
var repo: Repository = undefined;
Repository.open(&repo, gpa, io, root_dir, .{ .mode = .full }) catch return null;
defer repo.deinit(gpa);
var rep = zit.submanifest.replay(gpa, &repo, replay_window, ks_buf[0..n_ks]) catch return null;
defer rep.deinit(gpa);
if (rep.commits < 2) return null;
const w = rep.bestArm() orelse return null;
streams.out.print(
"k={d} by replaying {d} commits (steady-state materialization {d:.1}% vs flat; " ++
"snapshot optimum k={d}).\n",
.{ w.k, rep.commits, signedPct(w.steady_full, rep.flat_full_steady), snapshot_k },
) catch {};
return w.k;
}
/// Percentage delta of `got` against `base`, signed: -40.0 means 40% below.
fn signedPct(got: u64, base: u64) f64 {
std.debug.assert(base > 0);
const g: f64 = @floatFromInt(got);
const b: f64 = @floatFromInt(base);
return (g - b) * 100.0 / b;
}
/// The current checkout's effective file set as F cards, on `aa`.
fn submanifestNamesFromCheckout(
gpa: std.mem.Allocator,
aa: std.mem.Allocator,
io: std.Io,
root_dir: std.Io.Dir,
fallback_tip: bool,
streams: cli.Streams,
) ?[]const artifact.FCard {
var repo: Repository = undefined;
repo.open(gpa, io, root_dir, .{ .mode = .full }) catch {
streams.err.writeAll("zit submanifest: cannot read the repository\n") catch {};
return null;
};
defer repo.deinit(gpa);
// The fact only — each caller states its own remedy, since `analyze` can be
// pointed at a name file and `enable` cannot.
const rid = repo.currentCheckoutRid() orelse blk: {
// analyze over a bare store (-R, no checkout anywhere): the main
// branch's tip file set is the natural measurement subject.
if (fallback_tip) {
if (repo.resolve("tip", .checkin)) |tip| {
streams.out.writeAll("no checkout open — analyzing the tip check-in's file set\n") catch {};
break :blk tip;
} else |_| {}
}
streams.err.writeAll(
"zit submanifest: no check-in is open, so there is no file set to work from\n",
) catch {};
return null;
};
var fl = (repo.files(gpa, rid) catch {
streams.err.writeAll("zit submanifest: cannot read the current check-in\n") catch {};
return null;
}) orelse {
streams.err.writeAll("zit submanifest: cannot read the current check-in\n") catch {};
return null;
};
defer fl.deinit(gpa);
var list: std.ArrayList(artifact.FCard) = .empty;
var it = fl.iterator();
while (it.next()) |f| {
list.append(aa, .{
.filename = aa.dupe(u8, f.filename) catch return null,
.hash = if (f.hash) |h| aa.dupe(u8, h) catch return null else null,
.perm = if (f.perm) |p| aa.dupe(u8, p) catch return null else null,
.old_name = null, // §6.2 partitions on the filename only
.mode = f.mode,
}) catch return null;
}
return list.items;
}
/// A newline-separated name list from `path`, as F cards on `aa`.
///
/// §6.1: "The predicate reads the filename only: content hash, permission, and
/// old-name never influence the partition." So a name list is a complete input
/// to the partition; only the BYTE counts need a hash, and those depend on its
/// length, not its value — every entry gets a distinct 64-hex placeholder, the
/// width the SHA3-256 policy this pass measures under emits. Blank lines are
/// skipped; the list must already be in canonical order (§4.5.3), which is what
/// a manifest's F run and `fossil ls` both produce.
fn submanifestNamesFromFile(
aa: std.mem.Allocator,
io: std.Io,
path: []const u8,
streams: cli.Streams,
) ?[]const artifact.FCard {
const bytes = std.Io.Dir.cwd().readFileAlloc(io, path, aa, .limited(max_tracked_file_bytes)) catch {
streams.err.print("zit submanifest: cannot read '{s}'\n", .{path}) catch {};
return null;
};
var list: std.ArrayList(artifact.FCard) = .empty;
var it = std.mem.splitScalar(u8, bytes, '\n');
var seq: u64 = 0;
while (it.next()) |raw| {
const name = std.mem.trimEnd(u8, raw, "\r");
if (name.len == 0) continue;
seq += 1;
var digest: [32]u8 = undefined;
std.mem.writeInt(u64, digest[0..8], seq, .little);
@memset(digest[8..], 0);
const hex = aa.alloc(u8, 64) catch return null;
_ = std.fmt.bufPrint(hex, "{x}", .{&digest}) catch return null;
list.append(aa, .{
.filename = name,
.hash = hex,
.perm = null,
.old_name = null,
.mode = .regular,
}) catch return null;
}
const items = list.items;
// §6.2's precondition: strictly ascending canonical order. Reported rather
// than sorted — a caller whose list is out of order is measuring a different
// name set than it thinks it is.
for (items, 0..) |e, i| {
if (i != 0 and !std.mem.lessThan(u8, items[i - 1].filename, e.filename)) {
streams.err.print(
"zit submanifest: '{s}' is not in canonical order after '{s}' " ++
"(the name list must be sorted, with no duplicates)\n",
.{ e.filename, items[i - 1].filename },
) catch {};
return null;
}
}
return items;
}
fn submanifestOom(s: cli.Streams) cli.Exit {
s.err.writeAll("zit submanifest: out of memory\n") catch {};
return .failure;
}