tiny.zen.FootnoteStorage

1pub const Storage = struct {2    phase: alloc_phase.capacity.Phase,3    capacity: capacity_mod.Capacity,4    bytes: []align(capacity_mod.storage_alignment) u8,5    definitions: []model.Definition,6    joined_text: []u8,7    in_use: bool = false,8    definition_count: usize = 0,9    joined_text_bytes: usize = 0,10    high_water_definitions: usize = 0,11    high_water_joined_text_bytes: usize = 0,12    rejected_source_count: u64 = 0,1314    pub const Limits: type = capacity_mod.Limits;15    pub const Capacity: type = capacity_mod.Capacity;16    pub const Exhaustion: type = model.Exhaustion;17    pub const InitError = std.mem.Allocator.Error || capacity_mod.DeriveError;18    pub const AcquireError: type = model.Error;1920    pub const claim: alloc_phase.capacity.Declaration = .{21        .source = .{22            .id = "zen.footnote_storage",23            .kind = .phase_static,24            .limit_source = .caller,25            .storage = .{26                .covered = &.{27                    .{28                        .id = "footnote_definition_descriptors",29                        .lifetime = .steady,30                        .detail = "footnote definition descriptors",31                    },32                    .{33                        .id = "joined_footnote_continuation_text",34                        .lifetime = .steady,35                        .detail = "joined footnote continuation text",36                    },37                },38                .excluded = &.{39                    "caller-owned Markdown source and borrowed keys or single-line text",40                    "rendered HTML and inline-rendering owners",41                    "heading, quiz, site, theme, and filesystem owners",42                },43            },44            .capacity = .{45                .inputs = &.{46                    alloc_phase.capacity.bindInput(Limits, "max_definitions", "max_definitions"),47                    alloc_phase.capacity.bindInput(Limits, "max_joined_text_bytes", "max_joined_text_bytes"),48                },49                .type_selectors = &.{50                    alloc_phase.capacity.bindType(model.Definition, "definition"),51                },52                .nodes = &.{53                    .{ .input = 0 },54                    .{ .scale = .{ .node = 0, .coefficient = .{ .size_of_concrete_type = 0 } } },55                    .{ .input = 1 },56                    .{ .add = .{ .left = 1, .right = 2 } },57                },58                .assertions = &.{.{59                    .scope = .closure_total,60                    .measure = .retained,61                    .relation = .exact,62                    .expression = 3,63                }},64            },65            .overload = .{66                .kind = .reject_before_mutation,67                .detail = "max plus one and in-use collection reject before the backing region or active result changes; only rejection telemetry advances",68            },69            .risks = .{70                .transitive = .{71                    .status = .witnessed,72                    .detail = "scanning, planning, descriptor filling, duplicate filtering, joining, lookup, and numbering use borrowed input and acquired slices only",73                },74                .foreign = .{75                    .status = .excluded,76                    .detail = "footnote collection crosses no operating-system or foreign callback boundary",77                },78            },79            .obligations = &.{80                .{ .key = "zen_footnote_capacity", .role = .capacity_model },81                .{ .key = "zen_footnote_acquisition", .role = .custom },82                .{ .key = "zen_footnote_oom", .role = .custom },83                .{ .key = "zen_footnote_boundaries", .role = .overload },84                .{ .key = "zen_footnote_reuse", .role = .overload },85                .{ .key = "zen_footnote_sealed", .role = .transitive_risk },86                .{ .key = "zen_footnote_root", .role = .custom },87                .{ .key = "zen_footnote_consumer", .role = .foreign_risk },88            },89        },90        .bindings = .{91            .owner = @This(),92            .seal = .{93                .family = alloc_phase.capacity.selector(@This().activate),94                .premise = .{95                    .class = .checked_semantic_fact,96                    .authority = .checker,97                },98            },99            .teardown = .{100                .family = alloc_phase.capacity.selector(@This().deinit),101                .premise = .{102                    .class = .checked_semantic_fact,103                    .authority = .checker,104                },105            },106        },107    };108109    pub fn init(allocator: std.mem.Allocator, limits: Limits) InitError!Storage {110        const capacity = try Capacity.derive(limits);111        const bytes = if (capacity.storage_bytes == 0)112            @as([]align(capacity_mod.storage_alignment) u8, &.{})113        else114            try allocator.alignedAlloc(115                u8,116                .fromByteUnits(capacity_mod.storage_alignment),117                capacity.storage_bytes,118            );119        return .{120            .phase = .initialization,121            .capacity = capacity,122            .bytes = bytes,123            .definitions = typedSlice(124                model.Definition,125                bytes,126                capacity.definitions_offset,127                limits.max_definitions,128            ),129            .joined_text = bytes[capacity.joined_text_offset..][0..limits.max_joined_text_bytes],130        };131    }132133    pub fn activate(self: *Storage) void {134        std.debug.assert(self.phase == .initialization);135        self.assertStorage();136        self.phase = .steady;137    }138139    pub fn acquire(self: *Storage, source: []const u8) AcquireError!Regions {140        std.debug.assert(self.phase == .steady);141        if (self.in_use) return self.reject(error.FootnoteStorageInUse);142        const plan = plan_mod.Plan.inspect(source, self.capacity.limits) catch |err| {143            self.rejected_source_count +|= 1;144            return err;145        };146        self.in_use = true;147        self.definition_count = plan.definitions;148        self.joined_text_bytes = plan.joined_text_bytes;149        self.high_water_definitions = @max(self.high_water_definitions, plan.definitions);150        self.high_water_joined_text_bytes = @max(151            self.high_water_joined_text_bytes,152            plan.joined_text_bytes,153        );154        self.assertStorage();155        return .{156            .plan = plan,157            .definitions = self.definitions[0..plan.definitions],158            .joined_text = self.joined_text[0..plan.joined_text_bytes],159        };160    }161162    pub fn reset(self: *Storage) void {163        std.debug.assert(self.phase == .steady);164        std.debug.assert(self.in_use);165        self.in_use = false;166        self.definition_count = 0;167        self.joined_text_bytes = 0;168        self.assertStorage();169    }170171    pub fn status(self: *const Storage) Status {172        return .{173            .phase = self.phase,174            .in_use = self.in_use,175            .storage_bytes = self.capacity.storage_bytes,176            .max_definitions = self.capacity.limits.max_definitions,177            .max_joined_text_bytes = self.capacity.limits.max_joined_text_bytes,178            .definition_count = self.definition_count,179            .joined_text_bytes = self.joined_text_bytes,180            .high_water_definitions = self.high_water_definitions,181            .high_water_joined_text_bytes = self.high_water_joined_text_bytes,182            .rejected_source_count = self.rejected_source_count,183        };184    }185186    pub fn deinit(self: *Storage, allocator: std.mem.Allocator) void {187        std.debug.assert(self.phase != .teardown);188        std.debug.assert(!self.in_use);189        self.assertStorage();190        self.phase = .teardown;191        allocator.free(self.bytes);192        self.bytes = &.{};193        self.definitions = &.{};194        self.joined_text = &.{};195    }196197    fn reject(self: *Storage, err: model.Exhaustion) model.Exhaustion {198        self.rejected_source_count +|= 1;199        return err;200    }201202    fn assertStorage(self: *const Storage) void {203        std.debug.assert(self.bytes.len == self.capacity.storage_bytes);204        std.debug.assert(self.definitions.len == self.capacity.limits.max_definitions);205        std.debug.assert(self.joined_text.len == self.capacity.limits.max_joined_text_bytes);206        std.debug.assert(self.definition_count <= self.definitions.len);207        std.debug.assert(self.joined_text_bytes <= self.joined_text.len);208        std.debug.assert(self.high_water_definitions <= self.definitions.len);209        std.debug.assert(self.high_water_joined_text_bytes <= self.joined_text.len);210        if (!self.in_use) {211            std.debug.assert(self.definition_count == 0);212            std.debug.assert(self.joined_text_bytes == 0);213        }214    }215};

1/// Reusable caller-allocated storage for one parsed footnote set.2pub const FootnoteStorage = footnote.Storage;