tiny.zen.QuizStorage

1pub const Storage = struct {2    phase: alloc_phase.capacity.Phase,3    capacity: capacity_mod.Capacity,4    bytes: []align(capacity_mod.storage_alignment) u8,5    questions: []model.Question,6    options: []model.Option,7    joined_text: []u8,8    in_use: bool = false,9    question_count: usize = 0,10    option_count: usize = 0,11    joined_text_bytes: usize = 0,12    high_water_questions: usize = 0,13    high_water_options: usize = 0,14    high_water_joined_text_bytes: usize = 0,15    rejected_source_count: u64 = 0,1617    pub const Limits: type = capacity_mod.Limits;18    pub const Capacity: type = capacity_mod.Capacity;19    pub const Exhaustion: type = model.Exhaustion;20    pub const InitError = std.mem.Allocator.Error || capacity_mod.DeriveError;21    pub const AcquireError: type = model.Error;2223    pub const claim: alloc_phase.capacity.Declaration = .{24        .source = .{25            .id = "zen.quiz_storage",26            .kind = .phase_static,27            .limit_source = .caller,28            .storage = .{29                .covered = &.{30                    .{31                        .id = "quiz_question_descriptors",32                        .lifetime = .steady,33                        .detail = "quiz question descriptors",34                    },35                    .{36                        .id = "quiz_option_descriptors",37                        .lifetime = .steady,38                        .detail = "quiz option descriptors",39                    },40                    .{41                        .id = "normalized_continued_quiz_text",42                        .lifetime = .steady,43                        .detail = "normalized continued quiz text",44                    },45                },46                .excluded = &.{47                    "caller-owned quiz source and borrowed single-line text",48                    "Markdown document, output, and inline-rendering owners",49                    "site catalog, theme, and filesystem output owners",50                },51            },52            .capacity = .{53                .inputs = &.{54                    alloc_phase.capacity.bindInput(Limits, "max_questions", "max_questions"),55                    alloc_phase.capacity.bindInput(Limits, "max_options", "max_options"),56                    alloc_phase.capacity.bindInput(Limits, "max_joined_text_bytes", "max_joined_text_bytes"),57                },58                .type_selectors = &.{59                    alloc_phase.capacity.bindType(model.Question, "question"),60                    alloc_phase.capacity.bindType(model.Option, "option"),61                },62                .nodes = &.{63                    .{ .input = 0 },64                    .{ .scale = .{ .node = 0, .coefficient = .{ .size_of_concrete_type = 0 } } },65                    .{ .alignment = .{ .node = 1, .alignment = .{ .literal = 16 } } },66                    .{ .input = 1 },67                    .{ .scale = .{ .node = 3, .coefficient = .{ .size_of_concrete_type = 1 } } },68                    .{ .alignment = .{ .node = 4, .alignment = .{ .literal = 16 } } },69                    .{ .input = 2 },70                    .{ .add = .{ .left = 2, .right = 5 } },71                    .{ .add = .{ .left = 7, .right = 6 } },72                },73                .assertions = &.{.{74                    .scope = .closure_total,75                    .measure = .retained,76                    .relation = .exact,77                    .expression = 8,78                }},79            },80            .overload = .{81                .kind = .reject_before_mutation,82                .detail = "invalid input and max plus one reject before the backing region or active result changes; only rejection telemetry advances",83            },84            .risks = .{85                .transitive = .{86                    .status = .witnessed,87                    .detail = "scanning, planning, descriptor filling, and continuation joining use borrowed input and acquired slices only",88                },89                .foreign = .{90                    .status = .excluded,91                    .detail = "quiz parsing crosses no operating-system or foreign callback boundary",92                },93            },94            .obligations = &.{95                .{ .key = "zen_quiz_capacity", .role = .capacity_model },96                .{ .key = "zen_quiz_acquisition", .role = .custom },97                .{ .key = "zen_quiz_oom", .role = .custom },98                .{ .key = "zen_quiz_boundaries", .role = .overload },99                .{ .key = "zen_quiz_reuse", .role = .overload },100                .{ .key = "zen_quiz_sealed", .role = .transitive_risk },101                .{ .key = "zen_quiz_root", .role = .custom },102                .{ .key = "zen_quiz_consumer", .role = .foreign_risk },103            },104        },105        .bindings = .{106            .owner = @This(),107            .seal = .{108                .family = alloc_phase.capacity.selector(@This().activate),109                .premise = .{110                    .class = .checked_semantic_fact,111                    .authority = .checker,112                },113            },114            .teardown = .{115                .family = alloc_phase.capacity.selector(@This().deinit),116                .premise = .{117                    .class = .checked_semantic_fact,118                    .authority = .checker,119                },120            },121        },122    };123124    pub fn init(allocator: std.mem.Allocator, limits: Limits) InitError!Storage {125        const capacity = try Capacity.derive(limits);126        const bytes = if (capacity.storage_bytes == 0)127            @as([]align(capacity_mod.storage_alignment) u8, &.{})128        else129            try allocator.alignedAlloc(130                u8,131                .fromByteUnits(capacity_mod.storage_alignment),132                capacity.storage_bytes,133            );134        return .{135            .phase = .initialization,136            .capacity = capacity,137            .bytes = bytes,138            .questions = typedSlice(139                model.Question,140                bytes,141                capacity.questions_offset,142                limits.max_questions,143            ),144            .options = typedSlice(145                model.Option,146                bytes,147                capacity.options_offset,148                limits.max_options,149            ),150            .joined_text = bytes[capacity.joined_text_offset..][0..limits.max_joined_text_bytes],151        };152    }153154    pub fn activate(self: *Storage) void {155        std.debug.assert(self.phase == .initialization);156        self.assertStorage();157        self.phase = .steady;158    }159160    pub fn acquire(self: *Storage, source: []const u8) AcquireError!Regions {161        std.debug.assert(self.phase == .steady);162        if (self.in_use) return error.QuizStorageInUse;163        const plan = plan_mod.Plan.inspect(source, self.capacity.limits) catch |err| {164            self.rejected_source_count +|= 1;165            return err;166        };167        self.in_use = true;168        self.question_count = plan.questions;169        self.option_count = plan.options;170        self.joined_text_bytes = plan.joined_text_bytes;171        self.high_water_questions = @max(self.high_water_questions, plan.questions);172        self.high_water_options = @max(self.high_water_options, plan.options);173        self.high_water_joined_text_bytes = @max(174            self.high_water_joined_text_bytes,175            plan.joined_text_bytes,176        );177        self.assertStorage();178        return .{179            .plan = plan,180            .questions = self.questions[0..plan.questions],181            .options = self.options[0..plan.options],182            .joined_text = self.joined_text[0..plan.joined_text_bytes],183        };184    }185186    pub fn reset(self: *Storage) void {187        std.debug.assert(self.phase == .steady);188        std.debug.assert(self.in_use);189        self.in_use = false;190        self.question_count = 0;191        self.option_count = 0;192        self.joined_text_bytes = 0;193        self.assertStorage();194    }195196    pub fn status(self: *const Storage) Status {197        return .{198            .phase = self.phase,199            .in_use = self.in_use,200            .storage_bytes = self.capacity.storage_bytes,201            .max_questions = self.capacity.limits.max_questions,202            .max_options = self.capacity.limits.max_options,203            .max_joined_text_bytes = self.capacity.limits.max_joined_text_bytes,204            .question_count = self.question_count,205            .option_count = self.option_count,206            .joined_text_bytes = self.joined_text_bytes,207            .high_water_questions = self.high_water_questions,208            .high_water_options = self.high_water_options,209            .high_water_joined_text_bytes = self.high_water_joined_text_bytes,210            .rejected_source_count = self.rejected_source_count,211        };212    }213214    pub fn deinit(self: *Storage, allocator: std.mem.Allocator) void {215        std.debug.assert(self.phase != .teardown);216        std.debug.assert(!self.in_use);217        self.assertStorage();218        self.phase = .teardown;219        allocator.free(self.bytes);220        self.bytes = &.{};221        self.questions = &.{};222        self.options = &.{};223        self.joined_text = &.{};224    }225226    fn assertStorage(self: *const Storage) void {227        std.debug.assert(self.bytes.len == self.capacity.storage_bytes);228        std.debug.assert(self.questions.len == self.capacity.limits.max_questions);229        std.debug.assert(self.options.len == self.capacity.limits.max_options);230        std.debug.assert(self.joined_text.len == self.capacity.limits.max_joined_text_bytes);231        std.debug.assert(self.question_count <= self.questions.len);232        std.debug.assert(self.option_count <= self.options.len);233        std.debug.assert(self.joined_text_bytes <= self.joined_text.len);234        std.debug.assert(self.high_water_questions <= self.questions.len);235        std.debug.assert(self.high_water_options <= self.options.len);236        std.debug.assert(self.high_water_joined_text_bytes <= self.joined_text.len);237        if (!self.in_use) {238            std.debug.assert(self.question_count == 0);239            std.debug.assert(self.option_count == 0);240            std.debug.assert(self.joined_text_bytes == 0);241        }242    }243};

1/// Reusable caller-allocated storage for one parsed quiz.2pub const QuizStorage = quiz.Storage;