openscript 0.4.0__py3-none-any.whl

openscript/machine.py

@@ -0,0 +1,499 @@
+"""The instruction loop: forty-one arms and nothing clever in any of them.
+
+Section 4 is deliberately small and deliberately dull. There is one way to do
+each thing, no instruction is a shorthand for two others, and a new one cannot be
+added without a major format bump. So this is a loop over a list, with a table of
+handlers, and the table is data: a name in a compiled program never becomes a
+function here, and nothing on this path builds anything out of text.
+
+**Verification is what lets this be plain.** A verified program cannot underflow
+the stack, cannot jump out of bounds, cannot address a slot that does not exist
+and cannot loop without charging the budget (section 3.5), so none of that is
+tested again per instruction. What is tested per instruction is the one thing
+verification cannot decide: the tags of the values, which is where absence lives.
+
+**Absence has a rule in every arm and the rule is the page's.** It propagates
+through arithmetic and ordering comparison, is total under equality, is three
+valued under the logical operators, and is false at a branch. Those five rules
+are ``values.py``'s, and an engine that special cased absence anywhere else would
+have a bug rather than an optimisation.
+"""
+
+import math
+from typing import Any, Callable, Dict, List, Optional, Sequence
+
+from .budget import Budget
+from .contracts import CallContext, Library
+from .diagnostics import NO_POSITION, Position, raise_at
+from .memory import Cells, Channels, Frame, Register, States, read_history
+from .program import LoadedProgram
+from .values import (
+    ABSENT,
+    ArrayValue,
+    conjunction,
+    disjunction,
+    equal,
+    finite,
+    is_number,
+    is_whole,
+    negation,
+    ordered,
+    stored,
+    truthy,
+)
+
+
+class PendingEffect:
+    """One library call that reaches the outside world, held until step 9.
+
+    A function with an effect does not perform it when it executes: it leaves a
+    record here and pushes absent. The list is discarded at step 3 of every
+    execution and applied at step 9 only when the bar is decided, which is what
+    makes a condition that was true halfway through a bar and false when it
+    closed place no order at all.
+    """
+
+    __slots__ = ("fn", "name", "effect", "arguments", "position")
+
+    def __init__(
+        self, fn: int, name: str, effect: str, arguments: List[Any], position: Position
+    ) -> None:
+        self.fn = fn
+        self.name = name
+        self.effect = effect
+        self.arguments = arguments
+        self.position = position
+
+
+class Machine:
+    """One program, its memory, and the loop that walks its instructions."""
+
+    def __init__(
+        self,
+        program: LoadedProgram,
+        cells: Cells,
+        states: States,
+        registers: List[Register],
+        channels: Channels,
+        budget: Budget,
+        library: Library,
+    ) -> None:
+        self.program = program
+        self.cells = cells
+        self.states = states
+        self.registers = registers
+        self.channels = channels
+        self.budget = budget
+        self.library = library
+        self.pending: List[PendingEffect] = []
+        self.context = CallContext()
+        self.bar_index = 0
+        self._frames: List[Frame] = []
+        self._loop_line: Optional[int] = None
+        self._answer: Any = ABSENT
+        self._running = False
+        self._arms: Dict[str, Callable[[Frame, Sequence[Any]], None]] = {
+            "CONST": self._const,
+            "DUP": self._dup,
+            "POP": self._pop_top,
+            "LOAD": self._load,
+            "STORE": self._store,
+            "CELL_INIT": self._cell_init,
+            "LOADC": self._load_cell,
+            "STOREC": self._store_cell,
+            "SLOAD": self._series_load,
+            "SSTORE": self._series_store,
+            "HIST": self._history,
+            "HISTP": self._history_parameter,
+            "ADD": self._add,
+            "SUB": self._subtract,
+            "MUL": self._multiply,
+            "DIV": self._divide,
+            "MOD": self._modulo,
+            "NEG": self._negate,
+            "LT": self._less,
+            "LE": self._less_equal,
+            "GT": self._greater,
+            "GE": self._greater_equal,
+            "EQ": self._equals,
+            "NE": self._differs,
+            "NOT": self._not,
+            "AND": self._and,
+            "OR": self._or,
+            "AND_SHORT": self._and_short,
+            "OR_SHORT": self._or_short,
+            "JUMP": self._jump,
+            "JUMP_FALSE": self._jump_false,
+            "TICK": self._tick,
+            "FOR_INIT": self._for_init,
+            "FOR_NEXT": self._for_next,
+            "ARRAY": self._array,
+            "ELEM": self._element,
+            "CALL_LIB": self._call_library,
+            "CALL_FN": self._call_function,
+            "RET": self._return,
+            "EMIT": self._emit,
+            "HALT": self._halt,
+        }
+
+    # -- the loop ---------------------------------------------------------
+
+    def begin(self, bar_index: int, context: CallContext) -> None:
+        """Step 3's share: a fresh frame 0 with every slot absent, and the counters.
+
+        The frame exists before step 6 rather than at it, because step 5 writes
+        each input's effective value into a slot of this frame and the two steps
+        are in that order.
+        """
+        self.bar_index = bar_index
+        self.context = context
+        self.pending = []
+        self._loop_line = None
+        self.budget.begin()
+        top = self.program.top
+        self._frames = [Frame(top.code, top.slots, positions=top.positions)]
+
+    def write_slot(self, slot: int, value: Any) -> None:
+        """Step 5: one input's effective value, into frame 0."""
+        self._frames[0].slots[slot] = stored(value)
+
+    def execute(self) -> Any:
+        """Step 6: run the top-level list from instruction 0 until ``HALT``."""
+        return self._walk()
+
+    def _walk(self) -> Any:
+        self._answer = ABSENT
+        self._running = True
+        while self._running:
+            current = self._frames[-1]
+            if self.budget.step():
+                self.budget.spent(self.here(), self._loop_line)
+            instruction = current.code[current.pc]
+            current.pc += 1
+            self._arms[instruction[0]](current, instruction)
+        return self._answer
+
+    def here(self) -> Position:
+        """Where the instruction that is executing came from in the source."""
+        if not self._frames:
+            return NO_POSITION
+        frame = self._frames[-1]
+        at = frame.pc - 1
+        positions = frame.positions
+        if positions is None or at < 0 or at >= len(positions):
+            return NO_POSITION
+        return positions[at]
+
+    # -- constants and stack ----------------------------------------------
+
+    def _const(self, frame: Frame, instruction: Sequence[Any]) -> None:
+        frame.stack.append(self.program.consts[instruction[1]])
+
+    def _dup(self, frame: Frame, instruction: Sequence[Any]) -> None:
+        frame.stack.append(frame.stack[-1])
+
+    def _pop_top(self, frame: Frame, instruction: Sequence[Any]) -> None:
+        frame.stack.pop()
+
+    # -- slots -------------------------------------------------------------
+
+    def _load(self, frame: Frame, instruction: Sequence[Any]) -> None:
+        frame.stack.append(frame.slots[instruction[1]])
+
+    def _store(self, frame: Frame, instruction: Sequence[Any]) -> None:
+        frame.slots[instruction[1]] = stored(frame.stack.pop())
+
+    # -- cells --------------------------------------------------------------
+
+    def _cell_init(self, frame: Frame, instruction: Sequence[Any]) -> None:
+        cell = frame.cell_base + instruction[1]
+        if self.cells.initialised(cell):
+            frame.pc = instruction[2]
+            return
+        # Marked before the initialiser runs, not after: the two differ only if
+        # the initialiser could reach this instruction again, which needs
+        # recursion, which is an error.
+        self.cells.mark(cell)
+
+    def _load_cell(self, frame: Frame, instruction: Sequence[Any]) -> None:
+        frame.stack.append(self.cells.read(frame.cell_base + instruction[1]))
+
+    def _store_cell(self, frame: Frame, instruction: Sequence[Any]) -> None:
+        self.cells.write(frame.cell_base + instruction[1], frame.stack.pop())
+
+    # -- series registers ---------------------------------------------------
+
+    def _series_load(self, frame: Frame, instruction: Sequence[Any]) -> None:
+        frame.stack.append(self.registers[instruction[1]].current)
+
+    def _series_store(self, frame: Frame, instruction: Sequence[Any]) -> None:
+        self.registers[instruction[1]].current = stored(frame.stack.pop())
+
+    def _read_back(self, frame: Frame, register: int) -> None:
+        back = frame.stack.pop()
+        frame.stack.append(
+            read_history(
+                self.registers[register],
+                back,
+                self.bar_index,
+                self.program.retained,
+                self.here(),
+            )
+        )
+
+    def _history(self, frame: Frame, instruction: Sequence[Any]) -> None:
+        self._read_back(frame, instruction[1])
+
+    def _history_parameter(self, frame: Frame, instruction: Sequence[Any]) -> None:
+        # A parameter whose call site bound -1 cannot be reached by a HISTP: the
+        # compiler binds a register only for a parameter whose history the body
+        # reads, and a HISTP against -1 is a corrupt program the verifier caught.
+        self._read_back(frame, frame.bindings[instruction[1]])
+
+    # -- arithmetic ---------------------------------------------------------
+
+    def _two(self, frame: Frame):
+        right = frame.stack.pop()
+        return frame.stack.pop(), right
+
+    def _add(self, frame: Frame, instruction: Sequence[Any]) -> None:
+        left, right = self._two(frame)
+        if left is ABSENT or right is ABSENT:
+            frame.stack.append(ABSENT)
+            return
+        if is_number(left) and is_number(right):
+            frame.stack.append(finite(left + right))
+            return
+        if isinstance(left, str) and isinstance(right, str):
+            # The one operator that grows a string, and so the one that meets
+            # the ceiling: a log appended to on every bar is what OS5008 is for.
+            frame.stack.append(self.budget.text(self.here(), left + right))
+            return
+        # Any other combination is a program the checker should have rejected,
+        # and an engine that invented a conversion here would become the only
+        # engine that runs that script.
+        frame.stack.append(ABSENT)
+
+    def _numeric(self, frame: Frame, of: Callable[[float, float], Any]) -> None:
+        left, right = self._two(frame)
+        if not is_number(left) or not is_number(right):
+            frame.stack.append(ABSENT)
+            return
+        frame.stack.append(of(float(left), float(right)))
+
+    def _subtract(self, frame: Frame, instruction: Sequence[Any]) -> None:
+        self._numeric(frame, lambda a, b: finite(a - b))
+
+    def _multiply(self, frame: Frame, instruction: Sequence[Any]) -> None:
+        self._numeric(frame, lambda a, b: finite(a * b))
+
+    def _divide(self, frame: Frame, instruction: Sequence[Any]) -> None:
+        # Absent when the divisor is zero, zero divided by zero included: the
+        # language has no infinity and no not-a-number to hand back.
+        self._numeric(frame, lambda a, b: ABSENT if b == 0 else finite(a / b))
+
+    def _modulo(self, frame: Frame, instruction: Sequence[Any]) -> None:
+        # The remainder of truncated division, so the sign follows the left
+        # operand rather than the divisor.
+        self._numeric(frame, lambda a, b: ABSENT if b == 0 else finite(math.fmod(a, b)))
+
+    def _negate(self, frame: Frame, instruction: Sequence[Any]) -> None:
+        value = frame.stack.pop()
+        frame.stack.append(finite(-float(value)) if is_number(value) else ABSENT)
+
+    # -- comparison ---------------------------------------------------------
+
+    def _order(self, frame: Frame, wanted: Callable[[float], bool]) -> None:
+        left, right = self._two(frame)
+        found = ordered(left, right)
+        frame.stack.append(ABSENT if found is ABSENT else wanted(found))
+
+    def _less(self, frame: Frame, instruction: Sequence[Any]) -> None:
+        self._order(frame, lambda found: found < 0)
+
+    def _less_equal(self, frame: Frame, instruction: Sequence[Any]) -> None:
+        self._order(frame, lambda found: found <= 0)
+
+    def _greater(self, frame: Frame, instruction: Sequence[Any]) -> None:
+        self._order(frame, lambda found: found > 0)
+
+    def _greater_equal(self, frame: Frame, instruction: Sequence[Any]) -> None:
+        self._order(frame, lambda found: found >= 0)
+
+    def _equals(self, frame: Frame, instruction: Sequence[Any]) -> None:
+        left, right = self._two(frame)
+        frame.stack.append(equal(left, right))
+
+    def _differs(self, frame: Frame, instruction: Sequence[Any]) -> None:
+        left, right = self._two(frame)
+        frame.stack.append(not equal(left, right))
+
+    # -- logic ---------------------------------------------------------------
+
+    def _not(self, frame: Frame, instruction: Sequence[Any]) -> None:
+        frame.stack.append(negation(frame.stack.pop()))
+
+    def _and(self, frame: Frame, instruction: Sequence[Any]) -> None:
+        left, right = self._two(frame)
+        frame.stack.append(conjunction(left, right))
+
+    def _or(self, frame: Frame, instruction: Sequence[Any]) -> None:
+        left, right = self._two(frame)
+        frame.stack.append(disjunction(left, right))
+
+    def _and_short(self, frame: Frame, instruction: Sequence[Any]) -> None:
+        # The value that decides the answer by itself stays on the stack as the
+        # answer. Absence decides neither operator, so it does not short circuit.
+        if frame.stack[-1] is False:
+            frame.pc = instruction[1]
+
+    def _or_short(self, frame: Frame, instruction: Sequence[Any]) -> None:
+        if frame.stack[-1] is True:
+            frame.pc = instruction[1]
+
+    # -- branching and loops --------------------------------------------------
+
+    def _jump(self, frame: Frame, instruction: Sequence[Any]) -> None:
+        frame.pc = instruction[1]
+
+    def _jump_false(self, frame: Frame, instruction: Sequence[Any]) -> None:
+        if not truthy(frame.stack.pop()):
+            frame.pc = instruction[1]
+
+    def _tick(self, frame: Frame, instruction: Sequence[Any]) -> None:
+        line = self.program.loop_lines[instruction[1]]
+        self._loop_line = line
+        self.budget.tick(self.here(), line)
+
+    def _for_init(self, frame: Frame, instruction: Sequence[Any]) -> None:
+        step = frame.stack.pop()
+        limit = frame.stack.pop()
+        start = frame.stack.pop()
+        bounds = ((start, "start"), (limit, "limit"), (step, "step"))
+        for value, bound in bounds:
+            if value is ABSENT:
+                # An absent bound means the number of iterations is unknown, and
+                # running zero times would hide that.
+                raise_at("OS4013", self.here(), bound=bound)
+        for value, _bound in bounds:
+            if not is_number(value):
+                raise_at("OS4001", self.here(), index=str(value))
+        if step == 0:
+            raise_at(
+                "OS3004",
+                self.here(),
+                name="this loop",
+                argument="step",
+                range="anything but zero",
+                found=0,
+            )
+        frame.slots[instruction[2]] = start
+        frame.slots[instruction[3]] = limit
+        frame.slots[instruction[4]] = step
+        # A descending range with a positive step runs zero times and is never
+        # silently reversed.
+        if (start > limit) if step > 0 else (start < limit):
+            frame.pc = instruction[5]
+
+    def _for_next(self, frame: Frame, instruction: Sequence[Any]) -> None:
+        limit = frame.slots[instruction[3]]
+        step = frame.slots[instruction[4]]
+        moved = finite(float(frame.slots[instruction[2]]) + float(step))
+        frame.slots[instruction[2]] = moved
+        if moved is ABSENT:
+            return
+        if (moved <= limit) if step > 0 else (moved >= limit):
+            frame.pc = instruction[5]
+
+    # -- arrays ----------------------------------------------------------------
+
+    def _array(self, frame: Frame, instruction: Sequence[Any]) -> None:
+        count = instruction[1]
+        held = frame.stack[len(frame.stack) - count :] if count else []
+        del frame.stack[len(frame.stack) - count :]
+        # A new array every time it executes, which is why an array literal is
+        # not a constant pool entry.
+        frame.stack.append(ArrayValue(list(held)))
+
+    def _element(self, frame: Frame, instruction: Sequence[Any]) -> None:
+        index = frame.stack.pop()
+        array = frame.stack.pop()
+        size = len(array.elements) if isinstance(array, ArrayValue) else 0
+        usable = (
+            isinstance(array, ArrayValue)
+            and is_whole(index)
+            and 0 <= index < size
+        )
+        if not usable:
+            # The opposite of a history read past the start of the dataset, and
+            # the difference is the point: an array has an extent the script
+            # chose, so an index outside it is a mistake.
+            raise_at(
+                "OS4004",
+                self.here(),
+                index="none" if index is ABSENT else str(index),
+                name="the array",
+                size=size,
+            )
+        frame.stack.append(array.elements[int(index)])
+
+    # -- calls -------------------------------------------------------------------
+
+    def _call_library(self, frame: Frame, instruction: Sequence[Any]) -> None:
+        which, count, state = instruction[1], instruction[2], instruction[3]
+        arguments = frame.stack[len(frame.stack) - count :] if count else []
+        del frame.stack[len(frame.stack) - count :]
+        entry = self.program.entries[which]
+        if entry.effect != "none":
+            self.pending.append(
+                PendingEffect(which, entry.name, entry.effect, list(arguments), self.here())
+            )
+            frame.stack.append(ABSENT)
+            return
+        region = None if state < 0 else self.states.region(frame.state_base + state)
+        # The string ceiling, both halves: the length a call can be asked for
+        # before a character of it exists, and the string it did build. A call of
+        # that passes a string through, or answers a fact the host stated, hands
+        # back a string it did not make, and refusing that would refuse the host
+        # its own symbol for being long.
+        self.budget.measured(self.here(), self.library.length_of(entry.name, arguments))
+        answer = self.library.call(entry.name, list(arguments), region, self.context)
+        if isinstance(answer, str) and self.library.builds_a_string(entry.name):
+            self.budget.text(self.here(), answer)
+        frame.stack.append(stored(answer))
+
+    def _call_function(self, frame: Frame, instruction: Sequence[Any]) -> None:
+        site = self.program.call_sites[instruction[1]]
+        body = self.program.functions[site["fn"]]
+        count = site["argc"]
+        arguments = frame.stack[len(frame.stack) - count :] if count else []
+        del frame.stack[len(frame.stack) - count :]
+        called = Frame(
+            body.code,
+            body.slots,
+            cell_base=site["cellBase"],
+            state_base=site["stateBase"],
+            bindings=site["series"],
+            positions=body.positions,
+        )
+        for at, value in enumerate(arguments):
+            called.slots[at] = value
+        self._frames.append(called)
+
+    def _return(self, frame: Frame, instruction: Sequence[Any]) -> None:
+        value = frame.stack.pop()
+        self._frames.pop()
+        if not self._frames:
+            self._answer = value
+            self._running = False
+            return
+        self._frames[-1].stack.append(value)
+
+    # -- output and termination -----------------------------------------------------
+
+    def _emit(self, frame: Frame, instruction: Sequence[Any]) -> None:
+        self.channels.write(instruction[1], frame.stack.pop())
+
+    def _halt(self, frame: Frame, instruction: Sequence[Any]) -> None:
+        self._answer = ABSENT
+        self._running = False

openscript/memory.py

@@ -0,0 +1,204 @@
+"""The regions section 3.2 tabulates, each with the lifetime that table gives it.
+
+Three lifetimes and one table. Slots, the operand stack and the channels last one
+execution of a bar; cells, library state regions, register histories and the
+object heap last across bars; and the third and fourth columns of that table,
+what rolls back and what a checkpoint holds, are section 6 and are ``run.py``'s.
+
+**A register is the only thing with history.** ``HIST`` and ``HISTP`` are the
+only way to read one, and the resolution order below is the page's own numbered
+list, in that order, because case 3 and case 4 are different on purpose: in case
+3 the value never existed, and in case 4 it existed and the engine threw it away.
+Returning absence for both would hide a real bug behind a plausible gap.
+
+**Trimming moves the storage and not the bar numbering.** A register that has
+dropped its oldest entries still answers about bar 300 when asked for bar 300, so
+the count of what was dropped is kept beside the entries rather than the caller
+being asked to subtract.
+"""
+
+from typing import Any, Dict, List, Optional
+
+from .canonical import canonical_number
+from .diagnostics import Position, raise_at
+from .values import ABSENT, is_number, is_whole, stored
+
+
+class Register:
+    """One series register: a history of one value per bar, plus this bar's cell."""
+
+    __slots__ = ("history", "current", "dropped")
+
+    def __init__(self) -> None:
+        self.history: List[Any] = []
+        self.current: Any = ABSENT
+        #: How many of the oldest entries trimming has thrown away.
+        self.dropped: int = 0
+
+    @property
+    def length(self) -> int:
+        """The number of bars this register has entries for, trimmed or not."""
+        return self.dropped + len(self.history)
+
+    def truncate(self, length: int) -> None:
+        """Step 2: discard any entry a previous execution of this bar wrote."""
+        keep = max(0, length - self.dropped)
+        if keep < len(self.history):
+            del self.history[keep:]
+
+    def close(self) -> None:
+        """Step 7: the current cell becomes this bar's entry."""
+        self.history.append(self.current)
+
+    def at(self, bar: int) -> Any:
+        """The value this register held on that bar, or absence where it is gone."""
+        where = bar - self.dropped
+        if where < 0 or where >= len(self.history):
+            return ABSENT
+        return self.history[where]
+
+    def trim(self, depth: int) -> None:
+        """Step 10: drop entries older than the retained depth.
+
+        ``depth`` entries plus the bar just closed, because a read at the depth
+        itself is the last one section 4.4's case 4 does not refuse.
+        """
+        keep = depth + 1
+        if len(self.history) <= keep:
+            return
+        self.dropped += len(self.history) - keep
+        del self.history[: len(self.history) - keep]
+
+
+def read_history(
+    register: Register,
+    offset: Any,
+    bar_index: int,
+    retained: Optional[int],
+    position: Position,
+) -> Any:
+    """``HIST``, resolved in the order section 4.4 gives and no other."""
+    if offset is ABSENT:
+        return ABSENT
+    if not is_whole(offset) or offset < 0:
+        raise_at("OS4001", position, index=_written(offset))
+    back = int(offset)
+    if back > bar_index:
+        return ABSENT
+    if retained is not None and back > retained:
+        raise_at("OS4002", position, index=back, depth=retained, suggested=back)
+    # Offset zero is the bar being executed, which is the current cell and not a
+    # history entry: the entry for this bar is appended at step 7, after the
+    # code that is asking has finished running.
+    if back == 0:
+        return register.current
+    return register.at(bar_index - back)
+
+
+def _written(value: Any) -> str:
+    """The offending value as the message shows it."""
+    if value is ABSENT:
+        return "none"
+    if is_number(value):
+        return canonical_number(value)
+    return str(value)
+
+
+class Cells:
+    """The persistent values of section 2.11: one entry per ``var`` declaration.
+
+    Both kinds survive from bar to bar and both start uninitialised, which is a
+    state of its own rather than a value: a cell inside an ``if`` that is false
+    for a hundred bars is absent for a hundred bars, and ``CELL_INIT`` is what
+    ends that.
+    """
+
+    __slots__ = ("values", "ready")
+
+    def __init__(self, count: int) -> None:
+        self.values: List[Any] = [ABSENT] * count
+        self.ready: List[bool] = [False] * count
+
+    def initialised(self, cell: int) -> bool:
+        return self.ready[cell]
+
+    def mark(self, cell: int) -> None:
+        self.ready[cell] = True
+
+    def read(self, cell: int) -> Any:
+        return self.values[cell]
+
+    def write(self, cell: int, value: Any) -> None:
+        self.values[cell] = stored(value)
+
+
+class States:
+    """The per-call-site regions of the library functions that hold state.
+
+    What a region contains is the library's, section 20, and not this engine's.
+    What this engine requires of it is that it be snapshottable by a mechanical
+    copy, because the rollback and replay rules apply to every region at once and
+    an engine must be able to copy one without knowing which function owns it.
+    """
+
+    __slots__ = ("regions",)
+
+    def __init__(self, count: int) -> None:
+        self.regions: List[Dict[str, Any]] = [{} for _ in range(count)]
+
+    def region(self, at: int) -> Dict[str, Any]:
+        return self.regions[at]
+
+
+class Channels:
+    """Everything a script draws for a bar, one value per channel per bar.
+
+    ``EMIT`` is the only way to write one and a second write on a bar replaces
+    the first, so the last write wins and no drawing surface needs a rule of its
+    own. A channel nothing wrote is absent, and absence reaching a surface is a
+    gap in a plot, no marker, no alert, a bar left its own colour: never a zero.
+    """
+
+    __slots__ = ("values",)
+
+    def __init__(self, count: int) -> None:
+        self.values: List[Any] = [ABSENT] * count
+
+    def clear(self) -> None:
+        for at in range(len(self.values)):
+            self.values[at] = ABSENT
+
+    def write(self, channel: int, value: Any) -> None:
+        self.values[channel] = stored(value)
+
+    def read(self, channel: int) -> Any:
+        return self.values[channel]
+
+
+class Frame:
+    """One frame, section 3.3: a list, a counter and the bases a body reads through.
+
+    A frame's stack region is its own. A called function cannot see or disturb
+    the caller's operands, which is what makes the verifier's job local and what
+    lets the depth walk of check 5 stop at a call.
+    """
+
+    __slots__ = ("code", "pc", "slots", "cell_base", "state_base", "bindings", "stack", "positions")
+
+    def __init__(
+        self,
+        code: List[Any],
+        slots: int,
+        cell_base: int = 0,
+        state_base: int = 0,
+        bindings: Optional[List[int]] = None,
+        positions: Optional[List[Any]] = None,
+    ) -> None:
+        self.code = code
+        self.pc = 0
+        self.slots: List[Any] = [ABSENT] * slots
+        self.cell_base = cell_base
+        self.state_base = state_base
+        self.bindings: List[int] = [] if bindings is None else bindings
+        self.stack: List[Any] = []
+        self.positions = positions