tiny.closure.ledger

1pub const Ledger = struct {2    phase: capacity.Phase,3    capacity: Capacity,4    storage: Storage,56    pub const Limits: type = closure.Limits;7    pub const Capacity: type = closure.Capacity;8    pub const storage_alignment: usize = limits.storage_alignment;9    pub const Storage = []align(storage_alignment) u8;10    pub const Exhaustion: type = LedgerExhaustion;11    pub const InitError: type =12        Capacity.DeriveError || error{StorageTooShort};13    pub const PrepareError: type =14        OwnerError || ValidationError || Exhaustion || StagingError;15    pub const PublishError: type = OwnerError || PublicationError;16    pub const RecoveryError: type = OwnerError;17    pub const SnapshotError: type = OwnerError;18    pub const ScratchError: type = OwnerError;19    pub const ProjectionScratch: type = ProjectionScratchModel;20    pub const work_limits: capacity.WorkLimits = .{21        .transition_steps_max = 4_000_000,22        .cleanup_steps_per_call_max = 1,23        .cleanup_calls_at_capacity_max = 1,24    };25    pub const claim: capacity.Declaration = .{26        .source = .{27            .id = "closure.ledger",28            .kind = .startup_static,29            .limit_source = .caller,30            .storage = .{31                .covered = &.{32                    .{33                        .id = "caller_provisioned_double_buffered_closure_ledger_storage",34                        .lifetime = .steady,35                        .detail = "caller-provisioned double-buffered closure ledger storage",36                    },37                },38                .excluded = &.{39                    "ledger owner handle",40                    "borrowed GenerationInput source slices",41                    "external artifact bytes",42                },43            },44            .capacity = .{45                .inputs = &.{46                    capacity.bindInput(Limits, "artifacts", "artifacts"),47                    capacity.bindInput(Limits, "authorities", "authorities"),48                    capacity.bindInput(Limits, "build_records", "build_records"),49                    capacity.bindInput(Limits, "claim_nodes", "claim_nodes"),50                    capacity.bindInput(Limits, "claims", "claims"),51                    capacity.bindInput(Limits, "digests", "digests"),52                    capacity.bindInput(Limits, "edges", "edges"),53                    capacity.bindInput(Limits, "lineage_references", "lineage_references"),54                    capacity.bindInput(Limits, "nodes", "nodes"),55                    capacity.bindInput(Limits, "provenance_parents", "provenance_parents"),56                    capacity.bindInput(Limits, "ranges", "ranges"),57                    capacity.bindInput(Limits, "receipt_bytes", "receipt_bytes"),58                    capacity.bindInput(Limits, "residual_roots", "residual_roots"),59                    capacity.bindInput(Limits, "service_descriptors", "service_descriptors"),60                    capacity.bindInput(Limits, "source_records", "source_records"),61                },62                .type_selectors = &.{},63                .nodes = &.{64                    .{ .input = 0 },65                    .{ .input = 1 },66                    .{ .input = 2 },67                    .{ .input = 3 },68                    .{ .input = 4 },69                    .{ .input = 5 },70                    .{ .input = 6 },71                    .{ .input = 7 },72                    .{ .input = 8 },73                    .{ .input = 9 },74                    .{ .input = 10 },75                    .{ .input = 11 },76                    .{ .input = 12 },77                    .{ .input = 13 },78                    .{ .input = 14 },79                    .{ .add = .{ .left = 0, .right = 1 } },80                    .{ .add = .{ .left = 15, .right = 2 } },81                    .{ .add = .{ .left = 16, .right = 3 } },82                    .{ .add = .{ .left = 17, .right = 4 } },83                    .{ .add = .{ .left = 18, .right = 5 } },84                    .{ .add = .{ .left = 19, .right = 6 } },85                    .{ .add = .{ .left = 20, .right = 7 } },86                    .{ .add = .{ .left = 21, .right = 8 } },87                    .{ .add = .{ .left = 22, .right = 9 } },88                    .{ .add = .{ .left = 23, .right = 10 } },89                    .{ .add = .{ .left = 24, .right = 11 } },90                    .{ .add = .{ .left = 25, .right = 12 } },91                    .{ .add = .{ .left = 26, .right = 13 } },92                    .{ .add = .{ .left = 27, .right = 14 } },93                },94                .assertions = &.{.{95                    .scope = .closure_total,96                    .measure = .retained,97                    .relation = .upper_bound,98                    .expression = 28,99                }},100            },101            .overload = .{102                .kind = .reject_before_mutation,103                .detail = "every record occupancy and generation overflow rejects before copy",104            },105            .risks = .{106                .transitive = .{107                    .status = .excluded,108                    .detail = "ledger storage and validation retain no allocator capability",109                },110                .foreign = .{111                    .status = .excluded,112                    .detail = "ledger assembly reads only typed caller-owned records",113                },114            },115            .work = .{ .equation = "prepare validation and copy <= 4000000 bounded steps" },116            .obligations = &.{117                .{ .key = "closure_ledger_capacity_capacity_model", .role = .capacity_model },118                .{ .key = "closure_ledger_capacity_transitive_risk", .role = .transitive_risk },119                .{ .key = "closure_ledger_overload", .role = .overload },120                .{ .key = "closure_ledger_validation", .role = .foreign_risk },121                .{ .key = "closure_ledger_recovery", .role = .custom },122                .{ .key = "closure_ledger_work", .role = .work_bound },123            },124        },125        .bindings = .{126            .owner = @This(),127        },128    };129130    pub fn init(131        storage: Storage,132        requested: Limits,133    ) InitError!Ledger {134        const derived = try Capacity.derive(requested);135        if (storage.len < derived.storage_bytes) {136            return error.StorageTooShort;137        }138        @memset(storage[0..derived.storage_bytes], 0);139        const header = pointerAt(Header, storage, derived.layout.header);140        header.* = .{141            .magic = header_magic,142            .self_address = 0,143            .slot_state = encodeSlots(null, null),144            .phase = .initialization,145            .reserved = @splat(0),146        };147        return .{148            .phase = .initialization,149            .capacity = derived,150            .storage = storage,151        };152    }153154    pub fn activate(self: *Ledger) void {155        const header = self.sharedHeader();156        std.debug.assert(self.phase == .initialization);157        std.debug.assert(header.phase == .initialization);158        std.debug.assert(header.self_address == 0);159        header.self_address = @intFromPtr(self);160        header.phase = .steady;161        self.phase = .steady;162    }163164    pub fn prepare(165        self: *Ledger,166        input: schema.GenerationInput,167    ) PrepareError!void {168        try self.requireOwned();169        const state = self.loadSlots();170        if (stagedSlot(state) != null) {171            return error.GenerationAlreadyStaged;172        }173        try validateOccupancy(self.capacity, input);174        try self.validateGeneration(activeSlot(state), input.id);175        try validateCanonical(input);176        const target = inactiveSlot(activeSlot(state));177        copyInput(self.storage, self.slotLayout(target), input);178        self.storeSlots(encodeSlots(activeSlot(state), target));179    }180181    pub fn publish(self: *Ledger) PublishError!void {182        try self.requireOwned();183        const state = self.loadSlots();184        const staged = stagedSlot(state) orelse {185            return error.NoStagedGeneration;186        };187        std.debug.assert(activeSlot(state) != staged);188        self.storeSlots(encodeSlots(staged, null));189    }190191    pub fn recover(self: *Ledger) RecoveryError!bool {192        try self.requireOwned();193        const state = self.loadSlots();194        if (stagedSlot(state) == null) return false;195        self.storeSlots(encodeSlots(activeSlot(state), null));196        return true;197    }198199    pub fn snapshot(200        self: *const Ledger,201    ) SnapshotError!?schema.GenerationInput {202        try self.requireOwned();203        const slot = activeSlot(self.loadSlots()) orelse return null;204        return inputView(205            self.storage,206            self.slotLayout(slot),207        );208    }209210    pub fn projectionScratch(211        self: *Ledger,212    ) ScratchError!ProjectionScratch {213        try self.requireOwned();214        const visited_end = self.capacity.layout.visited +215            self.capacity.nodes;216        return .{217            .visited = self.storage[self.capacity.layout.visited..visited_end],218            .queue = sliceAt(219                u32,220                self.storage,221                self.capacity.layout.queue,222                self.capacity.nodes,223            ),224        };225    }226227    pub fn receiptScratch(self: *Ledger) ScratchError![]u8 {228        try self.requireOwned();229        const end = self.capacity.layout.receipt +230            self.capacity.receipt_bytes;231        return self.storage[self.capacity.layout.receipt..end];232    }233234    pub fn deinit(self: *Ledger) Storage {235        self.requireOwned() catch unreachable;236        const state = self.loadSlots();237        if (stagedSlot(state) != null) {238            self.storeSlots(encodeSlots(activeSlot(state), null));239        }240        self.sharedHeader().phase = .teardown;241        self.phase = .teardown;242        const storage = self.storage;243        self.* = undefined;244        return storage;245    }246247    fn validateGeneration(248        self: *const Ledger,249        active: ?Slot,250        generation: schema.GenerationId,251    ) (ValidationError || Exhaustion)!void {252        if (active) |slot| {253            const current = self.slotHeader(slot).generation;254            if (current == std.math.maxInt(schema.GenerationId)) {255                return error.GenerationExhausted;256            }257            if (generation != current + 1) {258                return error.GenerationOutOfOrder;259            }260            return;261        }262        if (generation == 0) return error.GenerationOutOfOrder;263    }264265    fn requireOwned(self: *const Ledger) OwnerError!void {266        const header = self.sharedHeaderConst();267        if (self.phase != .steady or header.phase != .steady) {268            return error.InvalidPhase;269        }270        std.debug.assert(header.magic == header_magic);271        if (header.self_address != @intFromPtr(self)) {272            return error.CopiedOwner;273        }274    }275276    fn sharedHeader(self: *Ledger) *Header {277        return pointerAt(278            Header,279            self.storage,280            self.capacity.layout.header,281        );282    }283284    fn sharedHeaderConst(self: *const Ledger) *const Header {285        return constPointerAt(286            Header,287            self.storage,288            self.capacity.layout.header,289        );290    }291292    fn slotHeader(self: *const Ledger, slot: Slot) *const SlotHeader {293        return constPointerAt(294            SlotHeader,295            self.storage,296            self.slotLayout(slot).header,297        );298    }299300    fn slotLayout(self: *const Ledger, slot: Slot) limits.SlotLayout {301        return self.capacity.layout.slots[@backingInt(slot)];302    }303304    fn loadSlots(self: *const Ledger) u8 {305        return @atomicLoad(306            u8,307            &self.sharedHeaderConst().slot_state,308            .acquire,309        );310    }311312    fn storeSlots(self: *Ledger, state: u8) void {313        @atomicStore(314            u8,315            &self.sharedHeader().slot_state,316            state,317            .release,318        );319    }320};

1const store = @import("store.zig");23pub const Ledger = store.Ledger;

1pub const ledger = @import("ledger/root.zig");