tiny.zen.ThemeRenderStorage

1pub const Storage = struct {2    phase: alloc_phase.capacity.Phase,3    capacity: capacity_mod.Capacity,4    bytes: []u8,5    in_use: bool = false,6    output_bytes: usize = 0,7    high_water_output_bytes: usize = 0,8    rejected_page_count: u64 = 0,910    pub const Limits: type = capacity_mod.Limits;11    pub const Capacity: type = capacity_mod.Capacity;12    pub const Exhaustion: type = model.Exhaustion;13    pub const InitError: type = std.mem.Allocator.Error;14    pub const AcquireError: type = model.Error;1516    pub const claim: alloc_phase.capacity.Declaration = .{17        .source = .{18            .id = "zen.theme_render_storage",19            .kind = .phase_static,20            .limit_source = .caller,21            .storage = .{22                .covered = &.{23                    .{24                        .id = "rendered_theme_page_bytes",25                        .lifetime = .steady,26                        .detail = "rendered theme page bytes",27                    },28                },29                .excluded = &.{30                    "caller-owned theme layout, page values, metadata, and includes",31                    "Markdown rendering, site catalog, loaded theme files, and filesystem owners",32                },33            },34            .capacity = .{35                .inputs = &.{36                    alloc_phase.capacity.bindInput(Limits, "max_output_bytes", "max_output_bytes"),37                },38                .type_selectors = &.{},39                .nodes = &.{40                    .{ .input = 0 },41                },42                .assertions = &.{.{43                    .scope = .closure_total,44                    .measure = .retained,45                    .relation = .exact,46                    .expression = 0,47                }},48            },49            .overload = .{50                .kind = .reject_before_mutation,51                .detail = "invalid templates, max plus one output, and in-use rendering reject before output bytes or the active result change; only rejection telemetry advances",52            },53            .risks = .{54                .transitive = .{55                    .status = .witnessed,56                    .detail = "template scanning, placeholder resolution, escaped-length planning, and exact filling use borrowed inputs and the acquired byte slice only",57                },58                .foreign = .{59                    .status = .excluded,60                    .detail = "theme page rendering crosses no operating-system or foreign callback boundary",61                },62            },63            .obligations = &.{64                .{ .key = "zen_theme_render_capacity", .role = .capacity_model },65                .{ .key = "zen_theme_render_acquisition", .role = .custom },66                .{ .key = "zen_theme_render_oom", .role = .custom },67                .{ .key = "zen_theme_render_boundaries", .role = .overload },68                .{ .key = "zen_theme_render_reuse", .role = .overload },69                .{ .key = "zen_theme_render_sealed", .role = .transitive_risk },70                .{ .key = "zen_theme_render_root", .role = .custom },71                .{ .key = "zen_theme_render_consumer", .role = .foreign_risk },72            },73        },74        .bindings = .{75            .owner = @This(),76            .seal = .{77                .family = alloc_phase.capacity.selector(@This().activate),78                .premise = .{79                    .class = .checked_semantic_fact,80                    .authority = .checker,81                },82            },83            .teardown = .{84                .family = alloc_phase.capacity.selector(@This().deinit),85                .premise = .{86                    .class = .checked_semantic_fact,87                    .authority = .checker,88                },89            },90        },91    };9293    pub fn init(allocator: std.mem.Allocator, limits: Limits) InitError!Storage {94        const capacity = Capacity.derive(limits);95        const bytes = if (capacity.storage_bytes == 0)96            @as([]u8, &.{})97        else98            try allocator.alloc(u8, capacity.storage_bytes);99        return .{100            .phase = .initialization,101            .capacity = capacity,102            .bytes = bytes,103        };104    }105106    pub fn activate(self: *Storage) void {107        std.debug.assert(self.phase == .initialization);108        self.assertStorage();109        self.phase = .steady;110    }111112    pub fn acquire(self: *Storage, active: model.Theme, page: model.Page) AcquireError!Regions {113        std.debug.assert(self.phase == .steady);114        if (self.in_use) return self.reject(error.ThemeStorageInUse);115        const plan = plan_mod.Plan.inspect(active, page, self.capacity.limits) catch |err| {116            self.rejected_page_count +|= 1;117            return err;118        };119        self.in_use = true;120        self.output_bytes = plan.output_bytes;121        self.high_water_output_bytes = @max(self.high_water_output_bytes, plan.output_bytes);122        self.assertStorage();123        return .{124            .plan = plan,125            .output = self.bytes[self.capacity.output_offset..][0..plan.output_bytes],126        };127    }128129    pub fn reset(self: *Storage) void {130        std.debug.assert(self.phase == .steady);131        std.debug.assert(self.in_use);132        self.in_use = false;133        self.output_bytes = 0;134        self.assertStorage();135    }136137    pub fn status(self: *const Storage) Status {138        return .{139            .phase = self.phase,140            .in_use = self.in_use,141            .storage_bytes = self.capacity.storage_bytes,142            .max_output_bytes = self.capacity.limits.max_output_bytes,143            .output_bytes = self.output_bytes,144            .high_water_output_bytes = self.high_water_output_bytes,145            .rejected_page_count = self.rejected_page_count,146        };147    }148149    pub fn deinit(self: *Storage, allocator: std.mem.Allocator) void {150        std.debug.assert(self.phase != .teardown);151        std.debug.assert(!self.in_use);152        self.assertStorage();153        self.phase = .teardown;154        allocator.free(self.bytes);155        self.bytes = &.{};156    }157158    fn reject(self: *Storage, err: model.Exhaustion) model.Exhaustion {159        self.rejected_page_count +|= 1;160        return err;161    }162163    fn assertStorage(self: *const Storage) void {164        std.debug.assert(self.bytes.len == self.capacity.storage_bytes);165        std.debug.assert(self.output_bytes <= self.bytes.len);166        std.debug.assert(self.high_water_output_bytes <= self.bytes.len);167        if (!self.in_use) std.debug.assert(self.output_bytes == 0);168    }169};

1/// Reusable caller-allocated storage for one rendered themed page.2pub const ThemeRenderStorage = theme.RenderStorage;