openscript 0.4.0__py3-none-any.whl

openscript/opcodes.py

@@ -0,0 +1,166 @@
+"""The forty-one instructions, as a table rather than as forty-one functions.
+
+``compiled-program.md`` section 4.13 prints the whole set with its operands and
+its stack effect, and this is that table in the one form an engine needs it:
+what each opcode's operands are called, how deep the stack goes after it, which
+operand is a jump target, and which table each operand indexes into.
+
+It is a table because verification needs the same facts the interpreter needs. A
+dispatch written as forty-one functions with the operand counts implied by their
+signatures would leave the verifier to state them a second time, and the two
+would drift the day an instruction changed.
+
+**The page is the source and this is a copy, so a test compares them.** That is
+the standing habit of this repository: a figure the specification prints is
+measured by a test rather than quoted by one. ``tests/test_opcodes.py`` reads
+section 4.13 out of the document by pattern and holds every row here to it, so a
+row the page gains, loses or changes fails this engine's tests naming the
+opcode. Nothing here may be corrected without the page being read again.
+"""
+
+from typing import Mapping, Sequence, Tuple
+
+#: Depth changes that are not a fixed number, written as the page writes them.
+BY_COUNT = "1 - n"
+BY_ARGC = "1 - argc"
+
+#: Opcode, operand names in order, depth change, and the group the page files it under.
+TABLE: Mapping[str, Tuple[Sequence[str], object, str]] = {
+    "CONST": (("k",), 1, "Constants and stack"),
+    "DUP": ((), 1, "Constants and stack"),
+    "POP": ((), -1, "Constants and stack"),
+    "LOAD": (("s",), 1, "Slots"),
+    "STORE": (("s",), -1, "Slots"),
+    "CELL_INIT": (("c", "t"), 0, "Cells"),
+    "LOADC": (("c",), 1, "Cells"),
+    "STOREC": (("c",), -1, "Cells"),
+    "SLOAD": (("r",), 1, "Series"),
+    "SSTORE": (("r",), -1, "Series"),
+    "HIST": (("r",), 0, "Series"),
+    "HISTP": (("p",), 0, "Series"),
+    "ADD": ((), -1, "Arithmetic"),
+    "SUB": ((), -1, "Arithmetic"),
+    "MUL": ((), -1, "Arithmetic"),
+    "DIV": ((), -1, "Arithmetic"),
+    "MOD": ((), -1, "Arithmetic"),
+    "NEG": ((), 0, "Arithmetic"),
+    "LT": ((), -1, "Comparison"),
+    "LE": ((), -1, "Comparison"),
+    "GT": ((), -1, "Comparison"),
+    "GE": ((), -1, "Comparison"),
+    "EQ": ((), -1, "Comparison"),
+    "NE": ((), -1, "Comparison"),
+    "NOT": ((), 0, "Logic"),
+    "AND": ((), -1, "Logic"),
+    "OR": ((), -1, "Logic"),
+    "AND_SHORT": (("t",), 0, "Logic"),
+    "OR_SHORT": (("t",), 0, "Logic"),
+    "JUMP": (("t",), 0, "Control"),
+    "JUMP_FALSE": (("t",), -1, "Control"),
+    "TICK": (("l",), 0, "Control"),
+    "FOR_INIT": (("l", "s", "sLim", "sStep", "t"), -3, "Control"),
+    "FOR_NEXT": (("l", "s", "sLim", "sStep", "t"), 0, "Control"),
+    "ARRAY": (("n",), BY_COUNT, "Arrays"),
+    "ELEM": ((), -1, "Arrays"),
+    "CALL_LIB": (("f", "n", "st"), BY_COUNT, "Calls"),
+    "CALL_FN": (("site",), BY_ARGC, "Calls"),
+    "RET": ((), -1, "Calls"),
+    "EMIT": (("ch",), -1, "Output"),
+    "HALT": ((), 0, "Termination"),
+}
+
+#: Which operand of an instruction is a jump target, by position.
+#:
+#: Read off the operand names rather than written down again: ``t`` is the name
+#: section 4's operand table gives a jump target and nothing else carries it.
+TARGETS: Mapping[str, Sequence[int]] = {
+    opcode: tuple(at for at, name in enumerate(names) if name == "t")
+    for opcode, (names, _depth, _group) in TABLE.items()
+}
+
+#: Which table each operand indexes into, for the range half of check 1.
+#:
+#: ``target`` is an instruction index in the same list and ``count`` is a number
+#: the instruction carries rather than an index into anything.
+OPERAND_TABLES: Mapping[str, Sequence[str]] = {
+    "CONST": ("consts",),
+    "LOAD": ("slots",),
+    "STORE": ("slots",),
+    "CELL_INIT": ("cells", "target"),
+    "LOADC": ("cells",),
+    "STOREC": ("cells",),
+    "SLOAD": ("registers",),
+    "SSTORE": ("registers",),
+    "HIST": ("registers",),
+    "HISTP": ("bindings",),
+    "AND_SHORT": ("target",),
+    "OR_SHORT": ("target",),
+    "JUMP": ("target",),
+    "JUMP_FALSE": ("target",),
+    "TICK": ("loops",),
+    "FOR_INIT": ("loops", "slots", "slots", "slots", "target"),
+    "FOR_NEXT": ("loops", "slots", "slots", "slots", "target"),
+    "ARRAY": ("count",),
+    "CALL_LIB": ("libFunctions", "count", "states"),
+    "CALL_FN": ("callSites",),
+    "EMIT": ("channels",),
+}
+
+#: What a reader is told a table is called when an operand is outside it.
+TABLE_NAMES: Mapping[str, str] = {
+    "slots": "the frame",
+    "cells": "cells",
+    "states": "states",
+    "registers": "series",
+    "channels": "channels",
+    "libFunctions": "lib.functions",
+    "callSites": "callSites",
+    "loops": "loops",
+    "consts": "consts",
+    "bindings": "the call site's series bindings",
+}
+
+#: Check 8's program half: an instruction that needs a tag in ``requires``.
+INSTRUCTION_TAGS: Mapping[str, str] = {
+    "ARRAY": "arrays",
+    "ELEM": "arrays",
+    "CALL_FN": "functions",
+    "TICK": "loops",
+}
+
+
+def is_opcode(name: object) -> bool:
+    return isinstance(name, str) and name in TABLE
+
+
+def operand_count(opcode: str) -> int:
+    return len(TABLE[opcode][0])
+
+
+def operand_names(opcode: str) -> Sequence[str]:
+    return TABLE[opcode][0]
+
+
+def depth_change(opcode: str, operands: Sequence[int], argc_of) -> int:
+    """How far the stack moves, with the two formulas resolved.
+
+    ``CALL_FN`` reads its call site's ``argc``, which is fixed at load, so the
+    depth stays statically computable and the verifier can walk the list.
+    """
+    written = TABLE[opcode][1]
+    if written == BY_COUNT:
+        return 1 - int(operands[1] if opcode == "CALL_LIB" else operands[0])
+    if written == BY_ARGC:
+        return 1 - int(argc_of(int(operands[0])))
+    return int(written)
+
+
+def targets(opcode: str) -> Sequence[int]:
+    return TARGETS.get(opcode, ())
+
+
+COUNT: int = len(TABLE)
+
+
+def tables_for(opcode: str) -> Sequence[str]:
+    return OPERAND_TABLES.get(opcode, ())

openscript/program.py

@@ -0,0 +1,146 @@
+"""A verified program, with the parts a bar reads worked out once.
+
+Everything here is a table read from the program rather than a decision about
+it: the constant pool as machine values, the source position of each
+instruction, the line of each loop, and what the library manifest says about
+each entry the program calls. None of it changes between bars, so working it out
+per bar would be the same answer computed forty thousand times.
+
+**Nothing is built out of text.** The program is data, this is that data in the
+shape the loop reads it in, and there is no step between the two where a name
+becomes a function or a string becomes an instruction. That is the rule the
+whole format exists to keep, and it is what lets a platform run many people's
+scripts in one process.
+"""
+
+from dataclasses import dataclass, field
+from typing import Any, Dict, List, Optional, Sequence, Tuple
+
+from .contracts import LibraryEntry
+from .diagnostics import NO_POSITION, Position
+from .values import ABSENT, Colour
+
+
+def constant_value(entry: Sequence[Any]) -> Any:
+    """The machine value a constant pool entry denotes, section 2.9."""
+    tag = entry[0]
+    if tag == "z":
+        return ABSENT
+    if tag == "b":
+        return bool(entry[1])
+    if tag == "n":
+        return float(entry[1])
+    if tag == "s":
+        return entry[1]
+    red, green, blue, alpha = entry[1]
+    return Colour(float(red), float(green), float(blue), float(alpha))
+
+
+def positions_for(triples: Sequence[Sequence[int]], length: int) -> List[Position]:
+    """One position per instruction, from the triples ``debug.pos`` holds.
+
+    Section 2.15: the position of an instruction is the triple with the greatest
+    index at or below it, so a run of instructions from one expression costs one
+    triple. Spread once here rather than searched per instruction, because a
+    diagnostic is rare and the search would be on the path of every bar.
+    """
+    found: List[Position] = [NO_POSITION] * length
+    current = NO_POSITION
+    at = 0
+    ordered = sorted(
+        (one for one in triples if isinstance(one, list) and len(one) >= 3),
+        key=lambda one: one[0],
+    )
+    for index, line, column in ((one[0], one[1], one[2]) for one in ordered):
+        while at < length and at < index:
+            found[at] = current
+            at += 1
+        current = Position(int(line), int(column))
+        if 0 <= index < length:
+            found[index] = current
+            at = index + 1
+    while at < length:
+        found[at] = current
+        at += 1
+    return found
+
+
+@dataclass
+class Body:
+    """One instruction list with the tables a frame running it needs."""
+
+    code: List[Any]
+    positions: List[Position]
+    slots: int
+
+
+@dataclass
+class LoadedProgram:
+    """The verified program and the tables a bar reads, worked out once at load."""
+
+    raw: Dict[str, Any]
+    consts: List[Any] = field(default_factory=list)
+    top: Body = None
+    functions: List[Body] = field(default_factory=list)
+    call_sites: List[Dict[str, Any]] = field(default_factory=list)
+    loop_lines: List[int] = field(default_factory=list)
+    entries: List[LibraryEntry] = field(default_factory=list)
+    defer: List[bool] = field(default_factory=list)
+
+    @property
+    def loop_budget(self) -> int:
+        return int(self.raw["limits"]["loops"])
+
+    @property
+    def retained(self) -> Optional[int]:
+        held = self.raw["limits"]["history"]
+        return None if held is None else int(held)
+
+    @property
+    def on_unconfirmed(self) -> bool:
+        return bool(self.raw["meta"]["onUnconfirmed"])
+
+    @property
+    def kind(self) -> str:
+        return self.raw["meta"]["kind"]
+
+
+def loaded(raw: Dict[str, Any], entries: Sequence[LibraryEntry]) -> LoadedProgram:
+    """Spread a verified program into the tables above, and nothing more."""
+    functions = [
+        Body(
+            code=one["code"],
+            positions=_function_positions(raw, at, len(one["code"])),
+            slots=int(one["slots"]),
+        )
+        for at, one in enumerate(raw["functions"])
+    ]
+    return LoadedProgram(
+        raw=raw,
+        consts=[constant_value(one) for one in raw["consts"]],
+        top=Body(
+            code=raw["code"],
+            positions=positions_for(raw["debug"]["pos"], len(raw["code"])),
+            slots=int(raw["frame"]["slots"]),
+        ),
+        functions=functions,
+        call_sites=list(raw["callSites"]),
+        loop_lines=[int(one["line"]) for one in raw["loops"]],
+        entries=list(entries),
+        defer=[bool(one["defer"]) for one in raw["channels"]],
+    )
+
+
+def _function_positions(raw: Dict[str, Any], which: int, length: int) -> List[Position]:
+    for pair in raw["debug"]["fnPos"]:
+        if isinstance(pair, list) and len(pair) == 2 and pair[0] == which:
+            return positions_for(pair[1], length)
+    return [NO_POSITION] * length
+
+
+def manifest_entries(raw: Dict[str, Any]) -> List[Tuple[str, int, bool, str]]:
+    """What the program says about each function it calls, section 2.5."""
+    return [
+        (one["name"], int(one["arity"]), bool(one["state"]), one["effect"])
+        for one in raw["lib"]["functions"]
+    ]

openscript/run.py

@@ -0,0 +1,368 @@
+"""The eleven steps of section 5.1, and the checkpoint that makes a moving bar idempotent.
+
+Everything else in this package is a detail of one of these steps. They run in
+this order, on every execution of every bar, and the order is not an
+implementation's choice: steps 1 and 2 are what make a still-moving bar
+idempotent, and steps 8 and 9 are what separate what a script may do on a moving
+bar from what it may not.
+
+**The checkpoint is taken before a bar rather than after one.** Section 6.1
+describes it as taken at the end of bar ``i - 1``, and the state at the start of
+the first execution of bar ``i`` *is* that state, so taking it there is the same
+checkpoint reached by the cheaper road: nothing is copied for a bar that is
+executed once, and a re-execution restores what the bar began with. Section 6.2
+says outright that an engine may implement a checkpoint however it likes, and
+that the specification requires the semantics rather than the representation.
+
+**A live cell is written into the checkpoint and is not rolled back.** That is
+the whole of ``live var``, and it has one consequence worth stating rather than
+discovering: where a live cell and an ordinary cell held the same array, the
+restore gives the ordinary cell the copy it recorded and leaves the live cell
+holding what it has now, so the two stop being the same array. That follows from
+the exception rather than from this implementation of it, and a script using
+``live var`` is not reproducible by design.
+
+**An error during step 6 stops the bar.** Steps 7 to 11 do not run, the bar's
+columns keep whatever the previous execution published or stay absent, and the
+engine reports the diagnostic. It does not carry a half executed state into the
+next bar.
+"""
+
+import copy
+from dataclasses import dataclass, field
+from typing import Any, Dict, List, Mapping, Optional, Sequence, Tuple
+
+from .bars import BarFacts, bar_field, facts_for
+from .budget import Budget, DEFAULT_LIMITS, EngineLimits, step_bound
+from .canonical import parse
+from .contracts import Bar, BarState, CallContext, Library, NoLibrary
+from .diagnostics import Diagnostic, ScriptError
+from .inputs import ResolvedInput, TimeReader, field_value, resolve_inputs
+from .machine import Machine, PendingEffect
+from .memory import Cells, Channels, Register, States
+from .program import LoadedProgram, loaded
+from .values import ABSENT
+from .verify import MACHINE_CAPABILITIES, VerifyOptions, verify
+
+
+@dataclass
+class Checkpoint:
+    """What section 6.1 holds, in the one form a mechanical copy can restore."""
+
+    kept: Tuple[Any, Any, Any]
+    lengths: Sequence[int]
+    bar: int
+
+
+@dataclass
+class Alert:
+    """What a raised alert carries, section 5.4, and nothing else.
+
+    Fixed there rather than left to a host, because a host cannot compose a
+    notification out of fields that differ between engines. The message is
+    whatever the channel held, absence included: one built out of a value that
+    was absent during warmup is absent, and an engine that substituted an empty
+    string would hide the one thing the author needs to see.
+    """
+
+    key: str
+    title: Any
+    message: Any
+    bar: int
+    time: Any
+
+
+@dataclass
+class BarResult:
+    """What one execution of one bar produced."""
+
+    index: int
+    columns: List[Any] = field(default_factory=list)
+    #: The deferred channels step 9 applied, by index, and empty where it
+    #: discarded them. The columns carry every channel either way: step 8
+    #: publishes the drawing and step 9 decides the marker and the alert, which
+    #: is the whole difference between what a script may do on a moving bar and
+    #: what it may not.
+    applied_channels: List[int] = field(default_factory=list)
+    applied: List[PendingEffect] = field(default_factory=list)
+    alerts: List[Alert] = field(default_factory=list)
+    diagnostic: Optional[Diagnostic] = None
+
+    @property
+    def ok(self) -> bool:
+        return self.diagnostic is None
+
+
+class Run:
+    """One program, loaded, with the memory a run of it holds."""
+
+    def __init__(
+        self,
+        program: LoadedProgram,
+        inputs: Sequence[ResolvedInput],
+        library: Library,
+        limits: EngineLimits = DEFAULT_LIMITS,
+    ) -> None:
+        self.program = program
+        self.inputs = inputs
+        self.limits = limits
+        raw = program.raw
+        self.cells = Cells(len(raw["cells"]))
+        self.states = States(len(raw["states"]))
+        self.registers = [Register() for _ in raw["series"]]
+        self.channels = Channels(len(raw["channels"]))
+        self.budget = Budget(step_bound(raw), program.loop_budget, limits.string_length)
+        self.machine = Machine(
+            program, self.cells, self.states, self.registers, self.channels, self.budget, library
+        )
+        self._live = [at for at, one in enumerate(raw["cells"]) if one["kind"] == "live"]
+        self._columns: Dict[int, List[Any]] = {}
+        self._checkpoint: Optional[Checkpoint] = None
+        self._fired_ever: set = set()
+        self._fired_on: Dict[str, int] = {}
+        self._supplied = 0
+
+    # -- the declared shape, with every input reference resolved ------------
+
+    def declaration(self, path: Sequence[str]) -> Any:
+        """A declaration field, with its input reference substituted, section 2.3."""
+        held: Any = self.program.raw
+        for step in path:
+            held = held[step]
+        return field_value(held, self.inputs)
+
+    # -- the checkpoint -----------------------------------------------------
+
+    def checkpoint(self, bar: int = -1) -> Checkpoint:
+        """Every cell with its flag, every state region, and the heap under both.
+
+        One mechanical copy over the three together, so that two cells holding
+        one array still hold one array after a restore: a copy taken cell by cell
+        would turn one array into two and change what the script computes.
+
+        ``bar`` is the bar this state is the start of, which is what makes a
+        re-execution recognisable; a caller keeping one for its own reasons, a
+        debugger stepping backwards, leaves it alone.
+        """
+        kept = copy.deepcopy((self.cells.values, self.cells.ready, self.states.regions))
+        return Checkpoint(kept, [one.length for one in self.registers], bar)
+
+    def restore(self, mark: Checkpoint) -> None:
+        """Section 6.3: everything goes back, except that live cells keep theirs."""
+        was = [self.cells.values[at] for at in self._live]
+        ready = [self.cells.ready[at] for at in self._live]
+        values, flags, regions = copy.deepcopy(mark.kept)
+        self.cells.values[:] = values
+        self.cells.ready[:] = flags
+        self.states.regions = regions
+        for at, value, flag in zip(self._live, was, ready):
+            self.cells.values[at] = value
+            self.cells.ready[at] = flag
+        for register, length in zip(self.registers, mark.lengths):
+            register.truncate(length)
+
+    # -- the bar ------------------------------------------------------------
+
+    def execute_bar(
+        self,
+        index: int,
+        bar: Bar,
+        state: BarState = BarState(),
+        supplied: Optional[int] = None,
+        instrument: Optional[Mapping[str, Any]] = None,
+        now: Any = ABSENT,
+    ) -> BarResult:
+        """The eleven steps, in order, for one execution of bar ``index``."""
+        held = index + 1 if supplied is None else supplied
+        self._supplied = held
+
+        # Step 1. On the first execution of this bar the state already is the
+        # checkpoint, so nothing is copied; it is recorded instead, because the
+        # next execution of the same bar is what needs it.
+        if self._checkpoint is not None and self._checkpoint.bar == index:
+            self.restore(self._checkpoint)
+        else:
+            self._checkpoint = self.checkpoint(index)
+
+        # Step 2.
+        for register in self.registers:
+            register.truncate(index)
+
+        # Step 3.
+        self.channels.clear()
+        for register in self.registers:
+            register.current = ABSENT
+        context = CallContext(
+            bar_index=index, instrument={} if instrument is None else instrument, now=now
+        )
+        self.machine.begin(index, context)
+
+        # Step 4.
+        facts = facts_for(index, held, state)
+        self._fill_registers(bar, facts)
+
+        # Step 5.
+        self._fill_inputs()
+
+        # Step 6.
+        try:
+            self.machine.execute()
+        except ScriptError as stopped:
+            return BarResult(index, self._columns.get(index, []), [], [], [], stopped.diagnostic)
+
+        # Step 7.
+        for register in self.registers:
+            register.close()
+
+        # Step 8.
+        columns = list(self.channels.values)
+        self._columns[index] = columns
+
+        # Step 9.
+        decided = state.is_confirmed or self.program.on_unconfirmed
+        applied: List[PendingEffect] = []
+        alerts: List[Alert] = []
+        channels: List[int] = []
+        if decided:
+            applied = list(self.machine.pending)
+            channels = [at for at, held in enumerate(self.program.defer) if held]
+            alerts = self._raise_alerts(index, bar, state)
+
+        # Step 10.
+        retained = self.program.retained
+        if retained is not None:
+            for register in self.registers:
+                register.trim(retained)
+
+        # Step 11 is the record taken at the top of the next bar: see the note
+        # at the head of this module.
+        return BarResult(index, columns, channels, applied, alerts, None)
+
+    def _fill_registers(self, bar: Bar, facts: BarFacts) -> None:
+        for at, declared in enumerate(self.program.raw["series"]):
+            if declared["kind"] == "bar":
+                self.registers[at].current = bar_field(declared["field"], bar, facts)
+
+    def _fill_inputs(self) -> None:
+        """Step 5: the effective values, already resolved, written into slots.
+
+        A ``"source"`` input is the one that reads something here: its value is
+        the register it named, for the bar about to run, rather than a value
+        settled at load.
+        """
+        for one in self.inputs:
+            if one.field is None:
+                self.machine.write_slot(one.slot, one.value)
+                continue
+            self.machine.write_slot(one.slot, self._register_named(one.field))
+
+    def _register_named(self, field: str) -> Any:
+        for at, declared in enumerate(self.program.raw["series"]):
+            if declared["kind"] == "bar" and declared["field"] == field:
+                return self.registers[at].current
+        return ABSENT
+
+    def _raise_alerts(self, index: int, bar: Bar, state: BarState) -> List[Alert]:
+        """Section 5.4: on a bar this engine decided and the host is driving live.
+
+        Deferral covers half of when an alert fires. The other half is that
+        adding a study to a chart that already holds history fires nothing for
+        those bars, and the fact that separates a bar of history from the bar in
+        front of you is ``isRealtime``, which the host states and no engine can
+        derive. An engine that only backtests is handed it false throughout and
+        raises none, which is the same answer reached from the other side.
+        """
+        if not state.is_realtime:
+            return []
+        raised: List[Alert] = []
+        for declared in self.program.raw["outputs"]["alerts"]:
+            if self.channels.read(declared["condChannel"]) is not True:
+                continue
+            key = declared["key"]
+            frequency = field_value(declared["frequency"], self.inputs)
+            if frequency == "once" and key in self._fired_ever:
+                continue
+            if frequency == "oncePerBar" and self._fired_on.get(key) == index:
+                continue
+            message = ABSENT
+            if declared.get("messageChannel") is not None:
+                message = self.channels.read(declared["messageChannel"])
+            raised.append(
+                Alert(
+                    key=key,
+                    title=field_value(declared["title"], self.inputs),
+                    message=message,
+                    bar=index,
+                    time=bar.time,
+                )
+            )
+            self._fired_ever.add(key)
+            self._fired_on[key] = index
+        return raised
+
+
+@dataclass
+class LoadResult:
+    run: Optional[Run] = None
+    diagnostic: Optional[Diagnostic] = None
+
+    @property
+    def ok(self) -> bool:
+        return self.diagnostic is None
+
+
+def load(
+    raw: Any,
+    settings: Optional[Mapping[str, Any]] = None,
+    library: Optional[Library] = None,
+    limits: EngineLimits = DEFAULT_LIMITS,
+    capabilities: Sequence[str] = MACHINE_CAPABILITIES,
+    read_time: Optional[TimeReader] = None,
+) -> LoadResult:
+    """Steps 2 to 8 of section 9.4, then check 10's value half, then a run.
+
+    An object built in the same process enters here: it was never text and has
+    nothing to be canonical about, which is section 9.4 step 1's other half and
+    the minute that settled it.
+    """
+    served = library if library is not None else NoLibrary()
+    checked = verify(raw, VerifyOptions(capabilities=capabilities, limits=limits, library=served))
+    if not checked.ok:
+        return LoadResult(None, checked.diagnostic)
+    resolved = resolve_inputs(checked.program, {} if settings is None else settings, read_time)
+    if not resolved.ok:
+        return LoadResult(None, resolved.diagnostic)
+    entries = _entries_for(checked.program, served)
+    return LoadResult(
+        Run(loaded(checked.program, entries), resolved.inputs, served, limits), None
+    )
+
+
+def load_text(
+    text: str,
+    settings: Optional[Mapping[str, Any]] = None,
+    library: Optional[Library] = None,
+    limits: EngineLimits = DEFAULT_LIMITS,
+    capabilities: Sequence[str] = MACHINE_CAPABILITIES,
+    read_time: Optional[TimeReader] = None,
+) -> LoadResult:
+    """The text boundary: step 1 of section 9.4, then everything ``load`` does.
+
+    Text an engine reads from outside its process arrives as the canonical
+    encoding and its hash was taken over those bytes, so text that parses to a
+    program but is spelled some other way is text that hash does not name.
+    """
+    parsed, refusal = parse(text)
+    if refusal is not None:
+        return LoadResult(None, refusal)
+    return load(parsed, settings, library, limits, capabilities, read_time)
+
+
+def _entries_for(raw: Any, library: Library) -> List[Any]:
+    """The manifest entry for each function the program calls, in its own order.
+
+    Verification has already held every one of them to this engine's manifest, so
+    reading them here is reading facts that agree rather than trusting the
+    program's copy.
+    """
+    return [library.entry(one["name"], one["arity"]) for one in raw["lib"]["functions"]]