tiny.machine.explore.query

1pub const Capacity = struct {2    frames: u16,3    evidence: u16,4};

1pub const ChoicePattern = struct {2    stream: ?explore.Stream = null,3};

1pub const Cursor = struct {2    history: Identity,3    offset: u32,4    first: u32,5    end: u32,6    order: QueryOrder,7};

1pub const DiffCapacity = struct {2    prefix: u16,3    suffix: u16,4};

1pub const DiffCompletion = union(enum) {2    complete,3    incomplete: DiffIncompleteReason,4};

1pub const DiffIncompleteReason = enum(u8) {2    prefix_capacity = 1,3    suffix_capacity = 2,4    work_budget = 3,5    source_incomplete = 4,6};

1pub const DiffResult = struct {2    prefix: []const FramePair,3    left_suffix: []const FrameRefs,4    right_suffix: []const FrameRefs,5    divergence: ?Divergence,6    compared: u32,7    completion: DiffCompletion,8};

1pub const Divergence = struct {2    reason: DivergenceReason,3    left: ?FrameRefs,4    right: ?FrameRefs,5    roots: RootDifference,6};

1pub const DivergenceReason = enum(u8) {2    choice = 1,3    evidence = 2,4    root = 3,5    length = 4,6};

1pub const EffectPattern = struct {2    correlation: ?u64 = null,3    phase: ?EffectPhase = null,4    status: ?os.abi.EffectStatus = null,5};

1pub const EffectPhase = enum(u8) {2    choice = 1,3    request = 2,4    result = 3,5    operation = 4,6};

1pub const Evidence = union(enum) {2    transition: fabric.transition.Wire,3    machine: os.abi.MessageWire,4    semantic: explore.Event,5};

1pub const EvidenceRange = struct {2    first: ?EvidenceRef,3    count: u16,4};

1pub const EvidenceRef = struct {2    history: Identity,3    target: Target,4    index: u16,5};

1pub const FaultPattern = struct {2    kind: ?fault.Kind = null,3    choice: ?fault.Choice = null,4};

1pub const Frame = struct {2    decision: explore.SearchDecision,3    expected: world.Moment,4    evidence_start: u16,5    evidence_count: u16,6};

1pub const FramePair = struct {2    left: FrameRefs,3    right: FrameRefs,4};

1pub const FrameRefs = struct {2    choice: EvidenceRef,3    evidence: EvidenceRange,4    root: EvidenceRef,5};

1pub const Identity = struct {2    digest: [32]u8,34    pub fn hex(self: Identity) [64]u8 {5        return std.fmt.bytesToHex(self.digest, .lower);6    }7};

1pub const IncompleteReason = enum(u8) {2    result_capacity = 1,3    work_budget = 2,4    source_incomplete = 3,5};

1pub const Kind = enum(u8) {2    all = 1,3    choice = 2,4    scheduler = 3,5    root = 4,6    semantic = 5,7    transition = 6,8    machine = 7,9    packet = 8,10    fault = 9,11    effect = 10,12    terminal = 11,13};

1pub const Located = struct {2    reference: EvidenceRef,3    frame: ?u16,4    virtual_time_tick: ?u64,5    view: View,6};

1pub const PacketAction = enum(u8) {2    choose = 1,3    send = 2,4    deliver = 3,5    drop = 4,6    delay = 5,7    reorder = 6,8};

1pub const PacketPattern = struct {2    id: ?u64 = null,3    action: ?PacketAction = null,4};

1pub const Pattern = union(enum) {2    kind: Kind,3    choice: ChoicePattern,4    semantic: explore.Pattern,5    packet: PacketPattern,6    fault: FaultPattern,7    effect: EffectPattern,8    terminal: TerminalPattern,9};

1pub const QueryCapacity = struct {2    results: u16,3};

1pub const QueryCompletion = union(enum) {2    complete,3    incomplete: IncompleteReason,4};

1pub const QueryOrder = enum(u8) {2    forward = 1,3    reverse = 2,4};

1pub const QueryPlan = struct {2    pattern: Pattern,3    work: u32,4    scope: QueryScope = .branch,5    order: QueryOrder = .forward,6    virtual_time: ?VirtualTimeRange = null,7    cursor: ?Cursor = null,8};

1pub const QueryResult = struct {2    matches: []const EvidenceRef,3    inspected: u32,4    next: ?Cursor,5    completion: QueryCompletion,6};

1pub const QueryScope = union(enum) {2    branch,3    before: EvidenceRef,4    after: EvidenceRef,5};

1pub const RootDifference = struct {2    moment_digest: bool = false,3    origin: bool = false,4    fabric_digest: bool = false,5    contract: bool = false,6    entry_frontier: bool = false,7    admission_frontier: bool = false,8    fault_frontier: bool = false,910    pub fn any(self: RootDifference) bool {11        return self.moment_digest or self.origin or self.fabric_digest or12            self.contract or self.entry_frontier or self.admission_frontier or13            self.fault_frontier;14    }15};

1pub const Target = enum(u8) {2    choice = 1,3    root = 2,4    record = 3,5};

1pub const TerminalDirection = enum(u8) {2    either = 1,3    input = 2,4    output = 3,5};

1pub const TerminalPattern = struct {2    direction: TerminalDirection = .either,3    offset: ?u64 = null,4};

1pub const View = union(Target) {2    choice: *const explore.SearchDecision,3    root: *const world.Moment,4    record: *const Evidence,5};

1pub const VirtualTimeRange = struct {2    first: u64,3    last: u64,4};

1pub const RefWire = [80]u8;

1pub fn decodeRef(input: *const RefWire) types.Error!types.EvidenceRef {2    if (!std.mem.eql(u8, input[0..8], &ref_magic)) {3        return error.EvidenceRefBadMagic;4    }5    if (get(u16, input, 8) != version) {6        return error.EvidenceRefVersionUnsupported;7    }8    if (input[11] != flags or !os.abi.wire.allZero(input[14..16])) {9        return error.EvidenceRefFieldInvalid;10    }11    var expected: [digest_bytes]u8 = undefined;12    var hasher = Sha256.init(.{});13    hasher.update(ref_domain);14    hasher.update(&.{0});15    hasher.update(input[0..48]);16    hasher.final(&expected);17    if (!std.mem.eql(u8, &expected, input[48..80])) {18        return error.EvidenceRefFieldInvalid;19    }20    return .{21        .history = .{ .digest = input[16..48].* },22        .target = try enumValue(types.Target, input[10]),23        .index = get(u16, input, 12),24    };25}

1pub fn encodeRef(value: types.EvidenceRef, output: *RefWire) void {2    var encoded: RefWire = @splat(0);3    @memcpy(encoded[0..8], &ref_magic);4    put(u16, &encoded, 8, version);5    encoded[10] = @backingInt(value.target);6    encoded[11] = flags;7    put(u16, &encoded, 12, value.index);8    @memcpy(encoded[16..48], &value.history.digest);9    var hasher = Sha256.init(.{});10    hasher.update(ref_domain);11    hasher.update(&.{0});12    hasher.update(encoded[0..48]);13    var digest: [digest_bytes]u8 = undefined;14    hasher.final(&digest);15    @memcpy(encoded[48..80], &digest);16    output.* = encoded;17}

1pub fn Diff(comptime capacity_value: types.DiffCapacity) type {2    return struct {3        prefix_storage: [capacity.prefix]types.FramePair = undefined,4        left_storage: [capacity.suffix]types.FrameRefs = undefined,5        right_storage: [capacity.suffix]types.FrameRefs = undefined,6        prefix_count: u16 = 0,7        left_count: u16 = 0,8        right_count: u16 = 0,910        const Self = @This();1112        pub const capacity: types.DiffCapacity = capacity_value;1314        pub fn run(15            self: *Self,16            left: anytype,17            right: anytype,18            work: u32,19        ) types.Error!types.DiffResult {20            self.reset();21            _ = try left.identity();22            _ = try right.identity();23            if (!std.meta.eql(left.start, right.start)) return error.RootStartMismatch;24            const common: usize = @min(left.frames().len, right.frames().len);25            var compared: u32 = 0;26            var divergence_index: ?usize = null;27            var divergence_reason: ?types.DivergenceReason = null;28            for (0..common) |index| {29                if (compared == work) {30                    return self.incomplete(compared, null, .work_budget);31                }32                const left_frame = left.frames()[index];33                const right_frame = right.frames()[index];34                compared += 1;35                const choices_equal = std.meta.eql(36                    left_frame.decision,37                    right_frame.decision,38                );39                const evidence_equal = evidenceEqual(40                    try left.frameEvidence(@intCast(index)),41                    try right.frameEvidence(@intCast(index)),42                );43                const roots_equal = std.meta.eql(44                    left_frame.expected,45                    right_frame.expected,46                );47                if (choices_equal and evidence_equal and roots_equal) {48                    if (self.prefix_count == capacity.prefix) {49                        return self.incomplete(compared, null, .prefix_capacity);50                    }51                    self.prefix_storage[self.prefix_count] = .{52                        .left = try left.frameRefs(@intCast(index)),53                        .right = try right.frameRefs(@intCast(index)),54                    };55                    self.prefix_count += 1;56                    continue;57                }58                divergence_index = index;59                divergence_reason = if (!choices_equal)60                    .choice61                else if (!evidence_equal)62                    .evidence63                else64                    .root;65                break;66            }67            if (divergence_index == null and left.frames().len != right.frames().len) {68                divergence_index = common;69                divergence_reason = .length;70            }71            const divergence = if (divergence_index) |index|72                try divergenceValue(left, right, index, divergence_reason.?)73            else74                null;75            if (divergence_index) |index| {76                const suffix_incomplete = try self.collectSuffixes(77                    left,78                    right,79                    index,80                    common,81                    work,82                    &compared,83                );84                if (suffix_incomplete) |reason| {85                    return self.incomplete(compared, divergence, reason);86                }87            }88            if (left.traceState() == .incomplete or right.traceState() == .incomplete) {89                return self.incomplete(compared, divergence, .source_incomplete);90            }91            return self.complete(compared, divergence);92        }9394        fn collectSuffixes(95            self: *Self,96            left: anytype,97            right: anytype,98            first: usize,99            common: usize,100            work: u32,101            compared: *u32,102        ) types.Error!?types.DiffIncompleteReason {103            const end = @max(left.frames().len, right.frames().len);104            for (first..end) |index| {105                const already_inspected = index == first and first < common;106                if (!already_inspected) {107                    if (compared.* == work) return .work_budget;108                    compared.* += 1;109                }110                if (index < left.frames().len) {111                    if (self.left_count == capacity.suffix) return .suffix_capacity;112                    self.left_storage[self.left_count] = try left.frameRefs(@intCast(index));113                    self.left_count += 1;114                }115                if (index < right.frames().len) {116                    if (self.right_count == capacity.suffix) return .suffix_capacity;117                    self.right_storage[self.right_count] = try right.frameRefs(@intCast(index));118                    self.right_count += 1;119                }120            }121            return null;122        }123124        fn complete(125            self: *const Self,126            compared: u32,127            divergence: ?types.Divergence,128        ) types.DiffResult {129            return .{130                .prefix = self.prefix_storage[0..self.prefix_count],131                .left_suffix = self.left_storage[0..self.left_count],132                .right_suffix = self.right_storage[0..self.right_count],133                .divergence = divergence,134                .compared = compared,135                .completion = .complete,136            };137        }138139        fn incomplete(140            self: *const Self,141            compared: u32,142            divergence: ?types.Divergence,143            reason: types.DiffIncompleteReason,144        ) types.DiffResult {145            var result = self.complete(compared, divergence);146            result.completion = .{ .incomplete = reason };147            return result;148        }149150        fn reset(self: *Self) void {151            self.prefix_count = 0;152            self.left_count = 0;153            self.right_count = 0;154        }155    };156}

1pub fn Query(comptime capacity_value: types.QueryCapacity) type {2    if (capacity_value.results == 0) {3        @compileError("query result capacity must be positive");4    }5    return struct {6        storage: [capacity.results]types.EvidenceRef = undefined,7        count: u16 = 0,89        const Self = @This();1011        pub const capacity: types.QueryCapacity = capacity_value;1213        pub fn run(14            self: *Self,15            history: anytype,16            plan: types.QueryPlan,17        ) types.Error!types.QueryResult {18            self.count = 0;19            const identity = try history.identity();20            const total = history.logicalCount();21            const range = try queryRange(history, plan.scope, total);22            if (plan.virtual_time) |window| {23                if (window.first > window.last) return error.InvalidQueryPlan;24            }25            var offset = if (plan.cursor) |cursor| cursor.offset else 0;26            if (plan.cursor) |cursor| {27                if (!std.meta.eql(cursor.history, identity)) {28                    return error.CursorHistoryMismatch;29                }30                if (cursor.first != range.first or31                    cursor.end != range.end or32                    cursor.order != plan.order)33                {34                    return error.CursorPlanMismatch;35                }36            }37            const span = range.end - range.first;38            if (offset > span) return error.EvidenceIndexInvalid;39            var inspected: u32 = 0;40            while (offset < span and inspected < plan.work) {41                const logical_offset = switch (plan.order) {42                    .forward => range.first + offset,43                    .reverse => range.end - 1 - offset,44                };45                const reference = try history.referenceAt(logical_offset);46                const located = try history.lookup(reference);47                inspected += 1;48                offset += 1;49                if (!withinTime(plan.virtual_time, located.virtual_time_tick)) {50                    continue;51                }52                if (!try matches(plan.pattern, located)) continue;53                self.storage[self.count] = reference;54                self.count += 1;55                if (self.count == capacity.results and offset < span) {56                    return self.result(57                        identity,58                        inspected,59                        range,60                        plan.order,61                        offset,62                        .result_capacity,63                    );64                }65            }66            if (offset < span) {67                return self.result(68                    identity,69                    inspected,70                    range,71                    plan.order,72                    offset,73                    .work_budget,74                );75            }76            if (history.traceState() == .incomplete and sourceCanGrow(plan.scope)) {77                return self.result(78                    identity,79                    inspected,80                    range,81                    plan.order,82                    offset,83                    .source_incomplete,84                );85            }86            return .{87                .matches = self.storage[0..self.count],88                .inspected = inspected,89                .next = null,90                .completion = .complete,91            };92        }9394        fn result(95            self: *const Self,96            identity: types.Identity,97            inspected: u32,98            range: Range,99            order: types.QueryOrder,100            offset: u32,101            reason: types.IncompleteReason,102        ) types.QueryResult {103            return .{104                .matches = self.storage[0..self.count],105                .inspected = inspected,106                .next = .{107                    .history = identity,108                    .offset = offset,109                    .first = range.first,110                    .end = range.end,111                    .order = order,112                },113                .completion = .{ .incomplete = reason },114            };115        }116    };117}

1/// Returns a history type that records one run in arrays sized by the capacity,2/// so a caller records one run into it, seals it with `finish`, and then hands3/// it to queries and comparisons or stores its bytes. The record starts with4/// the run's start *moment*, a position in a world's history. Each step of the5/// history (*frame*) holds one alternative taken at a step, the moment reached,6/// and the evidence records the step produced. Each evidence record is one of7/// three things: an encoded ledger entry, an encoded event message from the8/// guest kernel, or an event recorded for checking rules. A frame or evidence9/// capacity of zero stops the build with a compile error. While the history is10/// open, each record attaches to the latest frame, and `appendFrame` rejects a11/// moment that fails to follow the previous one. `finish` checks the whole12/// history, marks it exhausted or incomplete, writes the one fixed-size byte13/// encoding of a sealed history, and records its SHA-256 identity. A failed14/// `finish` leaves the history as it was. After `finish`, every append returns15/// `HistorySealed`, so the sealed history stays fixed. Until `finish`,16/// `identity`, `encode`, `frameEvidence`, `referenceAt`, `frameRefs`, and17/// `lookup` return `HistoryOpen`. Each reference carries the history's18/// identity, a target, and an index, and `lookup` rejects a reference made from19/// any other history. `decode` rejects bytes that fail to encode back to the20/// same bytes. The history holds no pointers.21pub fn History(comptime capacity_value: types.Capacity) type {22    requireCapacity(capacity_value);23    return struct {24        start: world.Moment,25        frames_storage: [capacity.frames]types.Frame = undefined,26        evidence_storage: [capacity.evidence]types.Evidence = undefined,27        frame_count: u16 = 0,28        evidence_count: u16 = 0,29        state: explore.TraceState = .open,30        identity_value: types.Identity = .{ .digest = @splat(0) },3132        const Self = @This();3334        pub const capacity: types.Capacity = capacity_value;35        pub const Error: type = types.Error;36        pub const RefWire: type = canon.RefWire;37        pub const Wire: type = canon.Wire(capacity);3839        pub fn init(start: world.Moment) Error!Self {40            try world.verifyMoment(start, start.origin, start.fabric);41            return .{ .start = start };42        }4344        pub fn decode(input: *const Wire) Error!Self {45            var result: Self = undefined;46            try canon.decode(capacity, input, &result);47            return result;48        }4950        pub fn encode(self: *const Self, output: *Wire) Error!void {51            try self.requirePublished();52            try canon.encode(capacity, self, output);53            const actual = try canon.identity(capacity, output);54            if (!std.meta.eql(actual, self.identity_value)) {55                return error.CanonicalIdentityMismatch;56            }57        }5859        pub fn finish(60            self: *Self,61            completion: explore.TraceCompletion,62            output: *Wire,63        ) Error!types.Identity {64            if (self.state != .open) return error.HistorySealed;65            var candidate = self.*;66            candidate.state = switch (completion) {67                .exhausted => .exhausted,68                .incomplete => .incomplete,69            };70            try candidate.validate();71            try canon.encode(capacity, &candidate, output);72            candidate.identity_value = try canon.identity(capacity, output);73            self.* = candidate;74            return self.identity_value;75        }7677        pub fn appendFrame(78            self: *Self,79            decision: explore.SearchDecision,80            expected: world.Moment,81        ) Error!u16 {82            try self.requireOpen();83            if (self.frame_count == capacity.frames) {84                return error.FrameCapacityExceeded;85            }86            try validateDecision(decision);87            const previous = self.lastMoment();88            if (!momentFollows(previous, expected)) {89                return error.FrameSequenceInvalid;90            }91            const id = self.frame_count;92            self.frames_storage[id] = .{93                .decision = decision,94                .expected = expected,95                .evidence_start = self.evidence_count,96                .evidence_count = 0,97            };98            self.frame_count += 1;99            return id;100        }101102        pub fn appendTransition(103            self: *Self,104            frame: u16,105            wire: fabric.transition.Wire,106        ) Error!void {107            _ = try fabric.transition.inspect(&wire);108            try self.appendEvidence(frame, .{ .transition = wire });109        }110111        pub fn appendMachine(112            self: *Self,113            frame: u16,114            wire: os.abi.MessageWire,115        ) Error!void {116            _ = try os.abi.decodeEvent(&wire);117            try self.appendEvidence(frame, .{ .machine = wire });118        }119120        pub fn appendBatch(121            self: *Self,122            frame: u16,123            batch: *const instance.EventBatch,124        ) Error!void {125            try self.requireLatestFrame(frame);126            if (batch.count > batch.storage.len) {127                return error.EvidenceSequenceInvalid;128            }129            const remaining = capacity.evidence - self.evidence_count;130            if (batch.count > remaining) return error.EvidenceCapacityExceeded;131            for (batch.frames()) |wire| try self.appendMachine(frame, wire);132        }133134        pub fn appendSemantic(135            self: *Self,136            frame: u16,137            event: explore.Event,138        ) Error!void {139            try validateSemantic(event);140            try self.appendEvidence(frame, .{ .semantic = event });141        }142143        pub fn frames(self: *const Self) []const types.Frame {144            std.debug.assert(self.frame_count <= capacity.frames);145            return self.frames_storage[0..self.frame_count];146        }147148        pub fn evidence(self: *const Self) []const types.Evidence {149            std.debug.assert(self.evidence_count <= capacity.evidence);150            return self.evidence_storage[0..self.evidence_count];151        }152153        pub fn frameEvidence(154            self: *const Self,155            frame: u16,156        ) Error![]const types.Evidence {157            try self.requirePublished();158            if (frame >= self.frame_count) return error.EvidenceFrameInvalid;159            const retained = self.frames_storage[frame];160            const end = retained.evidence_start + retained.evidence_count;161            return self.evidence_storage[retained.evidence_start..end];162        }163164        pub fn traceState(self: *const Self) explore.TraceState {165            return self.state;166        }167168        pub fn identity(self: *const Self) Error!types.Identity {169            try self.requirePublished();170            return self.identity_value;171        }172173        pub fn logicalCount(self: *const Self) u32 {174            const frames_count: u32 = self.frame_count;175            const evidence_count_value: u32 = self.evidence_count;176            return 1 + frames_count * 2 + evidence_count_value;177        }178179        pub fn referenceAt(180            self: *const Self,181            offset: u32,182        ) Error!types.EvidenceRef {183            try self.requirePublished();184            if (offset >= self.logicalCount()) return error.EvidenceIndexInvalid;185            if (offset == 0) return self.makeRef(.root, 0);186            var cursor: u32 = 1;187            for (self.frames(), 0..) |frame, frame_index| {188                if (cursor == offset) return self.makeRef(.choice, @intCast(frame_index));189                cursor += 1;190                for (0..frame.evidence_count) |record_offset| {191                    if (cursor == offset) {192                        const index = frame.evidence_start + @as(u16, @intCast(record_offset));193                        return self.makeRef(.record, index);194                    }195                    cursor += 1;196                }197                if (cursor == offset) return self.makeRef(.root, @intCast(frame_index + 1));198                cursor += 1;199            }200            unreachable;201        }202203        pub fn frameRefs(self: *const Self, frame: u16) Error!types.FrameRefs {204            try self.requirePublished();205            if (frame >= self.frame_count) return error.EvidenceFrameInvalid;206            return .{207                .choice = self.makeRef(.choice, frame),208                .evidence = .{209                    .first = if (self.frames_storage[frame].evidence_count == 0)210                        null211                    else212                        self.makeRef(213                            .record,214                            self.frames_storage[frame].evidence_start,215                        ),216                    .count = self.frames_storage[frame].evidence_count,217                },218                .root = self.makeRef(.root, frame + 1),219            };220        }221222        pub fn logicalOffset(223            self: *const Self,224            reference: types.EvidenceRef,225        ) Error!u32 {226            _ = try self.lookup(reference);227            if (reference.target == .root and reference.index == 0) return 0;228            var offset: u32 = 1;229            for (self.frames(), 0..) |frame, frame_index| {230                if (reference.target == .choice and reference.index == frame_index) {231                    return offset;232                }233                offset += 1;234                if (reference.target == .record and235                    reference.index >= frame.evidence_start and236                    reference.index < frame.evidence_start + frame.evidence_count)237                {238                    return offset + reference.index - frame.evidence_start;239                }240                offset += frame.evidence_count;241                if (reference.target == .root and reference.index == frame_index + 1) {242                    return offset;243                }244                offset += 1;245            }246            unreachable;247        }248249        pub fn lookup(250            self: *const Self,251            reference: types.EvidenceRef,252        ) Error!types.Located {253            try self.requirePublished();254            if (!std.meta.eql(reference.history, self.identity_value)) {255                return error.EvidenceHistoryMismatch;256            }257            return switch (reference.target) {258                .choice => self.lookupChoice(reference),259                .root => self.lookupRoot(reference),260                .record => self.lookupRecord(reference),261            };262        }263264        pub fn validate(self: *const Self) Error!void {265            if (self.frame_count > capacity.frames or266                self.evidence_count > capacity.evidence)267            {268                return error.EvidenceWireCapacityMismatch;269            }270            try world.verifyMoment(self.start, self.start.origin, self.start.fabric);271            var previous = self.start;272            var evidence_cursor: u16 = 0;273            var semantic_previous: ?explore.Event = null;274            for (self.frames()) |frame| {275                try validateDecision(frame.decision);276                if (!momentFollows(previous, frame.expected)) return error.FrameSequenceInvalid;277                if (frame.evidence_start != evidence_cursor or278                    frame.evidence_count > self.evidence_count - evidence_cursor)279                {280                    return error.EvidenceSequenceInvalid;281                }282                try self.validateFrameEvidence(283                    frame,284                    previous.fabric,285                    &semantic_previous,286                );287                evidence_cursor += frame.evidence_count;288                previous = frame.expected;289            }290            if (evidence_cursor != self.evidence_count) {291                return error.EvidenceSequenceInvalid;292            }293        }294295        fn appendEvidence(296            self: *Self,297            frame: u16,298            value: types.Evidence,299        ) Error!void {300            try self.requireLatestFrame(frame);301            if (self.evidence_count == capacity.evidence) {302                return error.EvidenceCapacityExceeded;303            }304            self.evidence_storage[self.evidence_count] = value;305            self.evidence_count += 1;306            self.frames_storage[frame].evidence_count += 1;307        }308309        fn validateFrameEvidence(310            self: *const Self,311            frame: types.Frame,312            previous_root: fabric.Root,313            semantic_previous: *?explore.Event,314        ) Error!void {315            var transition_root = previous_root;316            var transition_seen = false;317            const end = frame.evidence_start + frame.evidence_count;318            for (self.evidence_storage[frame.evidence_start..end]) |record| {319                switch (record) {320                    .transition => |wire| {321                        const inspected = try fabric.transition.inspect(&wire);322                        try validateTransition(transition_root, inspected);323                        transition_root = inspected.result;324                        transition_seen = true;325                    },326                    .machine => |wire| _ = try os.abi.decodeEvent(&wire),327                    .semantic => |event| {328                        try validateSemantic(event);329                        if (semantic_previous.*) |prior| {330                            if (event.sequence <= prior.sequence or331                                event.virtual_time_tick < prior.virtual_time_tick)332                            {333                                return error.EvidenceSequenceInvalid;334                            }335                        }336                        semantic_previous.* = event;337                    },338                }339            }340            if (transition_seen and !std.meta.eql(transition_root, frame.expected.fabric)) {341                return error.EvidenceSequenceInvalid;342            }343        }344345        fn lastMoment(self: *const Self) world.Moment {346            return if (self.frame_count == 0)347                self.start348            else349                self.frames_storage[self.frame_count - 1].expected;350        }351352        fn lookupChoice(353            self: *const Self,354            reference: types.EvidenceRef,355        ) Error!types.Located {356            if (reference.index >= self.frame_count) return error.EvidenceIndexInvalid;357            return .{358                .reference = reference,359                .frame = reference.index,360                .virtual_time_tick = self.frames_storage[reference.index]361                    .decision.site.virtual_time_tick,362                .view = .{ .choice = &self.frames_storage[reference.index].decision },363            };364        }365366        fn lookupRoot(367            self: *const Self,368            reference: types.EvidenceRef,369        ) Error!types.Located {370            if (reference.index > self.frame_count) return error.EvidenceIndexInvalid;371            if (reference.index == 0) return .{372                .reference = reference,373                .frame = null,374                .virtual_time_tick = null,375                .view = .{ .root = &self.start },376            };377            return .{378                .reference = reference,379                .frame = reference.index - 1,380                .virtual_time_tick = self.frames_storage[reference.index - 1]381                    .decision.site.virtual_time_tick,382                .view = .{ .root = &self.frames_storage[reference.index - 1].expected },383            };384        }385386        fn lookupRecord(387            self: *const Self,388            reference: types.EvidenceRef,389        ) Error!types.Located {390            if (reference.index >= self.evidence_count) return error.EvidenceIndexInvalid;391            const frame = self.frameForRecord(reference.index);392            return .{393                .reference = reference,394                .frame = frame,395                .virtual_time_tick = (try recordTick(396                    self.evidence_storage[reference.index],397                )) orelse self.frames_storage[frame].decision.site.virtual_time_tick,398                .view = .{ .record = &self.evidence_storage[reference.index] },399            };400        }401402        fn frameForRecord(self: *const Self, record: u16) u16 {403            for (self.frames(), 0..) |frame, index| {404                const end = frame.evidence_start + frame.evidence_count;405                if (record >= frame.evidence_start and record < end) return @intCast(index);406            }407            unreachable;408        }409410        fn makeRef(self: *const Self, target: types.Target, index: u16) types.EvidenceRef {411            return .{ .history = self.identity_value, .target = target, .index = index };412        }413414        fn requireLatestFrame(self: *const Self, frame: u16) Error!void {415            try self.requireOpen();416            if (self.frame_count == 0 or frame != self.frame_count - 1) {417                return error.EvidenceFrameInvalid;418            }419        }420421        fn requireOpen(self: *const Self) Error!void {422            if (self.state != .open) return error.HistorySealed;423        }424425        fn requirePublished(self: *const Self) Error!void {426            if (self.state == .open) return error.HistoryOpen;427        }428    };429}

1pub const Error = world.MomentError ||2    fabric.transition.Error ||3    os.abi.message.Error ||4    QueryError;

1//! Once a run fails, the next questions are which choice, message, or fault led2//! there, and where the failing run first parted from one that passed. This3//! namespace records one run in order and answers such questions within bounds4//! fixed in advance.5//!6//! The record holds each step's choice, the position the run reached, and what7//! the step produced: entries added to the run's ordered log of inputs and8//! faults, event messages from the guest kernel, and the events recorded for9//! checking rules. A caller asks for the entries that match one question: a10//! kind of entry, a kind of choice, a rule event, a packet, a fault, an outside11//! effect, or terminal input and output. A caller compares two runs from the12//! same start and learns where they first differ.13//!14//! An answer has to point at entries in a way that still names the same entry15//! after the record is stored and read back in another process, and that cannot16//! be resolved against a different record. Answers and comparisons have to fit17//! fixed storage and bounded work, so a scan cut short has to say so and be18//! resumable. A question asked of a run that was itself cut short cannot claim19//! a complete answer. A record has to agree with itself: log entries follow one20//! another from each position to the next, and rule events move forward in21//! number and in time.22//!23//! Each run becomes an append-only record, a *causal history*: the start24//! position, then for each step the choice, the position reached, and the25//! entries that step produced. `finish` checks the record, marks it exhausted26//! or incomplete, writes its one canonical byte encoding, and records its27//! SHA-256 identity, and after that the record changes no more.28//!29//! Queries (`Query`) and comparisons answer with references into the record,30//! each an *evidence reference* made of the record's identity, a target (a31//! choice, a reached position, or an entry), and an index, so an answer holds32//! no copies of the entries. A reference also travels as an 80-byte encoding33//! with its own SHA-256 check. A query reads the record in one fixed order: the34//! start, then for each step its choice, its entries, and the position reached.35//! A query scans forward or backward, over the whole record or before or after36//! a reference, and optionally only inside a window of simulated time. A query37//! stops when its result storage fills or its work budget runs out, returns a38//! cursor to resume from, and marks the answer incomplete with the reason. A39//! query over an incomplete record that could still grow past the scanned range40//! reports its answer incomplete as well.41//!42//! A comparison (`Diff`) walks two sealed records with the same start step by43//! step and collects the common prefix of steps equal in choice, entries, and44//! reached position. It reports the first step that differs (the *first45//! divergence*), with the reason and which fields of the two positions differ.46//! A comparison stays inside its prefix capacity, its suffix capacity, and a47//! work budget, and it marks the result incomplete when any of them runs out or48//! when either record is incomplete. Records, queries, and comparisons hold no49//! pointers.50//!51//! - *moment*: a position in one world's history, pairing the world root the52//!   world grew from with the ledger root it has reached since.53//! - *frame*: one step of a causal history: its decision, the moment it54//!   reached, and the range of its evidence records.55//! - *transition*: one ledger entry together with the ledger root it produces.56//! - *semantic event*: one numbered, timestamped entry in the event list a run57//!   is checked over.58//! - *canonical wire*: the one fixed-size byte encoding of a sealed history for59//!   a given capacity, ending in its SHA-256 identity. Decoding rejects any60//!   input that does not encode back to the same bytes.6162const canon = @import("canon.zig");63const engine = @import("engine.zig");64const history_owner = @import("history.zig");65const types = @import("types.zig");6667pub const Capacity = types.Capacity;68pub const ChoicePattern = types.ChoicePattern;69pub const Cursor = types.Cursor;70pub const Diff = engine.Diff;71pub const DiffCapacity = types.DiffCapacity;72pub const DiffCompletion = types.DiffCompletion;73pub const DiffIncompleteReason = types.DiffIncompleteReason;74pub const DiffResult = types.DiffResult;75pub const Divergence = types.Divergence;76pub const DivergenceReason = types.DivergenceReason;77pub const EffectPattern = types.EffectPattern;78pub const EffectPhase = types.EffectPhase;79pub const Error = types.Error;80pub const Evidence = types.Evidence;81pub const EvidenceRange = types.EvidenceRange;82pub const EvidenceRef = types.EvidenceRef;83pub const FaultPattern = types.FaultPattern;84pub const Frame = types.Frame;85pub const FramePair = types.FramePair;86pub const FrameRefs = types.FrameRefs;87pub const History = history_owner.History;88pub const Identity = types.Identity;89pub const IncompleteReason = types.IncompleteReason;90pub const Kind = types.Kind;91pub const Located = types.Located;92pub const PacketAction = types.PacketAction;93pub const PacketPattern = types.PacketPattern;94pub const Pattern = types.Pattern;95pub const Query = engine.Query;96pub const QueryCapacity = types.QueryCapacity;97pub const QueryCompletion = types.QueryCompletion;98pub const QueryPlan = types.QueryPlan;99pub const QueryOrder = types.QueryOrder;100pub const QueryResult = types.QueryResult;101pub const QueryScope = types.QueryScope;102pub const RefWire = canon.RefWire;103pub const RootDifference = types.RootDifference;104pub const Target = types.Target;105pub const TerminalDirection = types.TerminalDirection;106pub const TerminalPattern = types.TerminalPattern;107pub const View = types.View;108pub const VirtualTimeRange = types.VirtualTimeRange;109pub const decodeRef = canon.decodeRef;110pub const encodeRef = canon.encodeRef;

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