astreum 0.2.29__py3-none-any.whl → 0.2.61__py3-none-any.whl

astreum/_lispeum/low_evaluation.py

@@ -0,0 +1,123 @@
+from typing import Dict, List, Union
+from .expression import Expr, error_expr
+from .meter import Meter
+
+def tc_to_int(b: bytes) -> int:
+    """bytes -> int using two's complement (width = len(b)*8)."""
+    if not b:
+        return 0
+    return int.from_bytes(b, "big", signed=True)
+
+def int_to_tc(n: int, width_bytes: int) -> bytes:
+    """int -> bytes (two's complement, fixed width)."""
+    if width_bytes <= 0:
+        return b"\x00"
+    return n.to_bytes(width_bytes, "big", signed=True)
+
+def min_tc_width(n: int) -> int:
+    """minimum bytes to store n in two's complement."""
+    if n == 0:
+        return 1
+    w = 1
+    while True:
+        try:
+            n.to_bytes(w, "big", signed=True)
+            return w
+        except OverflowError:
+            w += 1
+
+def nand_bytes(a: bytes, b: bytes) -> bytes:
+    """Bitwise NAND on two byte strings, zero-extending to max width."""
+    w = max(len(a), len(b), 1)
+    au = int.from_bytes(a.rjust(w, b"\x00"), "big", signed=False)
+    bu = int.from_bytes(b.rjust(w, b"\x00"), "big", signed=False)
+    mask = (1 << (w * 8)) - 1
+    resu = (~(au & bu)) & mask
+    return resu.to_bytes(w, "big", signed=False)
+
+def low_eval(self, code: List[bytes], meter: Meter) -> Expr:
+        
+        heap: Dict[bytes, bytes] = {}
+
+        stack: List[bytes] = []
+        pc = 0
+
+        while True:
+            if pc >= len(code):
+                if len(stack) != 1:
+                    return error_expr("low_eval", "bad stack")
+                # wrap successful result as an Expr.Bytes
+                return Expr.Bytes(stack.pop())
+
+            tok = code[pc]
+            pc += 1
+
+            # ---------- ADD ----------
+            if tok == b"add":
+                if len(stack) < 2:
+                    return error_expr("low_eval", "underflow")
+                b_b = stack.pop()
+                a_b = stack.pop()
+                a_i = tc_to_int(a_b)
+                b_i = tc_to_int(b_b)
+                res_i = a_i + b_i
+                width = max(len(a_b), len(b_b), min_tc_width(res_i))
+                res_b = int_to_tc(res_i, width)
+                # charge for both operands' byte widths
+                if not meter.charge_bytes(len(a_b) + len(b_b)):
+                    return error_expr("low_eval", "meter limit")
+                stack.append(res_b)
+                continue
+
+            # ---------- NAND ----------
+            if tok == b"nand":
+                if len(stack) < 2:
+                    return error_expr("low_eval", "underflow")
+                b_b = stack.pop()
+                a_b = stack.pop()
+                res_b = nand_bytes(a_b, b_b)
+                # bitwise cost: 2 * max(len(a), len(b))
+                if not meter.charge_bytes(2 * max(len(a_b), len(b_b), 1)):
+                    return error_expr("low_eval", "meter limit")
+                stack.append(res_b)
+                continue
+
+            # ---------- JUMP ----------
+            if tok == b"jump":
+                if len(stack) < 1:
+                    return error_expr("low_eval", "underflow")
+                tgt_b = stack.pop()
+                if not meter.charge_bytes(1):
+                    return error_expr("low_eval", "meter limit")
+                tgt_i = tc_to_int(tgt_b)
+                if tgt_i < 0 or tgt_i >= len(code):
+                    return error_expr("low_eval", "bad jump")
+                pc = tgt_i
+                continue
+
+            # ---------- HEAP GET ----------
+            if tok == b"heap_get":
+                if len(stack) < 1:
+                    return error_expr("low_eval", "underflow")
+                key = stack.pop()
+                val = heap.get(key) or b""
+                # get cost: 1
+                if not meter.charge_bytes(1):
+                    return error_expr("low_eval", "meter limit")
+                stack.append(val)
+                continue
+
+            # ---------- HEAP SET ----------
+            if tok == b"heap_set":
+                if len(stack) < 2:
+                    return error_expr("low_eval", "underflow")
+                val = stack.pop()
+                key = stack.pop()
+                if not meter.charge_bytes(len(val)):
+                    return error_expr("low_eval", "meter limit")
+                heap[key] = val
+                continue
+
+            # if no opcode matched above, treat token as literal
+            # not an opcode → literal blob
+            stack.append(tok)

astreum/_lispeum/meter.py

@@ -0,0 +1,18 @@
+from typing import Optional
+
+
+class Meter:
+    def __init__(self, enabled: bool = True, limit: Optional[int] = None):
+        self.enabled = enabled
+        self.limit: Optional[int] = limit
+        self.used: int = 0
+
+    def charge_bytes(self, n: int) -> bool:
+        if not self.enabled:
+            return True
+        if n < 0:
+            n = 0
+        if self.limit is not None and (self.used + n) >= self.limit:
+            return False
+        self.used += n
+        return True

astreum/_lispeum/parser.py

@@ -0,0 +1,51 @@
+from typing import List, Tuple
+from . import Expr
+
+class ParseError(Exception):
+    pass
+
+def _parse_one(tokens: List[str], pos: int = 0) -> Tuple[Expr, int]:
+    if pos >= len(tokens):
+        raise ParseError("unexpected end")
+    tok = tokens[pos]
+
+    if tok == '(':  # list
+        items: List[Expr] = []
+        i = pos + 1
+        while i < len(tokens):
+            if tokens[i] == ')':
+                return Expr.ListExpr(items), i + 1
+            expr, i = _parse_one(tokens, i)
+            items.append(expr)
+        raise ParseError("expected ')'")
+
+    if tok == ')':
+        raise ParseError("unexpected ')'")
+
+    # try integer → Bytes (variable-length two's complement)
+    try:
+        n = int(tok)
+        # encode as minimal-width signed two's complement, big-endian
+        def int_to_min_tc(v: int) -> bytes:
+            """Return the minimal-width signed two's complement big-endian
+            byte encoding of integer v. Width expands just enough so that
+            decoding with signed=True yields the same value and sign.
+            Example: 0 -> b"\x00", 127 -> b"\x7f", 128 -> b"\x00\x80".
+            """
+            if v == 0:
+                return b"\x00"
+            w = 1
+            while True:
+                try:
+                    return v.to_bytes(w, "big", signed=True)
+                except OverflowError:
+                    w += 1
+
+        return Expr.Bytes(int_to_min_tc(n)), pos + 1
+    except ValueError:
+        return Expr.Symbol(tok), pos + 1
+
+def parse(tokens: List[str]) -> Tuple[Expr, List[str]]:
+    """Parse tokens into an Expr and return (expr, remaining_tokens)."""
+    expr, next_pos = _parse_one(tokens, 0)
+    return expr, tokens[next_pos:]

astreum/_lispeum/tokenizer.py

@@ -0,0 +1,22 @@
+from typing import List
+
+
+def tokenize(source: str) -> List[str]:
+    tokens: List[str] = []
+    cur: List[str] = []
+    for ch in source:
+        if ch.isspace():
+            if cur:
+                tokens.append("".join(cur))
+                cur = []
+            continue
+        if ch in ("(", ")"):
+            if cur:
+                tokens.append("".join(cur))
+                cur = []
+            tokens.append(ch)
+            continue
+        cur.append(ch)
+    if cur:
+        tokens.append("".join(cur))
+    return tokens

astreum/_node.py

@@ -0,0 +1,198 @@
+from __future__ import annotations
+from pathlib import Path
+from typing import Dict, List, Optional
+import uuid
+import threading
+
+from astreum._storage.atom import AtomKind
+
+from ._storage import Atom, storage_setup
+from ._lispeum import Env, Expr, Meter, low_eval, parse, tokenize, ParseError
+from .utils.logging import logging_setup
+
+__all__ = [
+    "Node",
+    "Env",
+    "Expr",
+    "Meter",
+    "parse",
+    "tokenize",
+]
+
+def bytes_touched(*vals: bytes) -> int:
+    """For metering: how many bytes were manipulated (max of operands)."""
+    return max((len(v) for v in vals), default=1)
+
+class Node:
+    def __init__(self, config: dict):
+        self.logger = logging_setup(config)
+        self.logger.info("Starting Astreum Node")
+        # Storage Setup
+        storage_setup(self, config=config)
+        # Lispeum Setup
+        self.environments: Dict[uuid.UUID, Env] = {}
+        self.machine_environments_lock = threading.RLock()
+        self.low_eval = low_eval
+        # Communication and Validation Setup (import lazily to avoid heavy deps during parsing tests)
+        try:
+            from astreum._communication import communication_setup  # type: ignore
+            communication_setup(node=self, config=config)
+        except Exception:
+            pass
+        try:
+            from astreum._consensus import consensus_setup  # type: ignore
+            consensus_setup(node=self, config=config)
+        except Exception:
+            pass
+        
+
+
+    # ---- Env helpers ----
+    def env_get(self, env_id: uuid.UUID, key: bytes) -> Optional[Expr]:
+        cur = self.environments.get(env_id)
+        while cur is not None:
+            if key in cur.data:
+                return cur.data[key]
+            cur = self.environments.get(cur.parent_id) if cur.parent_id else None
+        return None
+
+    def env_set(self, env_id: uuid.UUID, key: bytes, value: Expr) -> bool:
+        with self.machine_environments_lock:
+            env = self.environments.get(env_id)
+            if env is None:
+                return False
+            env.data[key] = value
+            return True
+
+    # Storage
+    def _hot_storage_get(self, key: bytes) -> Optional[Atom]:
+        atom = self.hot_storage.get(key)
+        if atom is not None:
+            self.hot_storage_hits[key] = self.hot_storage_hits.get(key, 0) + 1
+        return atom
+
+    def _hot_storage_set(self, key: bytes, value: Atom) -> bool:
+        """Store atom in hot storage without exceeding the configured limit."""
+        projected = self.hot_storage_size + value.size
+        if projected > self.hot_storage_limit:
+            return False
+
+        self.hot_storage[key] = value
+        self.hot_storage_size = projected
+        return True
+
+    def _network_get(self, key: bytes) -> Optional[Atom]:
+        # locate storage provider
+        # query storage provider
+        return None
+
+    def storage_get(self, key: bytes) -> Optional[Atom]:
+        """Retrieve an Atom by checking local storage first, then the network."""
+        atom = self._hot_storage_get(key)
+        if atom is not None:
+            return atom
+        atom = self._cold_storage_get(key)
+        if atom is not None:
+            return atom
+        return self._network_get(key)
+
+    def _cold_storage_get(self, key: bytes) -> Optional[Atom]:
+        """Read an atom from the cold storage directory if configured."""
+        if not self.cold_storage_path:
+            return None
+        filename = f"{key.hex().upper()}.bin"
+        file_path = Path(self.cold_storage_path) / filename
+        try:
+            data = file_path.read_bytes()
+        except FileNotFoundError:
+            return None
+        except OSError:
+            return None
+        try:
+            return Atom.from_bytes(data)
+        except ValueError:
+            return None
+
+    def _cold_storage_set(self, atom: Atom) -> None:
+        """Persist an atom into the cold storage directory if it already exists."""
+        if not self.cold_storage_path:
+            return
+        atom_bytes = atom.to_bytes()
+        projected = self.cold_storage_size + len(atom_bytes)
+        if self.cold_storage_limit and projected > self.cold_storage_limit:
+            return
+        directory = Path(self.cold_storage_path)
+        if not directory.exists():
+            return
+        atom_id = atom.object_id()
+        filename = f"{atom_id.hex().upper()}.bin"
+        file_path = directory / filename
+        try:
+            file_path.write_bytes(atom_bytes)
+            self.cold_storage_size = projected
+        except OSError:
+            return
+
+    def _network_set(self, atom: Atom) -> None:
+        """Advertise an atom to the closest known peer so they can fetch it from us."""
+        try:
+            from ._communication.message import Message, MessageTopic
+        except Exception:
+            return
+
+        atom_id = atom.object_id()
+        try:
+            closest_peer = self.peer_route.closest_peer_for_hash(atom_id)
+        except Exception:
+            return
+        if closest_peer is None or closest_peer.address is None:
+            return
+        target_addr = closest_peer.address
+
+        try:
+            provider_ip, provider_port = self.incoming_socket.getsockname()[:2]
+        except Exception:
+            return
+
+        provider_str = f"{provider_ip}:{int(provider_port)}"
+        try:
+            provider_bytes = provider_str.encode("utf-8")
+        except Exception:
+            return
+
+        payload = atom_id + provider_bytes
+        message = Message(topic=MessageTopic.STORAGE_REQUEST, content=payload)
+        self.outgoing_queue.put((message.to_bytes(), target_addr))
+
+    def get_expr_list_from_storage(self, key: bytes) -> Optional["ListExpr"]:
+        atoms = self.get_atom_list_from_storage(root_hash=key)
+        if atoms is None:
+            return None
+        
+        expr_list = []
+        for atom in atoms:
+            match atom.kind:
+                case AtomKind.SYMBOL:
+                    expr_list.append(Expr.Symbol(atom.data))
+                case AtomKind.BYTES:
+                    expr_list.append(Expr.Bytes(atom.data))
+                case AtomKind.LIST:
+                    expr_list.append(Expr.ListExpr([
+                        Expr.Bytes(atom.data),
+                        Expr.Symbol("ref")
+                    ]))
+
+        expr_list.reverse()
+        return Expr.ListExpr(expr_list)
+    
+    def get_atom_list_from_storage(self, root_hash: bytes) -> Optional[List["Atom"]]:
+        next_id: Optional[bytes] = root_hash
+        atom_list: List["Atom"] = []
+        while next_id:
+            elem = self.storage_get(key=next_id)
+            if elem:
+                atom_list.append(elem)
+                next_id = elem.next
+            else:
+                return None
+        return atom_list

astreum/_storage/__init__.py

@@ -0,0 +1,7 @@
+from .atom import Atom
+from .setup import storage_setup
+
+__all__ = [
+    "Atom",
+    "storage_setup",
+]

astreum/_storage/atom.py

@@ -0,0 +1,109 @@
+
+
+from enum import IntEnum
+from typing import List, Optional, Tuple
+
+from blake3 import blake3
+
+ZERO32 = b"\x00"*32
+
+def u64_le(n: int) -> bytes:
+    return int(n).to_bytes(8, "little", signed=False)
+
+def hash_bytes(b: bytes) -> bytes:
+    return blake3(b).digest()
+
+class AtomKind(IntEnum):
+    SYMBOL = 0
+    BYTES = 1
+    LIST = 2
+
+
+class Atom:
+    data: bytes
+    next: bytes
+    size: int
+
+    def __init__(
+        self,
+        data: bytes,
+        next: bytes = ZERO32,
+        size: Optional[int] = None,
+        kind: AtomKind = AtomKind.BYTES,
+    ):
+        self.data = data
+        self.next = next
+        self.size = len(data) if size is None else size
+        self.kind = kind
+
+    @staticmethod
+    def from_data(
+        data: bytes,
+        next_hash: bytes = ZERO32,
+        kind: AtomKind = AtomKind.BYTES,
+    ) -> "Atom":
+        return Atom(data=data, next=next_hash, size=len(data), kind=kind)
+
+    def generate_id(self) -> bytes:
+        """Compute the object id using this atom's metadata."""
+        kind_bytes = int(self.kind).to_bytes(1, "little", signed=False)
+        return blake3(
+            kind_bytes + self.data_hash() + self.next + u64_le(self.size)
+        ).digest()
+
+    def data_hash(self) -> bytes:
+        return hash_bytes(self.data)
+
+    def object_id(self) -> bytes:
+        return self.generate_id()
+
+    @staticmethod
+    def verify_metadata(
+        object_id: bytes,
+        size: int,
+        next_hash: bytes,
+        data_hash: bytes,
+        kind: AtomKind,
+    ) -> bool:
+        kind_bytes = int(kind).to_bytes(1, "little", signed=False)
+        expected = blake3(kind_bytes + data_hash + next_hash + u64_le(size)).digest()
+        return object_id == expected
+
+    def to_bytes(self) -> bytes:
+        """Serialize as next-hash + kind byte + payload."""
+        kind_byte = int(self.kind).to_bytes(1, "little", signed=False)
+        return self.next + kind_byte + self.data
+
+    @staticmethod
+    def from_bytes(buf: bytes) -> "Atom":
+        header_len = len(ZERO32)
+        if len(buf) < header_len + 1:
+            raise ValueError("buffer too short for Atom header")
+        next_hash = buf[:header_len]
+        kind_value = buf[header_len]
+        data = buf[header_len + 1 :]
+        try:
+            kind = AtomKind(kind_value)
+        except ValueError as exc:
+            raise ValueError(f"unknown atom kind: {kind_value}") from exc
+        return Atom(data=data, next=next_hash, size=len(data), kind=kind)
+
+def bytes_list_to_atoms(values: List[bytes]) -> Tuple[bytes, List[Atom]]:
+    """Build a forward-ordered linked list of atoms from byte payloads.
+
+    Returns the head object's hash (ZERO32 if no values) and the atoms created.
+    """
+    next_hash = ZERO32
+    atoms: List[Atom] = []
+
+    for value in reversed(values):
+        atom = Atom.from_data(
+            data=bytes(value),
+            next_hash=next_hash,
+            kind=AtomKind.BYTES,
+        )
+        atoms.append(atom)
+        next_hash = atom.object_id()
+
+    atoms.reverse()
+    return (next_hash if values else ZERO32), atoms