tiny.zen.DiagramDocumentStorage

1pub const Storage = struct {2    phase: alloc_phase.capacity.Phase,3    capacity: capacity_mod.Capacity,4    line_scratch: []u8,5    document_bytes: []u8,6    prepared: ?plan_mod.Plan = null,7    document_slot: [@sizeOf(spec.Document)]u8 align(@alignOf(spec.Document)) = undefined,8    document_end: usize = 0,9    document_peak: usize = 0,10    in_use: bool = false,11    source_bytes: usize = 0,12    high_water_source_bytes: usize = 0,13    high_water_line_scratch_bytes: usize = 0,14    high_water_document_bytes: usize = 0,15    rejected_document_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 ParseError: type = model.Error;2223    pub const claim: alloc_phase.capacity.Declaration = .{24        .source = .{25            .id = "zen.diagram_document_storage",26            .kind = .phase_static,27            .limit_source = .caller,28            .storage = .{29                .covered = &.{30                    .{31                        .id = "json_line_parse_scratch",32                        .lifetime = .steady,33                        .detail = "JSON line parse scratch",34                    },35                    .{36                        .id = "parsed_diagram_document_values_and_retained_strings",37                        .lifetime = .steady,38                        .detail = "parsed diagram Document values and retained strings",39                    },40                },41                .excluded = &.{42                    "caller-owned JSONL source",43                    "ASCII and SVG render scratch, output, Markdown, and filesystem owners",44                },45            },46            .capacity = .{47                .inputs = &.{48                    alloc_phase.capacity.bindInput(Limits, "max_line_scratch_bytes", "max_line_scratch_bytes"),49                    alloc_phase.capacity.bindInput(Limits, "max_document_bytes", "max_document_bytes"),50                },51                .type_selectors = &.{},52                .nodes = &.{53                    .{ .input = 0 },54                    .{ .input = 1 },55                    .{ .add = .{ .left = 0, .right = 1 } },56                },57                .assertions = &.{.{58                    .scope = .closure_total,59                    .measure = .retained,60                    .relation = .exact,61                    .expression = 2,62                }},63            },64            .overload = .{65                .kind = .drop,66                .detail = "an in-use, oversized, or invalid attempted source is dropped while the two reusable regions remain eligible for later input",67            },68            .risks = .{69                .transitive = .{70                    .status = .witnessed,71                    .detail = "survey and parsing use only caller source plus the two activated regions, with a stable owner-backed allocator context",72                },73                .foreign = .{74                    .status = .excluded,75                    .detail = "diagram Document parsing crosses no operating-system or foreign callback boundary",76                },77            },78            .obligations = &.{79                .{ .key = "zen_diagram_document_capacity", .role = .capacity_model },80                .{ .key = "zen_diagram_document_acquisition", .role = .custom },81                .{ .key = "zen_diagram_document_oom", .role = .custom },82                .{ .key = "zen_diagram_document_boundaries", .role = .overload },83                .{ .key = "zen_diagram_document_reuse", .role = .overload },84                .{ .key = "zen_diagram_document_differential", .role = .custom },85                .{ .key = "zen_diagram_document_sealed", .role = .transitive_risk },86                .{ .key = "zen_diagram_document_root", .role = .custom },87                .{ .key = "zen_diagram_document_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 line_scratch = try allocateRegion(allocator, capacity.line_scratch_bytes);112        errdefer allocator.free(line_scratch);113        const document_bytes = try allocateRegion(allocator, capacity.document_bytes);114        return .{115            .phase = .initialization,116            .capacity = capacity,117            .line_scratch = line_scratch,118            .document_bytes = document_bytes,119        };120    }121122    pub fn initExact(allocator: std.mem.Allocator, jsonl: []const u8) !Storage {123        const line_scratch_bytes = try plan_mod.Plan.requiredLineScratchBytes(jsonl);124        const line_scratch = try allocateRegion(allocator, line_scratch_bytes);125        errdefer allocator.free(line_scratch);126        const plan = try plan_mod.Plan.inspect(line_scratch, jsonl);127        const capacity = try Capacity.derive(plan.exactLimits());128        const document_bytes = try allocateRegion(allocator, capacity.document_bytes);129        return .{130            .phase = .initialization,131            .capacity = capacity,132            .line_scratch = line_scratch,133            .document_bytes = document_bytes,134            .prepared = plan,135            .high_water_line_scratch_bytes = @intCast(plan.surveyed.scratch_high_water),136        };137    }138139    pub fn activate(self: *Storage) void {140        std.debug.assert(self.phase == .initialization);141        self.assertStorage();142        self.phase = .steady;143    }144145    pub fn parse(self: *Storage, jsonl: []const u8) ParseError!*const spec.Document {146        std.debug.assert(self.phase == .steady);147        if (self.in_use) return self.reject(error.DiagramDocumentStorageInUse);148        const required_line_scratch = plan_mod.Plan.requiredLineScratchBytes(jsonl) catch |err| {149            self.rejected_document_count +|= 1;150            return err;151        };152        if (required_line_scratch > self.capacity.line_scratch_bytes) {153            return self.reject(error.DiagramLineScratchCapacityExceeded);154        }155        const plan = if (self.prepared) |prepared|156            if (prepared.matches(jsonl)) prepared else plan_mod.Plan.inspect(self.line_scratch, jsonl) catch |err| {157                self.rejected_document_count +|= 1;158                return err;159            }160        else161            plan_mod.Plan.inspect(self.line_scratch, jsonl) catch |err| {162                self.rejected_document_count +|= 1;163                return err;164            };165        plan.require(self.capacity.limits) catch |err| return self.reject(err);166167        self.document_end = 0;168        self.document_peak = 0;169        const parsed = spec.Document.parse(170            documentAllocator(self),171            self.line_scratch[0..plan.line_scratch_bytes],172            jsonl,173        ) catch |err| {174            self.observe(plan, jsonl.len);175            self.document_end = 0;176            self.document_peak = 0;177            self.prepared = null;178            self.rejected_document_count +|= 1;179            return err;180        };181        documentSlot(self).* = parsed;182        self.in_use = true;183        self.source_bytes = jsonl.len;184        self.prepared = null;185        self.observe(plan, jsonl.len);186        self.assertStorage();187        return documentSlot(self);188    }189190    pub fn reset(self: *Storage) void {191        std.debug.assert(self.phase == .steady);192        std.debug.assert(self.in_use);193        documentSlot(self).deinit();194        self.document_end = 0;195        self.document_peak = 0;196        self.in_use = false;197        self.source_bytes = 0;198        self.assertStorage();199    }200201    pub fn status(self: *const Storage) Status {202        return .{203            .phase = self.phase,204            .in_use = self.in_use,205            .storage_bytes = self.capacity.storage_bytes,206            .line_scratch_bytes = self.capacity.line_scratch_bytes,207            .document_bytes = self.capacity.document_bytes,208            .source_bytes = self.source_bytes,209            .document_bytes_used = self.document_end,210            .high_water_source_bytes = self.high_water_source_bytes,211            .high_water_line_scratch_bytes = self.high_water_line_scratch_bytes,212            .high_water_document_bytes = self.high_water_document_bytes,213            .rejected_document_count = self.rejected_document_count,214        };215    }216217    pub fn deinit(self: *Storage, allocator: std.mem.Allocator) void {218        std.debug.assert(self.phase != .teardown);219        std.debug.assert(!self.in_use);220        self.assertStorage();221        self.phase = .teardown;222        allocator.free(self.document_bytes);223        allocator.free(self.line_scratch);224        self.document_bytes = &.{};225        self.line_scratch = &.{};226        self.prepared = null;227    }228229    fn reject(self: *Storage, err: model.Exhaustion) model.Exhaustion {230        self.rejected_document_count +|= 1;231        return err;232    }233234    fn observe(self: *Storage, plan: plan_mod.Plan, source_bytes: usize) void {235        self.high_water_source_bytes = @max(self.high_water_source_bytes, source_bytes);236        self.high_water_line_scratch_bytes = @max(237            self.high_water_line_scratch_bytes,238            @as(usize, @intCast(plan.surveyed.scratch_high_water)),239        );240        self.high_water_document_bytes = @max(241            self.high_water_document_bytes,242            @max(self.document_end, self.document_peak),243        );244    }245246    fn assertStorage(self: *const Storage) void {247        std.debug.assert(self.line_scratch.len == self.capacity.line_scratch_bytes);248        std.debug.assert(self.document_bytes.len == self.capacity.document_bytes);249        std.debug.assert(self.capacity.storage_bytes == self.line_scratch.len + self.document_bytes.len);250        std.debug.assert(self.document_end <= self.document_bytes.len);251        std.debug.assert(self.document_peak <= self.document_bytes.len);252        std.debug.assert(self.high_water_line_scratch_bytes <= self.line_scratch.len);253        std.debug.assert(self.high_water_document_bytes <= self.document_bytes.len);254        if (!self.in_use) std.debug.assert(self.source_bytes == 0);255    }256};

1/// Reusable caller-allocated storage for one parsed JSONL diagram.2pub const DiagramDocumentStorage = diagram.DocumentStorage;