tiny.zen.SitePathStorage

1pub const Storage = struct {2    phase: alloc_phase.capacity.Phase,3    capacity: capacity_mod.Capacity,4    bytes: []u8,5    target_path: []u8,6    public_path: []u8,7    in_use: bool = false,8    target_path_bytes: usize = 0,9    public_path_bytes: usize = 0,10    high_water_target_path_bytes: usize = 0,11    high_water_public_path_bytes: usize = 0,12    rejected_path_count: u64 = 0,1314    pub const Limits: type = capacity_mod.Limits;15    pub const Capacity: type = capacity_mod.Capacity;16    pub const Exhaustion: type = model.Exhaustion;17    pub const InitError = std.mem.Allocator.Error || capacity_mod.DeriveError;18    pub const AcquireError: type = model.Error;1920    pub const claim: alloc_phase.capacity.Declaration = .{21        .source = .{22            .id = "zen.site_path_storage",23            .kind = .phase_static,24            .limit_source = .caller,25            .storage = .{26                .covered = &.{27                    .{28                        .id = "markdown_target_path_bytes",29                        .lifetime = .steady,30                        .detail = "Markdown target path bytes",31                    },32                    .{33                        .id = "public_page_or_clean_url_path_bytes",34                        .lifetime = .steady,35                        .detail = "public page or clean URL path bytes",36                    },37                },38                .excluded = &.{39                    "caller-owned relative paths and build roots",40                    "retained site catalog strings, file contents, rendered pages, and filesystem internals",41                },42            },43            .capacity = .{44                .inputs = &.{45                    alloc_phase.capacity.bindInput(Limits, "max_target_path_bytes", "max_target_path_bytes"),46                    alloc_phase.capacity.bindInput(Limits, "max_public_path_bytes", "max_public_path_bytes"),47                },48                .type_selectors = &.{},49                .nodes = &.{50                    .{ .input = 0 },51                    .{ .input = 1 },52                    .{ .add = .{ .left = 0, .right = 1 } },53                },54                .assertions = &.{.{55                    .scope = .closure_total,56                    .measure = .retained,57                    .relation = .exact,58                    .expression = 2,59                }},60            },61            .overload = .{62                .kind = .reject_before_mutation,63                .detail = "max plus one and in-use requests reject before either reusable path region changes; only rejection telemetry advances",64            },65            .risks = .{66                .transitive = .{67                    .status = .witnessed,68                    .detail = "planning and path filling use borrowed relative paths plus the two acquired byte regions only",69                },70                .foreign = .{71                    .status = .excluded,72                    .detail = "path transformation crosses no operating-system boundary; directory and file effects remain site-build consumers",73                },74            },75            .obligations = &.{76                .{ .key = "zen_site_path_capacity", .role = .capacity_model },77                .{ .key = "zen_site_path_acquisition", .role = .custom },78                .{ .key = "zen_site_path_oom", .role = .custom },79                .{ .key = "zen_site_path_boundaries", .role = .overload },80                .{ .key = "zen_site_path_reuse", .role = .overload },81                .{ .key = "zen_site_path_sealed", .role = .transitive_risk },82                .{ .key = "zen_site_path_root", .role = .custom },83                .{ .key = "zen_site_path_consumer", .role = .foreign_risk },84            },85        },86        .bindings = .{87            .owner = @This(),88            .seal = .{89                .family = alloc_phase.capacity.selector(@This().activate),90                .premise = .{91                    .class = .checked_semantic_fact,92                    .authority = .checker,93                },94            },95            .teardown = .{96                .family = alloc_phase.capacity.selector(@This().deinit),97                .premise = .{98                    .class = .checked_semantic_fact,99                    .authority = .checker,100                },101            },102        },103    };104105    pub fn init(allocator: std.mem.Allocator, limits: Limits) InitError!Storage {106        const capacity = try Capacity.derive(limits);107        const bytes = if (capacity.storage_bytes == 0)108            @as([]u8, &.{})109        else110            try allocator.alloc(u8, capacity.storage_bytes);111        return .{112            .phase = .initialization,113            .capacity = capacity,114            .bytes = bytes,115            .target_path = bytes[capacity.target_path_offset..][0..limits.max_target_path_bytes],116            .public_path = bytes[capacity.public_path_offset..][0..limits.max_public_path_bytes],117        };118    }119120    pub fn activate(self: *Storage) void {121        std.debug.assert(self.phase == .initialization);122        self.assertStorage();123        self.phase = .steady;124    }125126    pub fn acquire(127        self: *Storage,128        relative_path: []const u8,129        clean_urls: bool,130        kind: model.PublicKind,131    ) AcquireError!Paths {132        std.debug.assert(self.phase == .steady);133        if (self.in_use) return self.reject(error.SitePathStorageInUse);134        const plan = plan_mod.Plan.inspect(135            relative_path,136            clean_urls,137            kind,138            self.capacity.limits,139        ) catch |err| {140            self.rejected_path_count +|= 1;141            return err;142        };143        self.in_use = true;144        self.target_path_bytes = plan.target_path_bytes;145        self.public_path_bytes = plan.public_path_bytes;146        self.high_water_target_path_bytes = @max(147            self.high_water_target_path_bytes,148            plan.target_path_bytes,149        );150        self.high_water_public_path_bytes = @max(151            self.high_water_public_path_bytes,152            plan.public_path_bytes,153        );154        const target = transform.writeTarget(155            self.target_path[0..plan.target_path_bytes],156            relative_path,157            clean_urls,158        );159        const public = transform.writePublic(160            self.public_path[0..plan.public_path_bytes],161            target,162            clean_urls,163            kind,164        );165        self.assertStorage();166        return .{ .target = target, .public = public };167    }168169    pub fn reset(self: *Storage) void {170        std.debug.assert(self.phase == .steady);171        std.debug.assert(self.in_use);172        self.in_use = false;173        self.target_path_bytes = 0;174        self.public_path_bytes = 0;175        self.assertStorage();176    }177178    pub fn status(self: *const Storage) Status {179        return .{180            .phase = self.phase,181            .in_use = self.in_use,182            .storage_bytes = self.capacity.storage_bytes,183            .max_target_path_bytes = self.capacity.limits.max_target_path_bytes,184            .max_public_path_bytes = self.capacity.limits.max_public_path_bytes,185            .target_path_bytes = self.target_path_bytes,186            .public_path_bytes = self.public_path_bytes,187            .high_water_target_path_bytes = self.high_water_target_path_bytes,188            .high_water_public_path_bytes = self.high_water_public_path_bytes,189            .rejected_path_count = self.rejected_path_count,190        };191    }192193    pub fn deinit(self: *Storage, allocator: std.mem.Allocator) void {194        std.debug.assert(self.phase != .teardown);195        std.debug.assert(!self.in_use);196        self.assertStorage();197        self.phase = .teardown;198        allocator.free(self.bytes);199        self.bytes = &.{};200        self.target_path = &.{};201        self.public_path = &.{};202    }203204    fn reject(self: *Storage, err: model.Exhaustion) model.Exhaustion {205        self.rejected_path_count +|= 1;206        return err;207    }208209    fn assertStorage(self: *const Storage) void {210        std.debug.assert(self.bytes.len == self.capacity.storage_bytes);211        std.debug.assert(self.target_path.len == self.capacity.limits.max_target_path_bytes);212        std.debug.assert(self.public_path.len == self.capacity.limits.max_public_path_bytes);213        std.debug.assert(self.target_path_bytes <= self.target_path.len);214        std.debug.assert(self.public_path_bytes <= self.public_path.len);215        std.debug.assert(self.high_water_target_path_bytes <= self.target_path.len);216        std.debug.assert(self.high_water_public_path_bytes <= self.public_path.len);217        if (!self.in_use) {218            std.debug.assert(self.target_path_bytes == 0);219            std.debug.assert(self.public_path_bytes == 0);220        }221    }222};

1/// Reusable caller-allocated target-path and public-URL storage.2pub const SitePathStorage = site_path.Storage;