hydo-assert 0.2.0__py3-none-any.whl

hydo_assert/_sink.py

@@ -0,0 +1,93 @@
+"""Where records go: the guest console, opened once.
+
+``HYDO_ASSERT_OUT`` (read once, at the first record) selects the target, as in the Go SDK:
+
+- unset or empty: ``/dev/ttyS0`` (the hvx guest console);
+- a path: that existing file, opened ``O_WRONLY|O_APPEND|O_NOCTTY`` (never created);
+- ``stderr``: standard error (file descriptor 2), i.e. plain logging outside hydo;
+- ``off``: nowhere;
+- ``logging`` (Python only): each record line is logged at INFO on the logger ``hydo_assert``.
+
+If the file cannot be opened the records go to standard error. Every record is written with
+one ``write()`` call (a loop only if the kernel accepts part of it), so it is never interleaved
+with other output on the console.
+"""
+
+import os
+import threading
+
+_lock = threading.Lock()
+_ready = False
+_mode = "fd"  # "fd", "off" or "logging"
+_fd = 2
+
+
+def _init():
+    global _ready, _mode, _fd
+    p = os.environ.get("HYDO_ASSERT_OUT", "")
+    if p == "off":
+        _mode = "off"
+    elif p == "stderr":
+        _mode, _fd = "fd", 2
+    elif p == "logging":
+        _mode = "logging"
+    else:
+        if p == "":
+            p = "/dev/ttyS0"
+        try:
+            _fd = os.open(p, os.O_WRONLY | os.O_APPEND | getattr(os, "O_NOCTTY", 0))
+            _mode = "fd"
+        except OSError:
+            _mode, _fd = "fd", 2
+    _ready = True
+
+
+def _ensure():
+    if not _ready:
+        with _lock:
+            if not _ready:
+                _init()
+
+
+def enabled():
+    """False when HYDO_ASSERT_OUT=off (records are dropped)."""
+    _ensure()
+    return _mode != "off"
+
+
+def write_line(line):
+    """Write one record line (``line`` without the trailing newline) to the sink."""
+    _ensure()
+    if _mode == "off":
+        return
+    if _mode == "logging":
+        import logging
+
+        logging.getLogger("hydo_assert").info("%s", line)
+        return
+    data = (line + "\n").encode("utf-8", "surrogatepass")
+    try:
+        while data:
+            n = os.write(_fd, data)
+            if n <= 0:
+                break
+            data = data[n:]
+    except OSError:
+        pass  # like Go's f.Write: a failed console write is not the program's problem
+
+
+def _reset():
+    """Forget the sink (tests). The next record re-reads HYDO_ASSERT_OUT."""
+    global _ready, _mode, _fd
+    with _lock:
+        if _ready and _mode == "fd" and _fd > 2:
+            try:
+                os.close(_fd)
+            except OSError:
+                pass
+        _ready, _mode, _fd = False, "fd", 2
+
+
+def _after_fork():
+    global _lock
+    _lock = threading.Lock()

hydo_assert/history.py

@@ -0,0 +1,300 @@
+"""Operation histories for hydo's host-side checkers (hydo/HISTORIES.md).
+
+A workload client records every operation it performs -- the invocation before the request,
+the completion after the reply -- and the host checks the whole history after the run
+(linearizability of a register / CAS object per key, Elle-style list-append). The lines are byte
+for byte those of the Go recorder (sdk/go/hydohist)::
+
+    HYDO-HIST <history> <process> <invoke|ok|fail|info> <time-ns> <f> <arg>...
+
+Use::
+
+    from hydo_assert import history as hh
+
+    kv = hh.History("kv")
+    op = kv.invoke(3, "write", "k1", hh.enc(v))     # process 3, before the request
+    try:
+        rev = put("k1", v)
+        op.ok("k1", hh.ver(v, rev))                 # the version the store assigned, if any
+    except Rejected:
+        op.fail()                                   # definitely had no effect
+    except Exception:
+        op.info()                                   # a timeout: unknown outcome
+    op = kv.invoke(3, "read", "k1")
+    op.ok("k1", hh.value_or_nil(get("k1")))         # None = absent
+
+One record = one line = one ``os.write`` to ``/dev/console``; ``HYDO_HIST_OUT=<path>|stderr|off``
+overrides it (the assertion records keep ``HYDO_ASSERT_OUT``). A path is opened
+``O_WRONLY|O_APPEND|O_CREAT|O_NOCTTY`` (mode 0644), once, at the first record; if it cannot be
+opened the records go to standard error. The host orders operations by the position of their
+records, so record the invocation before sending and the completion after receiving. A process
+has at most one operation in flight: give each concurrent client (thread, task) its own process
+number. The time field is CLOCK_MONOTONIC in ns (``time.monotonic_ns()``, deterministic under
+hydo); the checkers do not order by it.
+
+Text: tokens are written as UTF-8. A ``str`` is encoded with the ``surrogateescape`` rule, so a
+string that came from bytes that way (``os.fsdecode``, ``sys.argv``, ``os.environ``, or the result
+of ``enc`` on bytes) gives back its original bytes; any other lone surrogate is written as U+FFFD.
+``bytes`` are accepted wherever a ``str`` is and are taken as they are, so invalid UTF-8 can be
+recorded exactly as Go records it.
+
+This module is not imported by ``hydo_assert`` itself: importing the assertion SDK writes and
+opens nothing new.
+"""
+
+import operator
+import os
+import threading
+import time
+
+__all__ = [
+    "NIL",
+    "History",
+    "Op",
+    "enc",
+    "ver",
+    "value_or_nil",
+    "list_value",
+    "append_mop",
+    "read_mop",
+    "read_result_mop",
+]
+
+#: The value of an absent key (register model); the empty list is ``[]``.
+NIL = "nil"
+
+_INT64_MIN = -(1 << 63)
+_INT64_MAX = (1 << 63) - 1
+
+
+def _utf8(s):
+    """The bytes of a str: UTF-8 with surrogateescape; other lone surrogates become U+FFFD."""
+    try:
+        return s.encode("utf-8", "surrogateescape")
+    except UnicodeEncodeError:
+        out = bytearray()
+        for ch in s:
+            o = ord(ch)
+            if 0xDC80 <= o <= 0xDCFF:
+                out.append(o - 0xDC00)
+            elif 0xD800 <= o <= 0xDFFF:
+                out += b"\xef\xbf\xbd"
+            else:
+                out += ch.encode("utf-8")
+        return bytes(out)
+
+
+def _int(x, what):
+    """An int64 in decimal, as Go's strconv.FormatInt writes it (bool is refused)."""
+    try:
+        if isinstance(x, bool):
+            raise TypeError
+        x = operator.index(x)
+    except TypeError:
+        raise TypeError("hydo_assert.history: %s must be an int, got %s" % (what, type(x).__name__)) from None
+    if not _INT64_MIN <= x <= _INT64_MAX:
+        raise ValueError("hydo_assert.history: %s %d is outside int64" % (what, x))
+    return str(int(x))
+
+
+def _token(x, what="argument"):
+    """A record argument: a str (one token already), bytes (taken as they are) or an int."""
+    if isinstance(x, str):
+        return x
+    if isinstance(x, (bytes, bytearray, memoryview)):
+        return bytes(x).decode("utf-8", "surrogateescape")
+    return _int(x, what)
+
+
+# Bytes 0x00-0x7f: the byte itself, or %XX for '%', '@', whitespace and control characters
+# (<= ' '), DEL and the list / txn separators ',[]:' (Go's Enc). Bytes >= 0x80 stay.
+_TABLE = []
+for _c in range(256):
+    if _c == 0x25 or _c == 0x40 or _c <= 0x20 or _c == 0x7F or _c in b",[]:":
+        _TABLE.append(("%%%02X" % _c).encode("ascii"))
+    else:
+        _TABLE.append(bytes((_c,)))
+del _c
+
+
+def enc(s):
+    """One token from a value, as Go's ``hydohist.Enc`` makes it from the value's bytes.
+
+    '%', '@', whitespace, control characters, DEL and ``,[]:`` become ``%XX``; other bytes
+    (all of non-ASCII UTF-8, and invalid bytes given as ``bytes``) stay. ``""`` is ``"%"`` and
+    ``"nil"`` is ``"%6Eil"`` (the token ``nil`` means absent). ``s`` is a str, bytes or an int.
+    """
+    if isinstance(s, str):
+        b = _utf8(s)
+    elif isinstance(s, (bytes, bytearray, memoryview)):
+        b = bytes(s)
+    else:
+        b = _int(s, "enc value").encode("ascii")
+    if b == b"":
+        return "%"
+    if b == b"nil":
+        return "%6Eil"
+    t = _TABLE
+    return b"".join([t[c] for c in b]).decode("utf-8", "surrogateescape")
+
+
+def ver(v, version):
+    """Value ``v`` (encoded) with the version the store assigned it (an int64): ``"v@83"``."""
+    return enc(v) + "@" + _int(version, "version")
+
+
+def value_or_nil(v):
+    """``enc(v)``, or ``NIL`` when ``v`` is None (Go's ``ValOrNil(v, ok)`` with ok = v is not None)."""
+    return NIL if v is None else enc(v)
+
+
+def list_value(*elems):
+    """A list value ``"[e1,e2,...]"`` (list-append reads), each element encoded.
+
+    Go and Rust call it ``List`` / ``list``; here a function named ``list`` would hide the
+    builtin for every ``from hydo_assert.history import *`` user.
+    """
+    return "[" + ",".join([enc(e) for e in elems]) + "]"
+
+
+def append_mop(k, e):
+    """The list-append txn micro-op ``"a:<k>:<e>"``."""
+    return "a:" + enc(k) + ":" + enc(e)
+
+
+def read_mop(k):
+    """The list-append txn micro-op ``"r:<k>"`` (invocation)."""
+    return "r:" + enc(k)
+
+
+def read_result_mop(k, *l):
+    """The list-append txn micro-op ``"r:<k>:[...]"`` (completion)."""
+    return "r:" + enc(k) + ":" + list_value(*l)
+
+
+# ---------------------------------------------------------------------------------------------
+# Sink: opened once, at the first record.
+
+_lock = threading.Lock()
+_ready = False
+_off = False
+_fd = 2
+
+
+def _init():
+    global _ready, _off, _fd
+    p = os.environ.get("HYDO_HIST_OUT", "")
+    _off, _fd = False, 2
+    if p == "off":
+        _off = True
+    elif p != "stderr":
+        if p == "":
+            p = "/dev/console"
+        try:
+            _fd = os.open(p, os.O_WRONLY | os.O_APPEND | os.O_CREAT | getattr(os, "O_NOCTTY", 0), 0o644)
+        except OSError:
+            _fd = 2
+    _ready = True
+
+
+def _write(name, proc, typ, f, args):
+    if not _ready:
+        with _lock:
+            if not _ready:
+                _init()
+    if _off:
+        return
+    parts = [name, proc, typ, None, f]
+    for a in args:
+        parts.append(a if a != "" else "%")  # the empty string (enc("") gives it too)
+    with _lock:
+        # The time is read under the lock, so the times of the records on one console never
+        # decrease (Go reads it just before taking its lock; the format is the same).
+        parts[3] = str(time.monotonic_ns())
+        data = _utf8("HYDO-HIST " + " ".join(parts) + "\n")
+        try:
+            while data:  # one write(); a short write (never on the console) is continued
+                n = os.write(_fd, data)
+                if n <= 0:
+                    break
+                data = data[n:]
+        except OSError:
+            pass  # like Go's f.Write: a failed console write is ignored
+
+
+def _reset():
+    """Forget the sink (tests). The next record re-reads HYDO_HIST_OUT."""
+    global _ready, _off, _fd
+    with _lock:
+        if _ready and not _off and _fd > 2:
+            try:
+                os.close(_fd)
+            except OSError:
+                pass
+        _ready, _off, _fd = False, False, 2
+
+
+def _after_fork():
+    # The child inherits the descriptor; a lock held by another thread at the fork is not.
+    global _lock
+    _lock = threading.Lock()
+
+
+if hasattr(os, "register_at_fork"):
+    os.register_at_fork(after_in_child=_after_fork)
+
+
+class History(object):
+    """One named history (a check's ``history:``; ``[A-Za-z0-9_.-]+``)."""
+
+    __slots__ = ("name",)
+
+    def __init__(self, name):
+        self.name = str(name)
+
+    def invoke(self, proc, f, *args):
+        """Record the invocation of ``f(args...)`` by process ``proc`` and return the operation.
+
+        ``proc`` is an int or a token without spaces. ``args`` are tokens: encode free-form
+        values with ``enc`` (``ver``, ``list_value`` and ``NIL`` help); ints are written in
+        decimal, bytes as they are.
+        """
+        op = Op(self, _token(proc, "process"), str(f), tuple(_token(a) for a in args))
+        _write(self.name, op.proc, "invoke", op.f, op.args)
+        return op
+
+    def record(self, proc, typ, f, *args):
+        """Write one raw record (for programs that keep their own bookkeeping)."""
+        _write(self.name, _token(proc, "process"), str(typ), str(f), [_token(a) for a in args])
+
+    def __repr__(self):
+        return "History(%r)" % (self.name,)
+
+
+class Op(object):
+    """An invoked operation waiting for its completion."""
+
+    __slots__ = ("history", "proc", "f", "args")
+
+    def __init__(self, history, proc, f, args):
+        self.history = history
+        self.proc = proc
+        self.f = f
+        self.args = args
+
+    def ok(self, *args):
+        """A successful completion: the results in the invocation's layout (a read lists
+        ``<key> <value>`` pairs, a txn its micro-ops with read results); with no args the
+        invocation's are repeated."""
+        _write(self.history.name, self.proc, "ok", self.f, [_token(a) for a in args] if args else self.args)
+
+    def fail(self):
+        """The operation definitely had no effect."""
+        _write(self.history.name, self.proc, "fail", self.f, self.args)
+
+    def info(self):
+        """The outcome is unknown (it may take effect at any later time, or never)."""
+        _write(self.history.name, self.proc, "info", self.f, self.args)
+
+    def __repr__(self):
+        return "Op(%r, %r, %r, %r)" % (self.history.name, self.proc, self.f, self.args)

hydo_assert-0.2.0.dist-info/METADATA

@@ -0,0 +1,238 @@
+Metadata-Version: 2.4
+Name: hydo-assert
+Version: 0.2.0
+Summary: Assertion SDK for programs tested under hydo, a deterministic hypervisor (always/sometimes properties, BUGGIFY fault points, bounded liveness, operation histories)
+License-Expression: Apache-2.0
+Project-URL: Homepage, https://github.com/kakoc/hydo
+Project-URL: Documentation, https://github.com/kakoc/hydo/tree/main/sdk/python#readme
+Project-URL: Repository, https://github.com/kakoc/hydo
+Project-URL: Issues, https://github.com/kakoc/hydo/issues
+Keywords: testing,assertions,deterministic,fault-injection,simulation,hydo
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Topic :: Software Development :: Testing
+Classifier: Typing :: Typed
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: license-file
+
+# hydo-assert: the Python assertion SDK
+
+A Python program running under hydo (the deterministic hypervisor of
+[github.com/kakoc/hydo](https://github.com/kakoc/hydo)) uses this package to say what must be
+true and what should happen at least once. It writes the same console records as the Go SDK
+(`sdk/go`), byte for byte, with the same deduplication rules, so `hydo run` and the explorer
+(`hydo explore`) read them unchanged. The wire format and the verdict
+rules are in `hydo/ASSERTIONS.md` of that repository; paths below are relative to it.
+
+- Distribution name `hydo-assert`, import name `hydo_assert`.
+- Standard library only; Python 3.8 or later; thread-safe and safe to call from asyncio code.
+- Install it from PyPI (`pip install hydo-assert`), or from a checkout (`pip install ./sdk/python`),
+  or put `sdk/python/src` on `PYTHONPATH`, or copy `src/hydo_assert/` into the guest image (the
+  `hydo/onboard/examples/python-kv` example does that).
+
+## Use
+
+```python
+import hydo_assert as ha
+
+# Declare at module level: the catalog is complete once the module is imported.
+ACKED = ha.always("kv.acked_durable", "every acknowledged PUT reads back with its value")
+PARSES = ha.always_or_unreachable("kv.log_parses", "every complete log line parses on replay")
+SIZE = ha.always("kv.log_size", "the log holds at most 10000 entries")
+REPLAYED = ha.sometimes("kv.recovered", "the server replayed a non-empty log at start")
+TORN = ha.reachable("kv.torn_tail", "the log ended in a partial line")
+BAD = ha.unreachable("kv.bad_command", "the server got a command it does not know")
+BACK = ha.eventually("kv.back", "the server answers within 5 s", 5.0)        # seconds or timedelta
+LOST = ha.buggify("kv.put.lost_reply", "the PUT is logged but its reply is lost")
+
+ha.catalog()                                       # once, early: the HYDO-ASSERT-DECL lines
+ACKED.check(got == want, {"key": k, "got": got})   # returns bool(cond)
+REPLAYED.check(n > 0, {"entries": n})
+TORN.hit({"bytes": len(tail)})
+BAD.hit()
+SIZE.cmp(n, "<=", 10000)                           # details: left, op, right
+if LOST.fire({"key": k}):                          # BUGGIFY fault point
+    return
+BACK.await_cond(lambda: ping() == "PONG", poll=0.2)   # blocks; one record
+w = BACK.begin(); ...; w.done()                    # or: anchor now, condition true now / w.expire()
+ha.setup_complete()                                # HYDO-SETUP-COMPLETE
+```
+
+In asyncio code use `await BACK.await_async(cond, poll)`: `cond` may be a plain function or an
+`async def`, and the wait between checks is `asyncio.sleep`. Every other call is a short write
+to the console under one process-wide lock that is never held across a blocking call or an
+`await`, so it is safe from coroutines and from threads.
+
+| Go SDK (`hydoassert`) | Python (`hydo_assert`) |
+|---|---|
+| `Always(id, msg)`, `AlwaysOrUnreachable`, `Sometimes`, `Reachable`, `Unreachable` | `always(id, msg)`, `always_or_unreachable`, `sometimes`, `reachable`, `unreachable` (return an `Assertion`) |
+| `a.Check(cond, d)`, `a.Hit(d)` | `a.check(cond, details=None)`, `a.hit(details=None)` |
+| `a.Cmp(left, op, right, d)` | `a.cmp(left, op, right, details=None)` (`op` is one of `<`, `<=`, `==`, `!=`, `>=`, `>`) |
+| `Eventually(id, msg, within)`, `l.Await(cond, poll, d)`, `l.Begin()`, `w.Done(d)`, `w.Expire(d)` | `eventually(id, msg, within)`, `l.await_cond(cond, poll, details=None)`, `await l.await_async(cond, poll, details=None)`, `l.begin()`, `w.done(details=None)`, `w.expire(details=None)` |
+| `Buggify(id, msg)`, `p.Fire(d)` | `buggify(id, msg)`, `p.fire(details=None)` |
+| `Catalog()`, `SetupComplete()` | `catalog()`, `setup_complete()` |
+| `D{...}` | any mapping (a `dict`); `hydo_assert.D` is `dict` |
+
+The naming follows the other SDKs (`sdk/js`, `sdk/rust`): the Go names in Python's snake case,
+and `await_cond` / `await_async` for Go's `Await`. That table, `Liveness`, `Watch` and `Point`
+(the classes the calls return) and the history recorder below are the whole API: a comparison
+has one form, `cmp` with its operator, and names that start with `_` (the modules `_core`,
+`_buggify`, `_eventually`, `_json`, `_sink`) are the package's own.
+
+## Records, deduplication, catalog
+
+- Records go to `/dev/ttyS0` (opened once, `O_WRONLY|O_APPEND|O_NOCTTY`, one `write` per
+  record). `HYDO_ASSERT_OUT=<path>` writes to that existing file, `stderr` to standard error
+  (plain logging outside hydo), `off` nowhere, and `logging` (Python only) logs each record line
+  at INFO on the logger `hydo_assert`. If the file cannot be opened, standard error is used.
+- A process writes each (assertion, outcome) pair once: the first pass and the first failure,
+  with the details of that evaluation. A `sometimes` that evaluated false is never written.
+  `unreachable` is written with `ok:false`. A record whose details hold a NaN or an infinity is
+  not written at all, but still counts as written (as in Go, where `json.Marshal` fails after
+  the pair was marked).
+- The catalog (`catalog()`) lists every declared assertion in declaration order: the order in
+  which the declaring statements ran, which for module-level declarations is the import order.
+  A module that is never imported contributes nothing; import it before calling `catalog()`.
+  Call `catalog()` in the process whose console output is collected for each run (for a
+  server started before the explorer's snapshot point, that is a client or the oracle, not the
+  server; see the example).
+- Details are encoded exactly as Go's `encoding/json` encodes the equivalent Go value: keys in
+  UTF-8 byte order, `<`, `>`, `&`, U+2028 and U+2029 escaped, other non-ASCII text raw, Go's
+  float format (`1e+21`, `1.5e-7`, `3` for `3.0`, `-0`). The caller's dict is never changed
+  (Go adds `left`/`op`/`right`, `hit`, `elapsed_ms` to the caller's map; Python adds them to a
+  copy, which gives the same record).
+- Python values Go has no form for: a tuple is an array; `bytes` is a base64 string (as Go
+  encodes `[]byte`); a set is an array sorted by encoded element; integer dict keys are written
+  in decimal; any other object is the string `str(obj)`. A lone surrogate (an undecodable byte
+  read with `surrogateescape`) is written as `\ufffd`, as the pinned guest Go 1.26.5 writes an
+  invalid UTF-8 byte (Go 1.27 writes a raw U+FFFD instead).
+- `details` that is not a mapping is wrapped as `{"value": details}`.
+- After `os.fork()` the child keeps the parent's deduplication state (it is one program's
+  history) and gets fresh locks.
+
+## BUGGIFY
+
+Same decisions as the Go SDK: configured by `$HYDO_BUGGIFY`, or else the file
+`$HYDO_BUGGIFY_FILE` (default `/tmp/hydo-buggify`), holding
+`<seed-hex>[,<enable-permille>[,<fire-permille>]]` (defaults 250 and 250, FoundationDB's
+values), parsed as Go's `strconv.ParseUint` does (no `0x`, no sign, no spaces inside a field;
+an unparsable seed leaves BUGGIFY off, an unparsable permille keeps its default). It is read
+once, at the first evaluation of any point, which also writes
+`HYDO-BUGGIFY {"seed":..,"enable_pm":..,"fire_pm":..,"enabled":[..]}`. A point is enabled
+for the run when `splitmix64(seed ^ fnv1a(id)) % 1000 < enable`; its k-th evaluation fires
+when `splitmix64(splitmix64(seed ^ fnv1a(id)) + k·0x9e3779b97f4a7c15) % 1000 < fire`. Each
+point is also a `sometimes` property `buggify.<id>` ("fault point fired: <msg>"), recorded at
+its first firing with `{"hit": k}`. Without a configuration every point returns False and has
+no other effect. Under hydo the schedule token `B=<seed>` (`hydo explore --buggify`) reaches the
+file through the guest init: an onboarded project gets it with `buggify: true` in its
+`hydo.yaml` (`hydo/onboard/MANIFEST.md`).
+
+## History recorder
+
+The module `hydo_assert.history` records operation histories for hydo's host-side checkers
+(linearizability of a register or compare-and-set object per key, and Elle-style list-append;
+the format and the checkers are in `hydo/HISTORIES.md`). It writes the same `HYDO-HIST` lines as
+the Go recorder (`sdk/go/hydohist`), byte for byte except the time field. It is a separate
+module: `import hydo_assert` does not load it, so the assertion records are unchanged.
+
+```python
+from hydo_assert import history as hh
+
+kv = hh.History("kv")
+op = kv.invoke(3, "write", "k1", hh.enc(v))      # process 3, before the request
+try:
+    rev = put("k1", v)
+    op.ok("k1", hh.ver(v, rev))                  # the version the store assigned, if any
+except Rejected:
+    op.fail()                                    # it definitely had no effect
+except Exception:
+    op.info()                                    # a timeout: the outcome is unknown
+kv.invoke(3, "read", "k1").ok("k1", hh.value_or_nil(get("k1")))   # None means absent
+
+la = hh.History("la")
+tx = la.invoke(4, "txn", hh.append_mop("x", "1"), hh.read_mop("y"))
+tx.ok(hh.append_mop("x", "1"), hh.read_result_mop("y", "1", "2"))
+```
+
+| Go (`hydohist`) | Python (`hydo_assert.history`) |
+|---|---|
+| `New(name)` | `History(name)` |
+| `h.Invoke(proc, f, args...)`, `h.Record(proc, typ, f, args...)` | `h.invoke(proc, f, *args)`, `h.record(proc, typ, f, *args)` |
+| `op.Ok(args...)`, `op.Fail()`, `op.Info()` | `op.ok(*args)` (no args repeats the invocation's), `op.fail()`, `op.info()` |
+| `Enc`, `Ver`, `ValOrNil(v, ok)`, `List` | `enc`, `ver`, `value_or_nil(v)` (None means absent), `list_value` |
+| `Append`, `Read`, `ReadResult`, `Nil` | `append_mop`, `read_mop`, `read_result_mop`, `NIL` |
+
+- `list_value` has a longer name than Go's `List` so that it does not hide the builtin `list`
+  for a program that uses `from hydo_assert.history import *`. The micro-op helpers have the
+  Rust SDK's names.
+- A process is an int or a token without spaces. Arguments are tokens: a `str` is written as
+  it is (encode free-form values with `enc`), an `int` is written in decimal, and `bytes` are
+  written as they are. Versions are int64 values; a value outside that range raises
+  `ValueError`, and a value that is not an int (including `bool`) raises `TypeError`.
+- Records go to `/dev/console`. `HYDO_HIST_OUT=<path>` appends to that file and creates it if
+  it is missing (mode 0644), `stderr` writes to standard error, and `off` writes nothing. If the
+  file cannot be opened, standard error is used. The setting is read once, at the first record,
+  and is separate from `HYDO_ASSERT_OUT`.
+- Each record is one `os.write` call made under a lock, so threads never interleave lines. The
+  time field is `time.monotonic_ns()` (CLOCK_MONOTONIC on Linux, deterministic under hydo). It
+  is read under the lock, so the times of successive lines never decrease; Go reads it just
+  before its lock, and the line format is the same. A forked child gets a new lock and keeps the
+  descriptor.
+- Text is written as UTF-8. A `str` is encoded with the `surrogateescape` rule, so a string
+  that came from bytes that way (`os.fsdecode`, `sys.argv`, `os.environ`, or `enc` of bytes)
+  gives back its original bytes. Any other lone surrogate is written as U+FFFD. `enc` of
+  `bytes` keeps invalid UTF-8 bytes as they are, as Go's `Enc` does, and returns them as
+  surrogateescape characters.
+- A process has at most one operation in flight: give each concurrent client (thread or task)
+  its own process number. Record the invocation before sending the request and the completion
+  after the reply, because the checkers order operations by the position of their records.
+
+## Determinism
+
+The records are a pure function of the program's evaluation sequence: no clocks (except the
+guest's monotonic clock for `eventually`, which hvx makes deterministic), no host state,
+catalog in declaration order, sorted keys. A Python program is itself deterministic under hydo:
+the guest CRNG is seeded identically every run, so even the hash seed is the same; setting
+`PYTHONHASHSEED=0` makes that independent of the CRNG. `PYTHONDONTWRITEBYTECODE=1` avoids
+writing `.pyc` files on the guest's read-only root.
+
+## Tests
+
+- `python3 -m unittest discover -s sdk/python/tests`: the encoder (Go's float and string
+  forms), deduplication, details not mutated, NaN, catalog order, 16 threads writing 2000
+  evaluations each without an interleaved line, asyncio `eventually`, fork, BUGGIFY decisions
+  and rates. Passes on Python 3.8.20 and 3.15.0.
+- `tests/test_cases.py` (run by the same `unittest` command): the shared cases (`sdk/cases`,
+  written by the reference SDK, `sdk/rust`; format and rules in `sdk/rust/README.md`, "The
+  shared cases"). For every case and run it starts itself as a child process, makes the
+  case's calls with this package and `hydo_assert.history`, and compares the bytes the sink
+  received and the calls' results with the case's files: every assertion type, comparisons,
+  details with tricky values (invalid UTF-8 as `surrogateescape` characters), the catalog,
+  `eventually`, BUGGIFY under 18 configurations, `HYDO_ASSERT_OUT`, and the
+  history records with every helper and `HYDO_HIST_OUT` setting. Cases that need a float32
+  (`f32`) are skipped and listed. To add a case, add it to the Rust SDK's
+  `tests/cases/defs.rs` and run `HYDO_BLESS=1 cargo test --test cases` there; this test then
+  runs it. A format change starts in the Rust SDK too: after it is blessed, this test fails on
+  the lines this package must change. No other language is needed to run it. Passes on Python
+  3.8.20 and 3.15.0.
+- `tests/test_history.py` (run by the same `unittest` command): the exact lines of the Go
+  recorder's own unit test, the encoding of every byte class, the argument checks, the sink
+  settings, one `os.write` per record, 8 threads writing 400 records each without an
+  interleaved line, and fork.
+- The files of `src/hydo_assert/` are copied into the python-kv example's images, so a change
+  to any of them changes those images' bytes and every python-kv fingerprint (the last such
+  change, a reworded comment in `_core.py`, re-recorded them in milestone 157;
+  docs/REBASELINE.md has the values).
+
+## Limits
+
+- No call-site form that registers itself before it runs (the Rust SDK's macros do that with a
+  linker section). A Python assertion is in the catalog once the statement that declares it has
+  run, so declare at module level.
+- `cmp` compares any two Python values that support the operator; values that cannot be
+  compared evaluate to false. Go's `Cmp` takes only `int64`.

hydo_assert-0.2.0.dist-info/RECORD

@@ -0,0 +1,13 @@
+hydo_assert/__init__.py,sha256=PIsdaxsu7pYz9O0IazFp3FXxYRXqD3hZgylfVTRcJso,2251
+hydo_assert/_buggify.py,sha256=83PHDJ-A-9ekGroZYsrlN_Oh3GVr92nddNIwKSCXoh8,5215
+hydo_assert/_core.py,sha256=G7gEXpJKKUE6GiyAI-F5my_41Tcenu876dqlC-vU1hA,5568
+hydo_assert/_eventually.py,sha256=9vJnxwLZnmgFbj82ngszGoqoTqMzvjomOUS2P50nsZI,4244
+hydo_assert/_json.py,sha256=bJtpC2QKPEd8wpql5S5eXhfk2fUCoINIV1tKfHbvCjQ,5520
+hydo_assert/_sink.py,sha256=iEboDP_MtFoui1y4zdnCPcpugYBN98YAg4YU8aYgDQg,2536
+hydo_assert/history.py,sha256=z7O_gxpivlpRy0nCYgsqFj76QEHUjYKEA7IA_dd0WY0,10368
+hydo_assert/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+hydo_assert-0.2.0.dist-info/licenses/LICENSE,sha256=z8d0m5b2O9McPEK1xHG_dWgUBT6EfBDz6wA0F7xSPTA,11358
+hydo_assert-0.2.0.dist-info/METADATA,sha256=qnObnT7Ki0Nvb8BDqL5TwsgqmjGOZ_chnDVNh3ngRFs,15367
+hydo_assert-0.2.0.dist-info/WHEEL,sha256=mOdXR9C3wMVov7cSY8PY-XCzo3SmmWCHvGQr5csJoao,91
+hydo_assert-0.2.0.dist-info/top_level.txt,sha256=TvdT9tTbjxBQu9Qv2RRfQrJM8iKJy0eEtM-ptlVZbqY,12
+hydo_assert-0.2.0.dist-info/RECORD,,

hydo_assert-0.2.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (84.2.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+