tiny.zen.FrontmatterStorage

1pub const Storage = struct {2    phase: alloc_phase.capacity.Phase,3    capacity: capacity_mod.Capacity,4    bytes: []align(capacity_mod.storage_alignment) u8,5    pairs: []model.Pair,6    continuation: []u8,7    in_use: bool = false,89    pub const Limits: type = capacity_mod.Limits;10    pub const Capacity: type = capacity_mod.Capacity;11    pub const Exhaustion: type = model.Exhaustion;12    pub const InitError = std.mem.Allocator.Error || capacity_mod.DeriveError;13    pub const AcquireError: type = model.Error;1415    pub const claim: alloc_phase.capacity.Declaration = .{16        .source = .{17            .id = "zen.frontmatter_storage",18            .kind = .phase_static,19            .limit_source = .caller,20            .storage = .{21                .covered = &.{22                    .{23                        .id = "frontmatter_pair_descriptors",24                        .lifetime = .steady,25                        .detail = "frontmatter pair descriptors",26                    },27                    .{28                        .id = "joined_continuation_values",29                        .lifetime = .steady,30                        .detail = "joined continuation values",31                    },32                },33                .excluded = &.{34                    "caller-owned Markdown source and borrowed ordinary metadata values",35                    "site catalog, rendered page, theme, and filesystem output owners",36                },37            },38            .capacity = .{39                .inputs = &.{40                    alloc_phase.capacity.bindInput(Limits, "max_pairs", "max_pairs"),41                    alloc_phase.capacity.bindInput(Limits, "max_continuation_bytes", "max_continuation_bytes"),42                },43                .type_selectors = &.{44                    alloc_phase.capacity.bindType(model.Pair, "pair"),45                },46                .nodes = &.{47                    .{ .input = 0 },48                    .{ .scale = .{ .node = 0, .coefficient = .{ .size_of_concrete_type = 0 } } },49                    .{ .alignment = .{ .node = 1, .alignment = .{ .literal = 16 } } },50                    .{ .input = 1 },51                    .{ .add = .{ .left = 2, .right = 3 } },52                },53                .assertions = &.{.{54                    .scope = .closure_total,55                    .measure = .retained,56                    .relation = .exact,57                    .expression = 4,58                }},59            },60            .overload = .{61                .kind = .reject_before_mutation,62                .detail = "unclosed input, pair overflow, continuation overflow, and concurrent acquisition fail before storage mutation",63            },64            .risks = .{65                .transitive = .{66                    .status = .witnessed,67                    .detail = "section discovery, field scanning, and continuation joining use only borrowed input and acquired slices",68                },69                .foreign = .{70                    .status = .excluded,71                    .detail = "frontmatter parsing crosses no operating-system or foreign callback boundary",72                },73            },74            .obligations = &.{75                .{ .key = "zen_frontmatter_capacity", .role = .capacity_model },76                .{ .key = "zen_frontmatter_acquisition", .role = .custom },77                .{ .key = "zen_frontmatter_oom", .role = .custom },78                .{ .key = "zen_frontmatter_boundaries", .role = .overload },79                .{ .key = "zen_frontmatter_reuse", .role = .overload },80                .{ .key = "zen_frontmatter_sealed", .role = .transitive_risk },81                .{ .key = "zen_frontmatter_root", .role = .custom },82                .{ .key = "zen_frontmatter_consumer", .role = .foreign_risk },83            },84        },85        .bindings = .{86            .owner = @This(),87            .seal = .{88                .family = alloc_phase.capacity.selector(@This().activate),89                .premise = .{90                    .class = .checked_semantic_fact,91                    .authority = .checker,92                },93            },94            .teardown = .{95                .family = alloc_phase.capacity.selector(@This().deinit),96                .premise = .{97                    .class = .checked_semantic_fact,98                    .authority = .checker,99                },100            },101        },102    };103104    pub fn init(allocator: std.mem.Allocator, limits: Limits) InitError!Storage {105        const capacity = try Capacity.derive(limits);106        const bytes = try allocator.alignedAlloc(107            u8,108            .fromByteUnits(capacity_mod.storage_alignment),109            capacity.storage_bytes,110        );111        return .{112            .phase = .initialization,113            .capacity = capacity,114            .bytes = bytes,115            .pairs = typedSlice(116                model.Pair,117                bytes,118                capacity.pairs_offset,119                limits.max_pairs,120            ),121            .continuation = bytes[capacity.continuation_offset..][0..limits.max_continuation_bytes],122        };123    }124125    pub fn activate(self: *Storage) void {126        std.debug.assert(self.phase == .initialization);127        std.debug.assert(self.bytes.len == self.capacity.storage_bytes);128        self.phase = .steady;129    }130131    pub fn acquire(self: *Storage, markdown: []const u8) AcquireError!Regions {132        std.debug.assert(self.phase == .steady);133        if (self.in_use) return error.FrontmatterStorageInUse;134        const plan = try plan_mod.Plan.inspect(markdown, self.capacity.limits);135        self.in_use = true;136        return .{137            .plan = plan,138            .pairs = self.pairs[0..plan.pairs],139            .continuation = self.continuation[0..plan.continuation_bytes],140        };141    }142143    pub fn reset(self: *Storage) void {144        std.debug.assert(self.phase == .steady);145        std.debug.assert(self.in_use);146        self.in_use = false;147    }148149    pub fn status(self: *const Storage) Status {150        return .{151            .phase = self.phase,152            .in_use = self.in_use,153            .storage_bytes = self.capacity.storage_bytes,154            .max_pairs = self.capacity.limits.max_pairs,155            .max_continuation_bytes = self.capacity.limits.max_continuation_bytes,156        };157    }158159    pub fn deinit(self: *Storage, allocator: std.mem.Allocator) void {160        std.debug.assert(self.phase != .teardown);161        std.debug.assert(!self.in_use);162        std.debug.assert(self.bytes.len == self.capacity.storage_bytes);163        self.phase = .teardown;164        allocator.free(self.bytes);165        self.bytes = &.{};166        self.pairs = &.{};167        self.continuation = &.{};168    }169};

1/// Reusable caller-allocated storage for one parsed frontmatter block.2pub const FrontmatterStorage = frontmatter.Storage;