tiny.zen.AsciiRenderStorage

1/// One reusable aligned region for ASCII render scratch and output.2///3/// Call `init`, then `activate`. Output borrows the region until `reset`.4/// Call `deinit` with the allocator passed to `init` after the last reset.5pub const Storage = struct {6    phase: alloc_phase.capacity.Phase,7    capacity: capacity_mod.Capacity,8    bytes: []align(capacity_mod.storage_alignment) u8,9    categories: [][]const u8,10    stack_totals: []diagram.bounds.StackTotal,11    canvas: []u8,12    output: []u8,13    in_use: bool = false,14    category_count: usize = 0,15    stack_total_count: usize = 0,16    canvas_bytes: usize = 0,17    output_bytes: usize = 0,18    high_water_categories: usize = 0,19    high_water_stack_totals: usize = 0,20    high_water_canvas_bytes: usize = 0,21    high_water_output_bytes: usize = 0,22    rejected_render_count: u64 = 0,2324    pub const Limits: type = capacity_mod.Limits;25    pub const Capacity: type = capacity_mod.Capacity;26    pub const Exhaustion: type = model.Exhaustion;27    pub const InitError = std.mem.Allocator.Error || capacity_mod.DeriveError;28    pub const AcquireError: type = model.Exhaustion;2930    pub const claim: alloc_phase.capacity.Declaration = .{31        .source = .{32            .id = "zen.ascii_render_storage",33            .kind = .phase_static,34            .limit_source = .caller,35            .storage = .{36                .covered = &.{37                    .{38                        .id = "borrowed_categorical_bound_slots",39                        .lifetime = .steady,40                        .detail = "borrowed categorical bound slots",41                    },42                    .{43                        .id = "stacked_category_bound_totals",44                        .lifetime = .steady,45                        .detail = "stacked-category bound totals",46                    },47                    .{48                        .id = "ascii_canvas_bytes",49                        .lifetime = .steady,50                        .detail = "ASCII canvas bytes",51                    },52                    .{53                        .id = "compacted_ascii_output_bytes",54                        .lifetime = .steady,55                        .detail = "compacted ASCII output bytes",56                    },57                },58                .excluded = &.{59                    "caller-owned parsed diagram Document and retained strings",60                    "JSON line scratch, Document parsing, Markdown output, and filesystem owners",61                },62            },63            .capacity = .{64                .inputs = &.{65                    alloc_phase.capacity.bindInput(Limits, "max_categories", "max_categories"),66                    alloc_phase.capacity.bindInput(Limits, "max_stack_totals", "max_stack_totals"),67                    alloc_phase.capacity.bindInput(Limits, "max_canvas_bytes", "max_canvas_bytes"),68                    alloc_phase.capacity.bindInput(Limits, "max_output_bytes", "max_output_bytes"),69                },70                .type_selectors = &.{71                    alloc_phase.capacity.bindType([]const u8, "const_u8"),72                    alloc_phase.capacity.bindType(diagram.bounds.StackTotal, "stacktotal"),73                },74                .nodes = &.{75                    .{ .input = 0 },76                    .{ .scale = .{ .node = 0, .coefficient = .{ .size_of_concrete_type = 0 } } },77                    .{ .alignment = .{ .node = 1, .alignment = .{ .literal = 16 } } },78                    .{ .input = 1 },79                    .{ .scale = .{ .node = 3, .coefficient = .{ .size_of_concrete_type = 1 } } },80                    .{ .input = 2 },81                    .{ .input = 3 },82                    .{ .add = .{ .left = 2, .right = 4 } },83                    .{ .add = .{ .left = 7, .right = 5 } },84                    .{ .add = .{ .left = 8, .right = 6 } },85                },86                .assertions = &.{.{87                    .scope = .closure_total,88                    .measure = .retained,89                    .relation = .exact,90                    .expression = 9,91                }},92            },93            .overload = .{94                .kind = .reject_before_mutation,95                .detail = "every max plus one plan and in-use acquisition reject before backing bytes or the active result change; only rejection telemetry advances",96            },97            .risks = .{98                .transitive = .{99                    .status = .witnessed,100                    .detail = "bounds derivation, categorical lookup, canvas drawing, and row compaction use borrowed Document values and acquired slices only",101                },102                .foreign = .{103                    .status = .excluded,104                    .detail = "parsed-document ASCII rendering crosses no operating-system or foreign callback boundary",105                },106            },107            .obligations = &.{108                .{ .key = "zen_ascii_render_capacity", .role = .capacity_model },109                .{ .key = "zen_ascii_render_acquisition", .role = .custom },110                .{ .key = "zen_ascii_render_oom", .role = .custom },111                .{ .key = "zen_ascii_render_boundaries", .role = .overload },112                .{ .key = "zen_ascii_render_reuse", .role = .overload },113                .{ .key = "zen_ascii_render_sealed", .role = .transitive_risk },114                .{ .key = "zen_ascii_render_root", .role = .custom },115                .{ .key = "zen_ascii_render_consumer", .role = .foreign_risk },116            },117        },118        .bindings = .{119            .owner = @This(),120            .seal = .{121                .family = alloc_phase.capacity.selector(@This().activate),122                .premise = .{123                    .class = .checked_semantic_fact,124                    .authority = .checker,125                },126            },127            .teardown = .{128                .family = alloc_phase.capacity.selector(@This().deinit),129                .premise = .{130                    .class = .checked_semantic_fact,131                    .authority = .checker,132                },133            },134        },135    };136137    pub fn init(allocator: std.mem.Allocator, limits: Limits) InitError!Storage {138        const capacity = try Capacity.derive(limits);139        const bytes = if (capacity.storage_bytes == 0)140            @as([]align(capacity_mod.storage_alignment) u8, &.{})141        else142            try allocator.alignedAlloc(143                u8,144                .fromByteUnits(capacity_mod.storage_alignment),145                capacity.storage_bytes,146            );147        return .{148            .phase = .initialization,149            .capacity = capacity,150            .bytes = bytes,151            .categories = typedSlice(152                []const u8,153                bytes,154                capacity.categories_offset,155                limits.max_categories,156            ),157            .stack_totals = typedSlice(158                diagram.bounds.StackTotal,159                bytes,160                capacity.stack_totals_offset,161                limits.max_stack_totals,162            ),163            .canvas = bytes[capacity.canvas_offset..][0..limits.max_canvas_bytes],164            .output = bytes[capacity.output_offset..][0..limits.max_output_bytes],165        };166    }167168    pub fn activate(self: *Storage) void {169        std.debug.assert(self.phase == .initialization);170        self.assertStorage();171        self.phase = .steady;172    }173174    /// Acquires exact plan regions or rejects before backing bytes change.175    pub fn acquire(self: *Storage, plan: plan_mod.Plan) AcquireError!Regions {176        std.debug.assert(self.phase == .steady);177        if (self.in_use) return self.reject(error.AsciiRenderStorageInUse);178        plan.require(self.capacity.limits) catch |err| return self.reject(err);179        self.in_use = true;180        self.category_count = plan.categories;181        self.stack_total_count = plan.stack_totals;182        self.canvas_bytes = plan.canvas_bytes;183        self.output_bytes = plan.output_bytes;184        self.high_water_categories = @max(self.high_water_categories, plan.categories);185        self.high_water_stack_totals = @max(self.high_water_stack_totals, plan.stack_totals);186        self.high_water_canvas_bytes = @max(self.high_water_canvas_bytes, plan.canvas_bytes);187        self.high_water_output_bytes = @max(self.high_water_output_bytes, plan.output_bytes);188        self.assertStorage();189        return .{190            .plan = plan,191            .categories = self.categories[0..plan.categories],192            .stack_totals = self.stack_totals[0..plan.stack_totals],193            .canvas = self.canvas[0..plan.canvas_bytes],194            .output = self.output[0..plan.output_bytes],195        };196    }197198    /// Ends the active output borrow so the same region can render again.199    pub fn reset(self: *Storage) void {200        std.debug.assert(self.phase == .steady);201        std.debug.assert(self.in_use);202        self.in_use = false;203        self.category_count = 0;204        self.stack_total_count = 0;205        self.canvas_bytes = 0;206        self.output_bytes = 0;207        self.assertStorage();208    }209210    /// Returns current, high-water, and rejected demand without mutation.211    pub fn status(self: *const Storage) Status {212        return .{213            .phase = self.phase,214            .in_use = self.in_use,215            .storage_bytes = self.capacity.storage_bytes,216            .max_categories = self.capacity.limits.max_categories,217            .max_stack_totals = self.capacity.limits.max_stack_totals,218            .max_canvas_bytes = self.capacity.limits.max_canvas_bytes,219            .max_output_bytes = self.capacity.limits.max_output_bytes,220            .categories = self.category_count,221            .stack_totals = self.stack_total_count,222            .canvas_bytes = self.canvas_bytes,223            .output_bytes = self.output_bytes,224            .high_water_categories = self.high_water_categories,225            .high_water_stack_totals = self.high_water_stack_totals,226            .high_water_canvas_bytes = self.high_water_canvas_bytes,227            .high_water_output_bytes = self.high_water_output_bytes,228            .rejected_render_count = self.rejected_render_count,229        };230    }231232    pub fn deinit(self: *Storage, allocator: std.mem.Allocator) void {233        std.debug.assert(self.phase != .teardown);234        std.debug.assert(!self.in_use);235        self.assertStorage();236        self.phase = .teardown;237        allocator.free(self.bytes);238        self.bytes = &.{};239        self.categories = &.{};240        self.stack_totals = &.{};241        self.canvas = &.{};242        self.output = &.{};243    }244245    fn reject(self: *Storage, err: model.Exhaustion) model.Exhaustion {246        self.rejected_render_count +|= 1;247        return err;248    }249250    fn assertStorage(self: *const Storage) void {251        std.debug.assert(self.bytes.len == self.capacity.storage_bytes);252        std.debug.assert(self.categories.len == self.capacity.limits.max_categories);253        std.debug.assert(self.stack_totals.len == self.capacity.limits.max_stack_totals);254        std.debug.assert(self.canvas.len == self.capacity.limits.max_canvas_bytes);255        std.debug.assert(self.output.len == self.capacity.limits.max_output_bytes);256        std.debug.assert(self.category_count <= self.categories.len);257        std.debug.assert(self.stack_total_count <= self.stack_totals.len);258        std.debug.assert(self.canvas_bytes <= self.canvas.len);259        std.debug.assert(self.output_bytes <= self.output.len);260        std.debug.assert(self.high_water_categories <= self.categories.len);261        std.debug.assert(self.high_water_stack_totals <= self.stack_totals.len);262        std.debug.assert(self.high_water_canvas_bytes <= self.canvas.len);263        std.debug.assert(self.high_water_output_bytes <= self.output.len);264        if (!self.in_use) {265            std.debug.assert(self.category_count == 0);266            std.debug.assert(self.stack_total_count == 0);267            std.debug.assert(self.canvas_bytes == 0);268            std.debug.assert(self.output_bytes == 0);269        }270    }271};

1/// Reusable caller-allocated storage for bounded ASCII rendering.2pub const AsciiRenderStorage = diagram.AsciiRenderStorage;