tiny.zen.SiteCatalogStorage

1pub const Storage = struct {2    phase: alloc_phase.capacity.Phase,3    capacity: capacity_mod.Capacity,4    bytes: []align(capacity_mod.storage_alignment) u8,5    entries: []model.Entry,6    text: []u8,7    pages: usize = 0,8    text_bytes: usize = 0,9    rejected_entry_count: u64 = 0,10    sealed: bool = false,1112    pub const Limits: type = capacity_mod.Limits;13    pub const Capacity: type = capacity_mod.Capacity;14    pub const Exhaustion: type = model.Exhaustion;15    pub const InitError = std.mem.Allocator.Error || capacity_mod.DeriveError;16    pub const AppendError: type = model.Error;1718    pub const claim: alloc_phase.capacity.Declaration = .{19        .source = .{20            .id = "zen.site_catalog_storage",21            .kind = .phase_static,22            .limit_source = .caller,23            .storage = .{24                .covered = &.{25                    .{26                        .id = "retained_site_catalog_entry_descriptors",27                        .lifetime = .steady,28                        .detail = "retained site catalog entry descriptors",29                    },30                    .{31                        .id = "retained_path_url_title_and_date_bytes",32                        .lifetime = .steady,33                        .detail = "retained path, URL, title, and date bytes",34                    },35                },36                .excluded = &.{37                    "caller-owned limits, source paths, Markdown page bytes, and frontmatter scratch",38                    "filesystem walkers, rendered pages, theme output, page-list expansion, and assets",39                },40            },41            .capacity = .{42                .inputs = &.{43                    alloc_phase.capacity.bindInput(Limits, "max_pages", "max_pages"),44                    alloc_phase.capacity.bindInput(Limits, "max_text_bytes", "max_text_bytes"),45                },46                .type_selectors = &.{47                    alloc_phase.capacity.bindType(model.Entry, "entry"),48                },49                .nodes = &.{50                    .{ .input = 0 },51                    .{ .scale = .{ .node = 0, .coefficient = .{ .size_of_concrete_type = 0 } } },52                    .{ .alignment = .{ .node = 1, .alignment = .{ .literal = 16 } } },53                    .{ .input = 1 },54                    .{ .add = .{ .left = 2, .right = 3 } },55                },56                .assertions = &.{.{57                    .scope = .closure_total,58                    .measure = .retained,59                    .relation = .exact,60                    .expression = 4,61                }},62            },63            .overload = .{64                .kind = .reject_before_mutation,65                .detail = "entry demand rejects before mutation; rejection telemetry advances",66            },67            .risks = .{68                .transitive = .{69                    .status = .witnessed,70                    .detail = "append, sort, and borrow use only exact preacquired storage",71                },72                .foreign = .{73                    .status = .excluded,74                    .detail = "directory walks and page reads are excluded site-build effects",75                },76            },77            .obligations = &.{78                .{ .key = "zen_site_catalog_capacity", .role = .capacity_model },79                .{ .key = "zen_site_catalog_acquisition", .role = .custom },80                .{ .key = "zen_site_catalog_oom", .role = .custom },81                .{ .key = "zen_site_catalog_boundaries", .role = .overload },82                .{ .key = "zen_site_catalog_atomic_rejection", .role = .overload },83                .{ .key = "zen_site_catalog_sealed", .role = .transitive_risk },84                .{ .key = "zen_site_catalog_root", .role = .custom },85                .{ .key = "zen_site_catalog_consumer", .role = .foreign_risk },86            },87        },88        .bindings = .{89            .owner = @This(),90            .seal = .{91                .family = alloc_phase.capacity.selector(@This().activate),92                .premise = .{93                    .class = .checked_semantic_fact,94                    .authority = .checker,95                },96            },97            .teardown = .{98                .family = alloc_phase.capacity.selector(@This().deinit),99                .premise = .{100                    .class = .checked_semantic_fact,101                    .authority = .checker,102                },103            },104        },105    };106107    pub fn init(allocator: std.mem.Allocator, limits: Limits) InitError!Storage {108        const capacity = try Capacity.derive(limits);109        const bytes = try allocator.alignedAlloc(110            u8,111            .fromByteUnits(capacity_mod.storage_alignment),112            capacity.storage_bytes,113        );114        std.debug.assert(bytes.len == capacity.storage_bytes);115        const storage = Storage{116            .phase = .initialization,117            .capacity = capacity,118            .bytes = bytes,119            .entries = typedSlice(model.Entry, bytes, capacity.entries_offset, limits.max_pages),120            .text = bytes[capacity.text_offset..][0..limits.max_text_bytes],121        };122        storage.assertStorage();123        std.debug.assert(storage.pages == 0);124        std.debug.assert(storage.text_bytes == 0);125        return storage;126    }127128    pub fn activate(self: *Storage) void {129        std.debug.assert(self.phase == .initialization);130        std.debug.assert(!self.sealed);131        std.debug.assert(self.pages == 0);132        std.debug.assert(self.text_bytes == 0);133        self.assertStorage();134        self.phase = .steady;135    }136137    pub fn append(self: *Storage, input: model.EntryInput) AppendError!*const model.Entry {138        std.debug.assert(self.phase == .steady);139        std.debug.assert(!self.sealed);140        std.debug.assert(self.pages <= self.entries.len);141        std.debug.assert(self.text_bytes <= self.text.len);142        const demand = plan_mod.Demand.fromInput(input);143        const demand_bytes = demand.textBytes() catch |err| return self.reject(err);144        std.debug.assert(demand_bytes >= input.relative_path.len);145        const next_pages = std.math.add(usize, self.pages, 1) catch146            return self.reject(error.CapacityOverflow);147        if (next_pages > self.entries.len) {148            return self.reject(error.SiteCatalogPageCapacityExceeded);149        }150        const next_text = std.math.add(usize, self.text_bytes, demand_bytes) catch151            return self.reject(error.CapacityOverflow);152        if (next_text > self.text.len) {153            return self.reject(error.SiteCatalogTextCapacityExceeded);154        }155156        var cursor = self.text_bytes;157        const relative_path = self.appendText(&cursor, input.relative_path);158        const url = self.appendText(&cursor, input.url);159        const title = self.appendText(&cursor, input.title);160        const date = self.appendText(&cursor, input.date);161        const type_label = self.appendText(&cursor, input.type_label);162        std.debug.assert(cursor == next_text);163        self.entries[self.pages] = .{164            .relative_path = relative_path,165            .url = url,166            .title = title,167            .date = date,168            .section = model.section(relative_path),169            .type_label = type_label,170            .dispatch = input.dispatch,171            .draft = input.draft,172            .slop = input.slop,173        };174        self.pages = next_pages;175        self.text_bytes = next_text;176        self.assertStorage();177        const entry = &self.entries[self.pages - 1];178        std.debug.assert(entry.relative_path.len == input.relative_path.len);179        std.debug.assert(entry.url.len == input.url.len);180        std.debug.assert(entry.title.len == input.title.len);181        std.debug.assert(entry.date.len == input.date.len);182        std.debug.assert(entry.type_label.len == input.type_label.len);183        std.debug.assert(entry.dispatch == input.dispatch);184        return entry;185    }186187    pub fn seal(self: *Storage, base: []const u8) model.Catalog {188        std.debug.assert(self.phase == .steady);189        std.debug.assert(!self.sealed);190        std.mem.sort(model.Entry, self.entries[0..self.pages], {}, model.lessThan);191        self.sealed = true;192        self.assertStorage();193        for (self.entries[0..self.pages], 0..) |entry, index| {194            if (index != 0) {195                std.debug.assert(!model.lessThan({}, entry, self.entries[index - 1]));196            }197        }198        return .{ .base = base, .pages = self.entries[0..self.pages] };199    }200201    pub fn status(self: *const Storage) Status {202        return .{203            .phase = self.phase,204            .sealed = self.sealed,205            .storage_bytes = self.capacity.storage_bytes,206            .max_pages = self.capacity.limits.max_pages,207            .max_text_bytes = self.capacity.limits.max_text_bytes,208            .pages = self.pages,209            .text_bytes = self.text_bytes,210            .rejected_entry_count = self.rejected_entry_count,211        };212    }213214    pub fn deinit(self: *Storage, allocator: std.mem.Allocator) void {215        std.debug.assert(self.phase != .teardown);216        self.assertStorage();217        self.phase = .teardown;218        allocator.free(self.bytes);219        self.bytes = &.{};220        self.entries = &.{};221        self.text = &.{};222        self.pages = 0;223        self.text_bytes = 0;224    }225226    fn appendText(self: *Storage, cursor: *usize, source: []const u8) []const u8 {227        std.debug.assert(cursor.* <= self.text.len);228        std.debug.assert(source.len <= self.text.len - cursor.*);229        const start = cursor.*;230        @memcpy(self.text[start..][0..source.len], source);231        cursor.* += source.len;232        return self.text[start..cursor.*];233    }234235    fn reject(self: *Storage, err: model.Error) model.Error {236        std.debug.assert(self.phase == .steady);237        std.debug.assert(!self.sealed);238        self.assertStorage();239        self.rejected_entry_count +|= 1;240        return err;241    }242243    fn assertStorage(self: *const Storage) void {244        std.debug.assert(self.bytes.len == self.capacity.storage_bytes);245        std.debug.assert(self.entries.len == self.capacity.limits.max_pages);246        std.debug.assert(self.text.len == self.capacity.limits.max_text_bytes);247        std.debug.assert(self.pages <= self.entries.len);248        std.debug.assert(self.text_bytes <= self.text.len);249        std.debug.assert(@intFromPtr(self.bytes.ptr) % capacity_mod.storage_alignment == 0);250        if (self.sealed) std.debug.assert(self.phase == .steady);251    }252};

1/// Append-only storage whose `seal` result borrows its sorted entries and text.2pub const SiteCatalogStorage = site_catalog.Storage;