diff --git a/xo-reader/.gitignore b/xo-reader/.gitignore
new file mode 100644
index 00000000..3d3a7826
--- /dev/null
+++ b/xo-reader/.gitignore
@@ -0,0 +1,8 @@
+# emacs workspace config
+.projectile
+# clangd working space (see emacs+lsp)
+.cache
+# typical cmake build directory (source-tree-nephew)
+.build*
+# symlink to builddir/compile_commands.json;  should be set manually in dev sandbox
+compile_commands.json
diff --git a/xo-reader/.gitrepo b/xo-reader/.gitrepo
new file mode 100644
index 00000000..da04c6dc
--- /dev/null
+++ b/xo-reader/.gitrepo
@@ -0,0 +1,12 @@
+; DO NOT EDIT (unless you know what you are doing)
+;
+; This subdirectory is a git "subrepo", and this file is maintained by the
+; git-subrepo command. See https://github.com/ingydotnet/git-subrepo#readme
+;
+[subrepo]
+	remote = git@github.com:Rconybea/xo-reader.git
+	branch = main
+	commit = cb652195d3fa3774651c746a621e16f30481c22e
+	parent = f5828f616346f52e282cf86ef8dbc5901b8f5aad
+	method = merge
+	cmdver = 0.4.9
diff --git a/xo-reader/CMakeLists.txt b/xo-reader/CMakeLists.txt
new file mode 100644
index 00000000..5c9c7885
--- /dev/null
+++ b/xo-reader/CMakeLists.txt
@@ -0,0 +1,39 @@
+# xo-reader/CMakeLists.txt
+
+cmake_minimum_required(VERSION 3.10)
+
+project(xo_reader VERSION 0.1)
+
+include(GNUInstallDirs)
+include(cmake/xo-bootstrap-macros.cmake)
+
+xo_cxx_toplevel_options3()
+
+# ----------------------------------------------------------------
+# c++ settings
+
+set(PROJECT_CXX_FLAGS "-ftemplate-backtrace-limit=0")
+#set(PROJECT_CXX_FLAGS "-fconcepts-diagnostics-depth=2")
+add_definitions(${PROJECT_CXX_FLAGS})
+
+# ----------------------------------------------------------------
+
+add_subdirectory(src/reader)
+add_subdirectory(examples)
+#add_subdirectory(utest)    # test failing, temporarily removing
+xo_export_cmake_config(${PROJECT_NAME} ${PROJECT_VERSION} ${PROJECT_NAME}Targets)
+
+# ----------------------------------------------------------------
+
+if (XO_ENABLE_EXAMPLES)
+    install(TARGETS xo_expression_repl DESTINATION bin/xo/example/reader)
+    install(TARGETS xo_expression_replxx DESTINATION bin/xo/example/reader)
+endif()
+
+# ----------------------------------------------------------------
+# docs targets depends on other library/utest/exec targets,
+# must come after them
+#
+add_subdirectory(docs)
+
+# end CMakeLists.txt
diff --git a/xo-reader/README b/xo-reader/README
new file mode 100644
index 00000000..2c4a55b7
--- /dev/null
+++ b/xo-reader/README
@@ -0,0 +1,53 @@
+1. in parser we need.. type unification?
+2. or perhaps just need to introduce type variables.
+
+3. we can't resolve type for a recursive pair of functions until we've seen both of them..
+   tho we could require letrec
+
+def foo = lambda (n : i64) { let (n == 0) then 1 else n * foo(n - 1); };
+
+strategy:
+--------
+
+while parsing def, instead of creating DefineExpr with nullptr TypeDescr:
+a. create DefineExpr with TypeVariable.
+(We have to do this because can't tell nullptr's apart,..)
+
+- generalize xo::reflect::TypeDescrBase
+
+// compose these into Expressions.
+//
+struct type_ref {
+  bool is_concrete() const { return td_ && td_->is_concrete(); }
+
+  // generated name, so we can map between types.  Don't want to create TypeDescr
+  // every time we have a typed location. there'd be a lot of them, and hard to collect
+  flatstring<11> id_;
+  // if TypeDescr is concrete (fully described), this describes it
+  TypeDescr td_;
+};
+
+// what we know about a type
+//
+struct TypeBlueprint : public Refcounted {
+  static bool equal(bp<TypeTemplate> lhs, bp<TypeTemplate> rhs);
+
+  type_ref ref_;
+
+  // additional descriptive info...
+};
+
+// effectively these are constraints?
+//
+using TypeSubstitutionMap = map<string, rp<TypeTemplate>>;
+
+will have typeunifier in parserstatemachine
+
+struct TypeUnifier {
+   // extend as unification proceeds
+   //
+   TypeSubstitutionMap substitutions_;
+};
+
+alt strategy
+-------------
diff --git a/xo-reader/cmake/xo-bootstrap-macros.cmake b/xo-reader/cmake/xo-bootstrap-macros.cmake
new file mode 100644
index 00000000..aba31169
--- /dev/null
+++ b/xo-reader/cmake/xo-bootstrap-macros.cmake
@@ -0,0 +1,35 @@
+# ----------------------------------------------------------------
+# for example:
+#   $ PREFIX=/usr/local   # for example
+#   $ cmake -DCMAKE_MODULE_PATH=prefix -DCMAKE_INSTALL_PREFIX=$PREFIX -B .build
+#
+# will get
+#   CMAKE_MODULE_PATH
+# from xo-cmake-config --cmake-module-path
+#
+# and expect .cmake macros in
+#   CMAKE_MODULE_PATH/xo_macros/xo_cxx.cmake
+# ----------------------------------------------------------------
+
+find_program(XO_CMAKE_CONFIG_EXECUTABLE NAMES xo-cmake-config REQUIRED)
+
+if ("${XO_CMAKE_CONFIG_EXECUTABLE}" STREQUAL "XO_CMAKE_CONFIG_EXECUTABLE-NOT_FOUND")
+    message(FATAL "could not find xo-cmake-config executable")
+endif()
+
+message(STATUS "XO_CMAKE_CONFIG_EXECUTABLE=${XO_CMAKE_CONFIG_EXECUTABLE}")
+
+if (NOT XO_SUBMODULE_BUILD)
+    if (("${CMAKE_MODULE_PATH}" STREQUAL "") OR ("${CMAKE_MODULE_PATH}" STREQUAL prefix))
+        # default to typical install location for xo-project-macros
+        execute_process(COMMAND ${XO_CMAKE_CONFIG_EXECUTABLE} --cmake-module-path OUTPUT_VARIABLE CMAKE_MODULE_PATH)
+        message(STATUS "CMAKE_MODULE_PATH=${CMAKE_MODULE_PATH}")
+    endif()
+endif()
+
+# needs to have been installed somewhere on CMAKE_MODULE_PATH,
+# (e.g. from xo-cmake with the same value for CMAKE_INSTALL_PREFIX)
+#
+include(xo_macros/xo_cxx)
+
+xo_cxx_bootstrap_message()
diff --git a/xo-reader/cmake/xo_readerConfig.cmake.in b/xo-reader/cmake/xo_readerConfig.cmake.in
new file mode 100644
index 00000000..94b1811e
--- /dev/null
+++ b/xo-reader/cmake/xo_readerConfig.cmake.in
@@ -0,0 +1,9 @@
+@PACKAGE_INIT@
+
+include(CMakeFindDependencyMacro)
+find_dependency(xo_expression)
+find_dependency(xo_tokenizer)
+#find_dependency(subsys)
+include("${CMAKE_CURRENT_LIST_DIR}/@PROJECT_NAME@Targets.cmake")
+include("${CMAKE_CURRENT_LIST_DIR}/@PROJECT_NAME@Share.cmake")
+check_required_components("@PROJECT_NAME@")
diff --git a/xo-reader/docs/CMakeLists.txt b/xo-reader/docs/CMakeLists.txt
new file mode 100644
index 00000000..05b7681c
--- /dev/null
+++ b/xo-reader/docs/CMakeLists.txt
@@ -0,0 +1,7 @@
+# xo-reader/docs/CMakeLists.txt
+
+xo_doxygen_collect_deps()
+xo_docdir_doxygen_config()
+xo_docdir_sphinx_config(
+    index.rst example.rst install.rst implementation.rst
+)
diff --git a/xo-reader/docs/README b/xo-reader/docs/README
new file mode 100644
index 00000000..6aff5d41
--- /dev/null
+++ b/xo-reader/docs/README
@@ -0,0 +1,41 @@
+standalone build
+
+        +-----------------------------------------------+
+        | cmake                                         |
+        |   CMakeLists.txt                              |
+        |   $PREFIX/share/cmake/xo_macros/xo_cxx.cmake  |
+        +-----------------------------------------------+
+           |
+           |                                                  +----------------------+
+           +------------------------------------------------->| .build/docs/Doxyfile |
+           |                                                  +----------------------+
+           |                                                     ^
+           |                                 (cmake)             |
+           |                                        /------------/
+           |                                        |
+           |     +---------------------------------------+          +-----------------+
+           +---->| doxygen                               |--------->| .build/docs/dox |
+           |     |   $PREFIX/share/xo-macros/Doxyfile.in | (doxygen)|   +- html/      |
+           |     +---------------------------------------+          |   +- xml/       |
+           |                                                        +-----------------+
+           |                                                             |
+           |                                                             |(sphinx)
+           |                                                             |
+           |                                                             v
+           |     +---------------------------------------+        +--------------------+
+           \---->| sphinx                                |------->| .build/docs/sphinx |
+                 |   +- conf.py                          |        |   +- html/         |
+                 |   +- _static/                         |        +--------------------+
+                 |   +- *.rst                            |
+                 +---------------------------------------+
+
+umbrella build relies on top-level cmake macros
+
+files
+
+   README            this file
+   CMakeLists.txt    build entry point
+   conf.py           sphinx config
+   _static           static files for sphinx
+
+   index.rst         toplevel sphinx document; entry point
diff --git a/xo-reader/docs/_static/README b/xo-reader/docs/_static/README
new file mode 100644
index 00000000..8230095c
--- /dev/null
+++ b/xo-reader/docs/_static/README
@@ -0,0 +1 @@
+add any static {.html, .js, ..} files for sphinx to pickup here
\ No newline at end of file
diff --git a/xo-reader/docs/_static/img/favicon.ico b/xo-reader/docs/_static/img/favicon.ico
new file mode 100644
index 00000000..15da2145
Binary files /dev/null and b/xo-reader/docs/_static/img/favicon.ico differ
diff --git a/xo-reader/docs/conf.py b/xo-reader/docs/conf.py
new file mode 100644
index 00000000..a598d229
--- /dev/null
+++ b/xo-reader/docs/conf.py
@@ -0,0 +1,39 @@
+# Configuration file for the Sphinx documentation builder.
+#
+# For the full list of built-in configuration values, see the documentation:
+# https://www.sphinx-doc.org/en/master/usage/configuration.html
+
+# -- Project information -----------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information
+
+project = 'xo reader documentation'
+copyright = '2024-2025, Roland Conybeare'
+author = 'Roland Conybeare'
+
+# -- General configuration ---------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration
+
+#extensions = []
+extensions = [ "breathe",
+               "sphinx.ext.mathjax",     # inline math
+               "sphinx.ext.autodoc",     # generate info from docstrings
+               "sphinxcontrib.ditaa",    # diagrams-through-ascii-art
+               "sphinxcontrib.plantuml"  # text -> uml diagrams
+              ]
+
+# note: breathe requires doxygen xml output -> must have GENERATE_XML = YES in Doxyfile.in
+#       match project name in Doxyfile.in
+breathe_default_project = "xodoxxml"
+
+templates_path = ['_templates']
+exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store']
+
+pygments_style = 'sphinx'
+
+# -- Options for HTML output -------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output
+
+#html_theme = 'alabaster'
+html_theme = 'sphinx_rtd_theme'
+html_static_path = ['_static']
+html_favicon = '_static/img/favicon.ico'
diff --git a/xo-reader/docs/example.rst b/xo-reader/docs/example.rst
new file mode 100644
index 00000000..12a3b1c2
--- /dev/null
+++ b/xo-reader/docs/example.rst
@@ -0,0 +1,45 @@
+.. _examples:
+
+.. toctree::
+   :maxdepth: 2
+
+Examples
+========
+
+See ``xo-reader/examples`` for built examples
+
+.. code-block:: cpp
+   :linenos:
+
+    #include "xo/reader/reader.h"
+
+    int
+    main() {
+        using namespace xo::scm;
+        using namespace std;
+
+        reader rdr;
+        rdr.begin_translation_unit();
+
+        bool eof = false;
+        while (!eof) {
+            auto input = ins.read_some();
+
+            eof = ins.eof();
+
+            for (auto rem = input; !rem.empty();) {
+                // res: (parsed-expr, used)
+                auto [expr, rem2, _] = rdr.read_expr(rem, eof);
+
+                if (expr) {
+                     cout << expr << endl;
+                }
+
+                rem = rem.suffix_after(rem2);
+            }
+        }
+
+        if (rdr.has_prefix()) {
+            cout << "error: unparsed input after expression" << endl;
+        }
+    }
diff --git a/xo-reader/docs/implementation.rst b/xo-reader/docs/implementation.rst
new file mode 100644
index 00000000..d148c6a9
--- /dev/null
+++ b/xo-reader/docs/implementation.rst
@@ -0,0 +1,137 @@
+.. _implementation:
+
+.. toctree::
+   :maxdepth: 2
+
+Components
+==========
+
+Library dependency tower for *xo-reader*:
+
+.. ditaa::
+
+    +------------------------------------------+
+    |                xo_reader                 |
+    +-------------------------+----------------+
+    |      xo_expression      |                |
+    +-------------------------+                |
+    |      xo_reflect         |  xo_tokenizer  |
+    +-----------+-------------+                |
+    |           |  xo_refcnt  |                |
+    | xo_subsys +-------------+----------------+
+    |           |          xo_indentlog        |
+    +-----------+------------------------------+
+
+Install instructions :doc:`here<install>`
+
+Abstraction tower for *xo-reader* components:
+
+.. ditaa::
+    :--scale: 0.85
+
+    +--------------------------------+
+    |             reader             |
+    +--------------------------------+
+    |             parser             |
+    +----------------+---------------+
+    | exprstatestack | envframestack |
+    +----------------+---------------+
+    |   exprstate    |   envframe    |
+    +----------------+---------------+
+
+``exprstate`` provides an abstract api.
+We use runtime polymorphism to represent concrete parsing states.
+Different expression types inherit from ``exprstate`` to encapsulate
+parsing for each expression type.
+
+.. uml::
+    :caption: exprstate
+    :scale: 99%
+    :align: center
+
+    class exprstate {
+    }
+
+    class define_xs {
+    }
+
+    exprstate <|-- define_xs
+
+    class lambda_xs {
+    }
+
+    exprstate <|-- lambda_xs
+
+    class exprseq_xs {
+    }
+
+    exprstate <|-- exprseq_xs
+
+    class let1_xs {
+    }
+
+    exprstate <|-- let1_xs
+
+    class paren_xs {
+    }
+
+    exprstate <|-- paren_xs
+
+    class sequence_xs {
+    }
+
+    exprstate <|-- sequence_xs
+
+There are also classes for nested state machines:
+
+.. uml::
+    :caption: exprstate
+    :scale: 99%
+    :align: center
+
+    class exprstate {
+    }
+
+    class progress_xs {
+    }
+
+    exprstate <|-- progress_xs
+
+    class expect_symbol_xs {
+    }
+
+    exprstate <|-- expect_symbol_xs
+
+    class expect_type_xs {
+    }
+
+    exprstate <|-- expect_type_xs
+
+    class expect_expr_xs {
+    }
+
+    exprstate <|-- expect_expr_xs
+
+    class expect_formal_xs {
+    }
+
+    exprstate <|-- expect_formal_xs
+
+    class expect_formal_arglist_xs {
+    }
+
+    exprstate <|-- expect_formal_arglist_xs
+
+Putting these in context:
+
+.. list-table:: Schematika Parsing States
+    :widths: 15 30
+    :header-rows: 1
+
+    * - exprstate class
+      - target syntax
+    * - define_xs
+      - ``def foo : f64 = 1;``, ``def sq = lambda (x : i64) { x * x; }``
+    * - progress_xs
+      - possibly-incomplete arithmetic expressions
+        ``(a + b) * 7``..
diff --git a/xo-reader/docs/index.rst b/xo-reader/docs/index.rst
new file mode 100644
index 00000000..04446576
--- /dev/null
+++ b/xo-reader/docs/index.rst
@@ -0,0 +1,14 @@
+.. xo-reader documentation master file.
+
+xo-reader documentation
+=======================
+
+xo-reader provides a parser for the Schematika language.
+
+.. toctree::
+   :maxdepth: 2
+   :caption: xo-reader contents
+
+   install
+   example
+   implementation
diff --git a/xo-reader/docs/install.rst b/xo-reader/docs/install.rst
new file mode 100644
index 00000000..0f008815
--- /dev/null
+++ b/xo-reader/docs/install.rst
@@ -0,0 +1,146 @@
+.. _install:
+
+.. toctree::
+   :maxdepth: 2
+
+Source
+======
+
+Source code lives on github `here`_
+
+.. _here: https://github.com/rconybea/xo-reader
+
+To clone from git:
+
+.. code-block:: bash
+
+    git clone https://github.com/rconybea/xo-reader
+
+Tested with gcc 13.3
+
+Install
+=======
+
+One-step Install
+----------------
+
+Install along with the rest of *XO* from `xo-umbrella2 source`_:
+see install instructions for xo-umrbella2
+
+.. _xo-umbrella2 source: https://github.com/rconybea/xo-umbrella2
+
+Essential Xo Dependencies
+-------------------------
+
+``xo-reader`` uses several supporting libraries from the *XO* project:
+
+- `xo-expression source`_ (Schematika AST representation)
+- `xo-tokenizer source`_ (Schematika lexer)
+- `xo-reflect source`_ (reflection library)
+- `xo-refcnt source`_ (reference-counting library)
+- `xo-indentlog source`_ (structured logging)
+- `xo-subsys source`_ (utility library)
+- `xo-cmake source`_ (shared cmake macros)
+
+.. _xo-expression source: https://github.com/rconybea/xo-expression
+.. _xo-tokenizer source: https://github.com/rconybea/xo-tokenizer
+.. _xo-reflect source: https://github.com/rconybea/xo-reflect
+.. _xo-refcnt source: https://github.com/rconybea/refcnt
+.. _xo-indentlog source: https://github.com/rconybea/indentlog
+.. _xo-subsys source: https://github.com/rconybea/subsys
+.. _xo-cmake source: https://github.com/rconybea/xo-cmake
+
+Building from source
+--------------------
+
+Install scripts for XO libraries depend on helper scripts installed from `xo-cmake`.
+
+Preamble:
+
+.. code-block:: bash
+
+    mkdir -p ~/proj/xo
+    cd ~/proj/xo
+
+    git clone https://github.com/rconybea/xo-cmake
+
+    PREFIX=/usr/local  # ..or desired installation prefix
+
+    # want PREFIX/bin in PATH to use xo-cmake helpers
+    PATH=$PREFIX/bin:$PATH
+
+Install `xo-cmake`:
+
+.. code-block:: bash
+
+    cmake -B xo-cmake/.build -S xo-cmake
+    cmake --install xo-cmake/.build
+
+Install dependencies in topological order:
+
+.. code-block:: bash
+
+    xo-build --clone --configure --build --install xo-indentlog
+    xo-build --clone --configure --build --install xo-subsys
+    xo-build --clone --configure --build --install xo-refcnt
+    xo-build --clone --configure --build --install xo-reflect
+    xo-build --clone --configure --build --install xo-expression
+    xo-build --clone --configure --build --install xo-tokenizer
+    xo-build --clone --configure --build --install xo-reader
+
+Directories under ``PREFIX`` will then contain:
+
+.. code-block::
+
+    PREFIX
+    +- bin
+    |  +- xo-build
+    |  +- xo-cmake-config
+    |  \- xo-cmake-lcov-harness
+    +- include
+    |  \- xo
+    |     +- cxxutil/
+    |     +- expression/
+    |     +- indentlog/
+    |     +- reader/
+    |     +- refcnt/
+    |     +- reflect/
+    |     +- subsys/
+    |     \- tokenizer/
+    +- lib
+    |  +- cmake
+    |  |  +- indentlog/
+    |  |  +- refcnt/
+    |  |  +- reflect/
+    |  |  +- subsys/
+    |  |  +- xo_expression/
+    |  |  +- xo_reader/
+    |  |  \- xo_tokenizer/
+    |  +- lib*.so
+    +- share
+       +- cmake
+       |  \- xo_macros
+       |     +- code-coverage.cmake
+       |     +- xo-project-macros.cmake
+       |     \- xo_cxx.cmake
+       +- etc
+       |  \- xo
+       |     \- subsystem-list
+       \- xo-macros
+          +- Doxyfile.in
+          +- gen-ccov.in
+          \- xo-bootstrap-macros.cmake
+
+CMake Support
+-------------
+
+To use built-in cmake support, when using ``xo-reader`` from another project:
+
+Make sure ``PREFIX/lib/cmake`` is searched by cmake (for example include it in ``CMAKE_PREFIX_PATH``)
+
+Add to your ``CMakeLists.txt``:
+
+.. code-block:: cmake
+
+    FindPackage(xo_reader CONFIG REQUIRED)
+    target_link_libraries(mytarget INTERFACE xo_reader)
diff --git a/xo-reader/examples/CMakeLists.txt b/xo-reader/examples/CMakeLists.txt
new file mode 100644
index 00000000..faab007d
--- /dev/null
+++ b/xo-reader/examples/CMakeLists.txt
@@ -0,0 +1,2 @@
+add_subdirectory(exprrepl)
+add_subdirectory(exprreplxx)
diff --git a/xo-reader/examples/exprrepl/CMakeLists.txt b/xo-reader/examples/exprrepl/CMakeLists.txt
new file mode 100644
index 00000000..003c9cb0
--- /dev/null
+++ b/xo-reader/examples/exprrepl/CMakeLists.txt
@@ -0,0 +1,11 @@
+# xo-reader/example/exprrepl/CMakeLists.txt
+
+set(SELF_EXE xo_expression_repl)
+set(SELF_SRCS exprrepl.cpp)
+
+if (XO_ENABLE_EXAMPLES)
+    xo_add_executable(${SELF_EXE} ${SELF_SRCS})
+    xo_self_dependency(${SELF_EXE} xo_reader)
+endif()
+
+# end CMakeLists.txt
diff --git a/xo-reader/examples/exprrepl/expreplxx.cpp b/xo-reader/examples/exprrepl/expreplxx.cpp
new file mode 100644
index 00000000..e69de29b
diff --git a/xo-reader/examples/exprrepl/exprrepl.cpp b/xo-reader/examples/exprrepl/exprrepl.cpp
new file mode 100644
index 00000000..64e1c977
--- /dev/null
+++ b/xo-reader/examples/exprrepl/exprrepl.cpp
@@ -0,0 +1,91 @@
+/** @file exprrepl.cpp **/
+
+#include "xo/reader/reader.hpp"
+#include <iostream>
+#include <unistd.h> // for isatty
+
+bool repl_getline(bool interactive, std::size_t parser_stack_size, std::istream& in, std::ostream& out, std::string& input)
+{
+    using namespace std;
+
+    if (interactive) {
+        if (parser_stack_size <= 1)
+            out << "> ";
+        else
+            out << ". ";
+        std::flush(out);
+    }
+
+    bool retval = static_cast<bool>(getline(in, input));
+
+    if (retval) {
+        cerr << "got reval->true" << endl;
+
+        // interactive only: treat ^@ (C-RET) as ;RET
+        if ((input.size() > 0) && ((*input.rbegin()) == '\0'))
+        {
+            cerr << "got ^@" << endl;
+
+            *input.rbegin() = ';';
+        }
+
+        // want reader to see newline, it's syntax
+        input.push_back('\n');
+    } else {
+        cerr << "got retval->false" << endl;
+    }
+
+    return retval;
+}
+
+int
+main() {
+    using namespace xo::scm;
+    using namespace std;
+
+    using span_type = xo::scm::span<const char>;
+
+    bool interactive = isatty(STDIN_FILENO);
+    bool c_debug_flag = false;
+
+    auto toplevel_symtab = GlobalSymtab::make_empty();
+
+    reader rdr(toplevel_symtab, c_debug_flag);
+    rdr.begin_interactive_session();
+
+    string input_str;
+
+    bool eof = false;
+
+    span_type input;
+    std::size_t parser_stack_size = 0;
+
+    while (repl_getline(interactive, parser_stack_size, cin, cout, input_str)) {
+        input  = span_type::from_string(input_str);
+
+        while (!input.empty()) {
+            auto [expr, consumed, psz, error] = rdr.read_expr(input, eof);
+
+            if (expr) {
+                cout << expr << endl;
+            } else if (error.is_error()) {
+                cout << "parsing error: " << endl;
+                error.report(cout);
+
+                break;
+            }
+
+            input = input.after_prefix(consumed);
+            parser_stack_size = psz;
+        }
+    }
+
+    auto [expr, _1, _2, error] = rdr.read_expr(input, true /*eof*/);
+
+    if (expr) {
+        cout << expr << endl;
+    } else if (error.is_error()) {
+        cout << "parsing error: " << endl;
+        error.report(cout);
+    }
+}
diff --git a/xo-reader/examples/exprreplxx/CMakeLists.txt b/xo-reader/examples/exprreplxx/CMakeLists.txt
new file mode 100644
index 00000000..c7365632
--- /dev/null
+++ b/xo-reader/examples/exprreplxx/CMakeLists.txt
@@ -0,0 +1,16 @@
+# xo-reader/example/exprreplxx/CMakeLists.txt
+
+set(SELF_EXE xo_expression_replxx)
+set(SELF_SRCS exprreplxx.cpp)
+
+if (XO_ENABLE_EXAMPLES)
+    xo_add_executable(${SELF_EXE} ${SELF_SRCS})
+    xo_self_dependency(${SELF_EXE} xo_reader)
+    xo_external_target_dependency(${SELF_EXE} replxx replxx::replxx)
+
+    find_package(Threads REQUIRED)
+    target_link_libraries(${SELF_EXE} PUBLIC Threads::Threads)
+    #xo_external_target_dependency(${SELF_EXE} Threads Threads::Threads)
+endif()
+
+# end CMakeLists.txt
diff --git a/xo-reader/examples/exprreplxx/exprreplxx.cpp b/xo-reader/examples/exprreplxx/exprreplxx.cpp
new file mode 100644
index 00000000..e9d8079c
--- /dev/null
+++ b/xo-reader/examples/exprreplxx/exprreplxx.cpp
@@ -0,0 +1,143 @@
+/** @file exprreplxx.cpp **/
+
+#include "xo/reader/reader.hpp"
+#include <replxx.hxx>
+#include <iostream>
+#include <unistd.h> // for isatty
+
+// presumeably replxx assumes input is a tty
+//
+bool replxx_getline(bool interactive,
+                    std::size_t parser_stack_size,
+                    replxx::Replxx & rx,
+                    std::string& input)
+{
+    using namespace std;
+
+    char const * prompt = "";
+
+    if (interactive) {
+        if (parser_stack_size <= 1)
+            prompt = "> ";
+        else
+            prompt = ". ";
+    }
+
+    const char * input_cstr = rx.input(prompt);
+
+    bool retval = (input_cstr != nullptr);
+
+    if (retval) {
+        //cerr << "got reval->true" << endl;
+
+        input = input_cstr;
+
+    } else {
+        //cerr << "got retval->false" << endl;
+    }
+
+    rx.history_add(input);
+
+    input.push_back('\n');
+
+    return retval;
+}
+
+void
+welcome(std::ostream& os)
+{
+    using namespace std;
+
+    os << "read-eval-print loop for schematika expressions" << endl;
+    os << "  ctrl-a/ctrl-e   beginning/end of line" << endl;
+    os << "  ctrl-u          delete entire line" << endl;
+    os << "  ctrl-k          delete to end of line" << endl;
+    os << "  meta-<bs>       backward delete word" << endl;
+    os << "  <up>|meta-p     previous command from history" << endl;
+    os << "  <down>|meta-n   next command from history" << endl;
+    os << "  <pgup>/<pgdown> page through history faster" << endl;
+    os << "  ctrl-s/ctrl-r   forward/backward history search" << endl;
+    os << endl;
+}
+
+int
+main()
+{
+    using namespace replxx;
+    using namespace xo::scm;
+    using xo::scm::Expression;
+    using xo::print::ppconfig;
+    using xo::print::ppstate_standalone;
+    using xo::rp;
+    using namespace std;
+
+    using span_type = xo::scm::span<const char>;
+
+    bool interactive = isatty(STDIN_FILENO);
+
+    Replxx rx;
+    rx.set_max_history_size(1000);
+    rx.history_load("repl_history.txt");
+//    rx.bind_key_internal(Replxx::KEY::control('p'), "history_previous");
+//    rx.bind_key_internal(Replxx::KEY::control('n'), "history_next");
+
+    constexpr bool c_debug_flag = false;
+
+    rp<GlobalSymtab> toplevel_symtab = GlobalSymtab::make_empty();
+
+    reader rdr(toplevel_symtab, c_debug_flag);
+    rdr.begin_interactive_session();
+
+    string input_str;
+
+    bool eof = false;
+
+    span_type input;
+    std::size_t parser_stack_size = 0;
+
+    welcome(cerr);
+
+    while (replxx_getline(interactive, parser_stack_size, rx, input_str)) {
+        input = span_type::from_string(input_str);
+
+        while (!input.empty()) {
+            auto [expr, consumed, psz, error] = rdr.read_expr(input, eof);
+
+            if (expr) {
+                ppconfig ppc;
+                ppstate_standalone pps(&cout, 0, &ppc);
+
+                pps.prettyn(expr);
+            } else if (error.is_error()) {
+                cout << "parsing error (detected in " << error.src_function() << "): " << endl;
+                error.report(cout);
+
+                /* discard stashed remainder of input line
+                 * (for nicely-formatted errors)
+                 */
+                rdr.reset_to_idle_toplevel();
+                break;
+            }
+
+            input = input.after_prefix(consumed);
+            parser_stack_size = psz;
+        }
+
+        /* here: input.empty() or error encountered */
+
+    }
+
+    auto [expr, _1, _2, error] = rdr.read_expr(input, true /*eof*/);
+
+    if (expr) {
+        ppconfig ppc;
+        ppstate_standalone pps(&cout, 0, &ppc);
+
+        pps.prettyn<rp<Expression>>(rp<Expression>(expr));
+    } else if (error.is_error()) {
+        cout << "parsing error (detected in " << error.src_function() << "): " << endl;
+        error.report(cout);
+    }
+
+    rx.history_save("repl_history.txt");
+}
diff --git a/xo-reader/include/xo/reader/apply_xs.hpp b/xo-reader/include/xo/reader/apply_xs.hpp
new file mode 100644
index 00000000..14cf234c
--- /dev/null
+++ b/xo-reader/include/xo/reader/apply_xs.hpp
@@ -0,0 +1,119 @@
+/* @file apply_xs.hpp */
+
+#pragma once
+
+#include "exprstate.hpp"
+#include "xo/expression/Apply.hpp"
+
+
+namespace xo {
+    namespace scm {
+        /**
+         *    fn ( arg1 , arg2 , .. , argn )
+         *   ^  ^ ^    ^ ^    ^      ^    ^ ^
+         *   |  | |    | |    |      |    | (done)
+         *   |  | |    | |    |      |    apply_3
+         *   |  | |    | |    |      apply_2:expect_rhs_expression
+         *   |  | |    | |    apply_3
+         *   |  | |    | apply_2:expect_rhs_expression
+         *   |  | |    apply_3
+         *   |  | apply_2:expect_rhs_expression
+         *   |  apply_1
+         *   apply_0:expect_rhs_expression
+         *
+         *   apply_0 --on_expr()--> apply_1
+         *   apply_1 --on_leftparen()--> apply_2
+         *   apply_2 --on_expr()--> apply_3
+         *   apply_3 --on_comma()--> apply_2
+         *           --on_rightparen()-> (done)
+         *
+         *   apply_0: start
+         *   apply_1: leftparen following expr allows parser to recognize apply
+         *   apply_2: expect next argument
+         *   apply_3: got argument, expect comma or rightparen to continue
+         *   (done): apply complete, pop exprstate from stack
+         *
+         * In practice will start in state apply_1
+         **/
+        enum class applyexprstatetype {
+            invalid = -1,
+
+            apply_0,
+            apply_1,
+            apply_2,
+            apply_3,
+
+            n_applyexprstatetype
+        };
+
+        extern const char * applyexprstatetype_descr(applyexprstatetype x);
+
+        std::ostream &
+        operator<<(std::ostream & os, applyexprstatetype x);
+
+        /** @class apply_xs
+         *  @brief state machine for parsing a schematic function-call-expression
+         *
+         */
+        class apply_xs : public exprstate {
+        public:
+            using Apply = xo::scm::Apply;
+
+        public:
+            explicit apply_xs();
+            virtual ~apply_xs() = default;
+
+            /** downcast from parent type **/
+            static const apply_xs * from(const exprstate * x) {
+                return dynamic_cast<const apply_xs *>(x);
+            }
+
+            /**
+             * Start apply. Will trigger this after input like
+             *   "fn("
+             *
+             * apply_xs remains on expr stack until closing right paren
+             *    fn(arg1-expr, arg2-expr, ...)
+             *
+             * @p fnex   expression in function position
+             * @p p_psm  parser state machine
+             **/
+            static void start(rp<Expression> fnex,
+                              parserstatemachine * p_psm);
+
+            virtual const char * get_expect_str() const override;
+
+            virtual void on_expr(bp<Expression> expr,
+                                 parserstatemachine * p_psm) override;
+
+            virtual void on_comma_token(const token_type & tk,
+                                        parserstatemachine * p_psm) override;
+            virtual void on_leftparen_token(const token_type & tk,
+                                             parserstatemachine * p_psm) override;
+            virtual void on_rightparen_token(const token_type & tk,
+                                             parserstatemachine * p_psm) override;
+
+            virtual void print(std::ostream & os) const override;
+            virtual bool pretty_print(const print::ppindentinfo & ppii) const final override;
+
+        private:
+            static std::unique_ptr<apply_xs> make();
+
+        private:
+            /** current state of parser for this apply expression **/
+            applyexprstatetype applyxs_type_ = applyexprstatetype::apply_0;
+            /** evaluates to function to be invoked **/
+            rp<Expression> fn_expr_;
+            /** evaluates to the arguments to pass to @ref fn_ **/
+            std::vector<rp<Expression>> args_expr_v_;
+        };
+    } /*namespace scm */
+
+    namespace print {
+#ifndef ppdetail_atomic
+        PPDETAIL_ATOMIC(xo::scm::applyexprstatetype);
+#endif
+    }
+} /*namespace xo*/
+
+/* end apply_xs.hpp */
diff --git a/xo-reader/include/xo/reader/define_xs.hpp b/xo-reader/include/xo/reader/define_xs.hpp
new file mode 100644
index 00000000..d10a080f
--- /dev/null
+++ b/xo-reader/include/xo/reader/define_xs.hpp
@@ -0,0 +1,135 @@
+/** @file define_xs.hpp
+ *
+ *  Author: Roland Conybeare
+ **/
+
+#pragma once
+
+#include "xo/expression/DefineExpr.hpp"
+#include "xo/expression/ConvertExpr.hpp"
+#include "exprstate.hpp"
+#include "xo/indentlog/print/ppdetail_atomic.hpp"
+//#include <cstdint>
+
+namespace xo {
+    namespace scm {
+        /**
+         *   def foo : f64 = 1 ;
+         *  ^   ^   ^ ^   ^ ^ ^ ^
+         *  |   |   | |   | | | (done)
+         *  |   |   | |   | | def_6:expect_rhs_expression:expr_progress
+         *  |   |   | |   | def_5:expect_rhs_expression
+         *  |   |   | |   def_4
+         *  |   |   | def_3:expect_type
+         *  |   |   def_2
+         *  |   def_1:expect_symbol
+         *  def_0
+         *  expect_toplevel_expression_sequence
+         *
+         *   def_0 --on_def_token()--> def_1
+         *   def_1 --on_symbol()--> def_2
+         *   def_2 --on_colon_token()--> def_3
+         *         --on_singleassign_token()--> def_5
+         *   def_3 --on_typedescr()--> def_4
+         *   def_4 --on_singleassign_token()--> def_5
+         *   def_5 --on_expr()--> def_6
+         *   def_6 --on_semicolon_token()--> (done)
+         *
+         *   def_1:expect_symbol: got 'def' keyword, symbol to follow
+         *   def_1: got symbol name
+         *   def_3:expect_symbol got (optional) colon, type name to follow
+         *   def_4: got symbol type
+         *   def_6:expect_rhs_expression got (optional) equal sign, value to follow
+         *   (done): definition complete,  pop exprstate from stack
+         *
+         **/
+        enum class defexprstatetype {
+            invalid = -1,
+
+            def_0,
+            def_1,
+            def_2,
+            def_3,
+            def_4,
+            def_5,
+            def_6,
+
+            n_defexprstatetype,
+        };
+
+        extern const char * defexprstatetype_descr(defexprstatetype x);
+
+        std::ostream &
+        operator<<(std::ostream & os, defexprstatetype x);
+
+        /** @class define_xs
+         *  @brief state to provide parsing of a define-expression
+         **/
+        class define_xs : public exprstate {
+        public:
+            using DefineExprAccess = xo::scm::DefineExprAccess;
+            using ConvertExprAccess = xo::scm::ConvertExprAccess;
+
+        public:
+            define_xs(rp<DefineExprAccess> def_expr);
+            virtual ~define_xs() = default;
+
+            static const define_xs * from(const exprstate * x) { return dynamic_cast<const define_xs *>(x); }
+
+            static void start(parserstatemachine * p_psm);
+
+            defexprstatetype defxs_type() const { return defxs_type_; }
+            bp<Variable> lhs_variable() const { return def_expr_->lhs_variable(); }
+
+            /** @return expected input in current state **/
+            virtual const char * get_expect_str() const override;
+
+            virtual void on_expr(bp<Expression> expr,
+                                 parserstatemachine * p_psm) override;
+            virtual void on_expr_with_semicolon(bp<Expression> expr,
+                                                parserstatemachine * p_psm) override;
+            virtual void on_symbol(const std::string & symbol_name,
+                                   parserstatemachine * p_psm) override;
+            virtual void on_typedescr(TypeDescr td,
+                                      parserstatemachine * p_psm) override;
+            virtual void on_def_token(const token_type & tk,
+                                      parserstatemachine * p_psm) override;
+            virtual void on_colon_token(const token_type & tk,
+                                        parserstatemachine * p_psm) override;
+            virtual void on_semicolon_token(const token_type & tk,
+                                            parserstatemachine * p_psm) override;
+            virtual void on_singleassign_token(const token_type & tk,
+                                               parserstatemachine * p_psm) override;
+            virtual void on_rightparen_token(const token_type & tk,
+                                             parserstatemachine * p_psm) override;
+            virtual void on_i64_token(const token_type & tk,
+                                      parserstatemachine * p_psm) override;
+            virtual void on_f64_token(const token_type & tk,
+                                      parserstatemachine * p_psm) override;
+
+            virtual void print(std::ostream & os) const override;
+            virtual bool pretty_print(const print::ppindentinfo & ppii) const override;
+
+        private:
+            static std::unique_ptr<define_xs> make();
+
+        private:
+            defexprstatetype defxs_type_;
+            /** scaffold a define-expression here **/
+            rp<DefineExprAccess> def_expr_;
+            /** scafford a convert-expression here.
+             *  May be nested within a def_expr
+             **/
+            rp<ConvertExprAccess> cvt_expr_;
+        };
+    } /*namespace scm*/
+
+#ifndef ppdetail_atomic
+    namespace print {
+        PPDETAIL_ATOMIC(xo::scm::defexprstatetype);
+    }
+#endif
+} /*namespace xo*/
+
+
+/** end define_xs.hpp **/
diff --git a/xo-reader/include/xo/reader/envframe.hpp b/xo-reader/include/xo/reader/envframe.hpp
new file mode 100644
index 00000000..0dbd96e5
--- /dev/null
+++ b/xo-reader/include/xo/reader/envframe.hpp
@@ -0,0 +1,60 @@
+/* file envframe.hpp
+ *
+ * author: Roland Conybeare, Aug 2024
+ */
+
+#pragma once
+
+xxx;
+
+#include "xo/expression/Variable.hpp"
+#include "xo/expression/LocalSymtab.hpp"
+#include <vector>
+
+namespace xo {
+    namespace scm {
+#ifdef OBSOLETE
+        /** @class envframe
+         *  @brief names/types of formal paremeters introduced by a function
+         *
+         *
+         **/
+        class envframe {
+        public:
+            using Environment = xo::scm::Environment;
+            using LocalEnv    = xo::scm::LocalEnv;
+            using Variable    = xo::scm::Variable;
+
+        public:
+            envframe() = default;
+            envframe(const std::vector<rp<Variable>> & argl, const rp<Environment> & parent_env);
+
+            const std::vector<rp<Variable>> & argl() const { return env_->argv(); }
+            const rp<LocalEnv> & local_env() const { return env_; }
+
+            /** lookup variable by @p name.  If found, return it.
+             *  Otherwise return nullptr
+             **/
+            bp<Variable> lookup(const std::string & name) const;
+
+            /** establish (replacing if already exists) binding for variable @p var.
+             *  Replacement intended for use in interactive sessions
+             **/
+            void upsert(bp<Variable> var);
+
+            void print (std::ostream & os) const;
+
+        private:
+            rp<LocalEnv> env_;
+        };
+
+        inline std::ostream &
+        operator<< (std::ostream & os, const envframe & x) {
+            x.print(os);
+            return os;
+        }
+#endif
+    } /*namespace scm*/
+} /*namespace xo*/
+
+/* end envframe.hpp */
diff --git a/xo-reader/include/xo/reader/envframestack.hpp b/xo-reader/include/xo/reader/envframestack.hpp
new file mode 100644
index 00000000..02194113
--- /dev/null
+++ b/xo-reader/include/xo/reader/envframestack.hpp
@@ -0,0 +1,87 @@
+/* file envframestack.hpp
+ *
+ * author: Roland Conybeare, Aug 2024
+ */
+
+#pragma once
+
+#include "xo/expression/LocalSymtab.hpp"
+
+namespace xo {
+    namespace scm {
+        /** @class envframestack
+         *  @brief A stack of envframe objects
+         **/
+        class envframestack {
+        public:
+            using ppstate      = xo::print::ppstate;
+            using ppindentinfo = xo::print::ppindentinfo;
+
+        public:
+            envframestack() {}
+
+            bool empty() const { return stack_.empty(); }
+            std::size_t size() const { return stack_.size(); }
+
+            /** lookup variable in environment stack.
+             *  Visit frames in fifo order,  report first match;
+             *  nullptr if no matches.
+             **/
+            bp<Expression> lookup(const std::string & x) const;
+
+            /** update/replace binding for variable @p target.
+             *  New binding may have a different type.
+             **/
+            void upsert(bp<Variable> target);
+
+            bp<SymbolTable> top_envframe() const;
+            void push_envframe(const rp<SymbolTable> & x);
+            rp<SymbolTable> pop_envframe();
+
+            void reset_to_toplevel() { stack_.resize(1); }
+
+            /** relative to top-of-stack.
+             *  0 -> top (last in),  z-1 -> bottom (first in)
+             **/
+            bp<SymbolTable> operator[](std::size_t i) {
+                std::size_t z = stack_.size();
+
+                assert(i < z);
+
+                return stack_[z - i - 1].get();
+            }
+
+            bp<SymbolTable> operator[](std::size_t i) const {
+                std::size_t z = stack_.size();
+
+                assert(i < z);
+
+                return stack_[z - i - 1].get();
+            }
+
+            void print (std::ostream & os) const;
+            bool pretty_print(const ppindentinfo & ppii) const;
+
+        private:
+            std::vector<rp<SymbolTable>> stack_;
+        };
+
+        inline std::ostream &
+        operator<< (std::ostream & os, const envframestack & x) {
+            x.print(os);
+            return os;
+        }
+
+        inline std::ostream &
+        operator<< (std::ostream & os, const envframestack * x) {
+            if (x)
+                x->print(os);
+            else
+                os << "nullptr";
+            return os;
+        }
+    } /*namespace scm*/
+} /*namespace xo*/
+
+
+/* end envframestack.hpp */
diff --git a/xo-reader/include/xo/reader/expect_expr_xs.hpp b/xo-reader/include/xo/reader/expect_expr_xs.hpp
new file mode 100644
index 00000000..6f6513e3
--- /dev/null
+++ b/xo-reader/include/xo/reader/expect_expr_xs.hpp
@@ -0,0 +1,106 @@
+/* file expect_expr_xs.hpp
+ *
+ * author: Roland Conybeare, Aug 2024
+ */
+
+#pragma once
+
+#include "exprstate.hpp"
+
+namespace xo {
+    namespace scm {
+
+        /** @class expect_expr_xs
+         *  @brief state machine to expect + capture an expression
+         *
+         *  Examples:
+         *  @text
+         *    add (1, 2) ;
+         *    def x : i64 = 5 ;           // with allow_defs
+         *    lambda (f : x64) { ... } ;
+         *    if (prime(x)) { ... } ;
+         *    5 + x ;
+         *  @endtext
+         *
+         *  top exprstate when expect_expr_xs::start() invoked
+         *  will receive parsed expression via
+         *  exprstate::on_expr() or exprstate::on_expr_with_semicolon().
+         **/
+        class expect_expr_xs : public exprstate {
+        public:
+            explicit expect_expr_xs(bool allow_defs,
+                                    bool cxl_on_rightbrace);
+
+            static void start(parserstatemachine * p_psm);
+            static void start(bool allow_defs,
+                              bool cxl_on_rightbrace,
+                              parserstatemachine * p_psm);
+
+            virtual const char * get_expect_str() const override;
+
+            virtual void on_lambda_token(const token_type & tk,
+                                         parserstatemachine * p_psm) override;
+
+            virtual void on_if_token(const token_type & tk,
+                                     parserstatemachine * p_psm) override;
+
+            virtual void on_def_token(const token_type & tk,
+                                      parserstatemachine * p_psm) override;
+
+            virtual void on_leftparen_token(const token_type & tk,
+                                            parserstatemachine * p_psm) override;
+
+            virtual void on_leftbrace_token(const token_type & tk,
+                                            parserstatemachine * p_psm) override;
+
+            virtual void on_rightbrace_token(const token_type & tk,
+                                             parserstatemachine * p_psm) override;
+
+            virtual void on_symbol_token(const token_type & tk,
+                                         parserstatemachine * p_psm) override;
+
+            virtual void on_bool_token(const token_type & tk,
+                                       parserstatemachine * p_psm) override;
+
+            virtual void on_i64_token(const token_type & tk,
+                                      parserstatemachine * p_psm) override;
+
+            virtual void on_f64_token(const token_type & tk,
+                                      parserstatemachine * p_psm) override;
+
+            virtual void on_string_token(const token_type & tk,
+                                         parserstatemachine * p_psm) final override;
+
+            /** update exprstate in response to a successfully-parsed subexpression **/
+            virtual void on_expr(bp<Expression> expr,
+                                 parserstatemachine * p_psm) override;
+            /** update exprstate in response to a successfully-parsed subexpression
+             *  that's terminated by semicolon ';'
+             **/
+            virtual void on_expr_with_semicolon(bp<Expression> expr,
+                                                parserstatemachine * p_psm) override;
+
+            virtual void print(std::ostream & os) const override;
+            virtual bool pretty_print(const xo::print::ppindentinfo & ppii) const override;
+
+        private:
+            static std::unique_ptr<expect_expr_xs> make(bool allow_defs,
+                                                        bool cxl_on_rightbrace);
+
+        private:
+            /** if true: allow a define-expression here **/
+            bool allow_defs_ = false;
+            /** if true: expecting either:
+             *   - expression
+             *   - right brace '}',  in which case no expression
+             * if false: expecting
+             *   - expression
+             **/
+            bool cxl_on_rightbrace_ = false;
+        };
+
+    } /*namespace scm*/
+} /*namespace xo*/
+
+
+/* end expect_expr_xs.hpp */
diff --git a/xo-reader/include/xo/reader/expect_formal_arglist_xs.hpp b/xo-reader/include/xo/reader/expect_formal_arglist_xs.hpp
new file mode 100644
index 00000000..509fe194
--- /dev/null
+++ b/xo-reader/include/xo/reader/expect_formal_arglist_xs.hpp
@@ -0,0 +1,85 @@
+/* file expect_formal_arglist_xs.hpp
+ *
+ * author: Roland Conybeare, Aug 2024
+ */
+
+#pragma once
+
+#include "exprstate.hpp"
+#include "formal_arg.hpp"
+#include <vector>
+
+namespace xo {
+    namespace scm {
+        /**
+         *   ( name(1) : type(1) , ..., )
+         *  ^ ^                 ^ ^    ^
+         *  | |                 | |    |
+         *  | |                 | |    argl_1b
+         *  | argl_1a           | argl_1a
+         *  argl_0              argl_1b
+         *
+         *  argl_0 --on_leftparen_token()--> argl_1a
+         *  argl_1a --on_formal()--> argl_1b
+         *  argl_1b -+-on_comma_token()--> argl_1a
+         *           \-on_rightparen_token()--> (done)
+         **/
+        enum class formalarglstatetype {
+            invalid = -1,
+
+            argl_0,
+            argl_1a,
+            argl_1b,
+
+            n_formalarglstatetype,
+        };
+
+        extern const char *
+        formalarglstatetype_descr(formalarglstatetype x);
+
+        inline std::ostream &
+        operator<< (std::ostream & os, formalarglstatetype x) {
+            os << formalarglstatetype_descr(x);
+            return os;
+        }
+
+        /** @class expect_formal_arglist
+         *  @brief parser state-machine for a formal parameter list
+         **/
+        class expect_formal_arglist_xs : public exprstate {
+        public:
+            using Variable = xo::scm::Variable;
+
+        public:
+            expect_formal_arglist_xs();
+
+            static void start(parserstatemachine * p_psm);
+
+            virtual const char * get_expect_str() const override;
+
+            virtual void on_leftparen_token(const token_type & tk,
+                                            parserstatemachine * p_psm) override;
+            virtual void on_formal(const rp<Variable> & formal,
+                                   parserstatemachine * p_psm) override;
+            virtual void on_comma_token(const token_type & tk,
+                                        parserstatemachine * p_psm) override;
+            virtual void on_rightparen_token(const token_type & tk,
+                                             parserstatemachine * p_psm) override;
+            virtual void print(std::ostream & os) const override;
+
+        private:
+            static std::unique_ptr<expect_formal_arglist_xs> make();
+
+        private:
+            /** parsing state-machine state **/
+            formalarglstatetype farglxs_type_ = formalarglstatetype::argl_0;
+            /** populate with (parmaeter-name, parameter-type) list
+             *  as they're encountered
+             **/
+            std::vector<rp<Variable>> argl_;
+        };
+    } /*namespace scm*/
+} /*namespace xo*/
+
+
+/* end expect_formal_arglist_xs.hpp */
diff --git a/xo-reader/include/xo/reader/expect_formal_xs.hpp b/xo-reader/include/xo/reader/expect_formal_xs.hpp
new file mode 100644
index 00000000..97d781ee
--- /dev/null
+++ b/xo-reader/include/xo/reader/expect_formal_xs.hpp
@@ -0,0 +1,85 @@
+/* file expect_formal_xs.hpp
+ *
+ * author: Roland Conybeare, Aug 2024
+ */
+
+#pragma once
+
+#include "exprstate.hpp"
+#include "formal_arg.hpp"
+
+namespace xo {
+    namespace scm {
+        /**
+         *   name : type
+         *  ^    ^ ^
+         *  |    | formal_2
+         *  |    formal_1
+         *  formal_0
+         *
+         *  formal_0 --on_symbol()--> formal_1
+         *  formal_1 --on_colon_token()--> formal_2
+         *  formal_2 --on_typedescr()--> (done)
+         **/
+        enum class formalstatetype {
+            invalid = -1,
+
+            formal_0,
+            formal_1,
+            formal_2,
+
+            n_formalstatetype,
+        };
+
+        extern const char *
+        formalstatetype_descr(formalstatetype x);
+
+        inline std::ostream &
+        operator<< (std::ostream & os, formalstatetype x) {
+            os << formalstatetype_descr(x);
+            return os;
+        }
+
+        /** @class expect_formal_xs
+         *  @brief parser state-machine for a typed formal parameter
+         **/
+        class expect_formal_xs : public exprstate {
+        public:
+            expect_formal_xs();
+
+            static void start(parserstatemachine * p_psm);
+
+            virtual void on_symbol(const std::string & symbol_name,
+                                   parserstatemachine * p_psm) override;
+
+            virtual void on_colon_token(const token_type & tk,
+                                        parserstatemachine * p_psm) override;
+
+            // virtual void on_comma_token(...) override;
+
+#ifdef PROBABLY_NOT
+            virtual void on_rightparen_token(const token_type & tk,
+                                             exprstatestack * p_stack,
+                                             rp<Expression> * p_emit_expr) override;
+#endif
+
+            virtual void on_typedescr(TypeDescr td,
+                                      parserstatemachine * p_psm) override;
+
+            virtual void print(std::ostream & os) const override;
+
+        private:
+            static std::unique_ptr<expect_formal_xs> make();
+
+        private:
+            /** parsing state-machine state **/
+            formalstatetype formalxs_type_ = formalstatetype::formal_0;
+            /** populate with {parameter-name, parameter-type}
+             *  as they're encountered
+             **/
+            formal_arg result_;
+        };
+    } /*namespace scm*/
+} /*namespace xo*/
+
+/* end expect_formal_xs.hpp */
diff --git a/xo-reader/include/xo/reader/expect_symbol_xs.hpp b/xo-reader/include/xo/reader/expect_symbol_xs.hpp
new file mode 100644
index 00000000..be4df5e4
--- /dev/null
+++ b/xo-reader/include/xo/reader/expect_symbol_xs.hpp
@@ -0,0 +1,32 @@
+/* file expect_symbol_xs.hpp
+ *
+ * author: Roland Conybeare, Aug 2024
+ */
+
+#pragma once
+
+#include "exprstate.hpp"
+
+namespace xo {
+    namespace scm {
+        /** @class expect_symbol_xs
+         *  @brief state machine to expect + capture a symbol
+         *
+         *  For example,  lhs in a define-expression
+         **/
+        class expect_symbol_xs : public exprstate {
+        public:
+            expect_symbol_xs();
+
+            static std::unique_ptr<expect_symbol_xs> make();
+
+            static void start(parserstatemachine * p_psm);
+
+            virtual void on_symbol_token(const token_type & tk,
+                                         parserstatemachine * p_psm) override;
+        };
+    } /*namespace scm*/
+} /*namespace xo*/
+
+
+/* end expect_symbol_xs.hpp */
diff --git a/xo-reader/include/xo/reader/expect_type_xs.hpp b/xo-reader/include/xo/reader/expect_type_xs.hpp
new file mode 100644
index 00000000..28fea322
--- /dev/null
+++ b/xo-reader/include/xo/reader/expect_type_xs.hpp
@@ -0,0 +1,33 @@
+/* file expect_type_xs.hpp
+ *
+ * author: Roland Conybeare, Aug 2024
+ */
+
+#pragma once
+
+#include "exprstate.hpp"
+
+namespace xo {
+    namespace scm {
+        /** @class expect_type_xs
+         *  @brief state-machine for accepting a typename-expression
+         **/
+        class expect_type_xs : public exprstate {
+        public:
+            expect_type_xs();
+
+            static void start(parserstatemachine * p_stack);
+
+            virtual const char * get_expect_str() const override;
+
+            virtual void on_symbol_token(const token_type & tk,
+                                         parserstatemachine * p_psm) override;
+
+        private:
+            static std::unique_ptr<expect_type_xs> make();
+        };
+    } /*namespace scm*/
+} /*namespace xo*/
+
+
+/* end expect_type_xs.hpp */
diff --git a/xo-reader/include/xo/reader/exprseq_xs.hpp b/xo-reader/include/xo/reader/exprseq_xs.hpp
new file mode 100644
index 00000000..60b483ad
--- /dev/null
+++ b/xo-reader/include/xo/reader/exprseq_xs.hpp
@@ -0,0 +1,84 @@
+/** @file exprseq_xs.hpp
+ *
+ *  Author: Roland Conybeare
+ **/
+
+#pragma once
+
+#include "exprstate.hpp"
+//#include <cstdint>
+
+namespace xo {
+    namespace scm {
+        enum class exprseqtype {
+            /** toplevel interactive sequence.  Most permissive **/
+            toplevel_interactive,
+            /** toplevel non-interactive sequence.
+             *  This used for top-level expressions in a translation unit.
+             **/
+            toplevel_batch,
+        };
+
+        /** @class exprseq_xs
+         *  @brief parsing state-machine for top-level expression sequence
+         *
+         *  expression sequences come in several types:
+         *  1. top-level interactive
+         *  2. top-level batch
+         *
+         *  @text
+         *           1 2
+         *         +-----
+         *  def    | y y
+         *  if     | y n     1: eval as expression
+         *  symbol | y n     1: evaluate as variable
+         *  i64    | y n     1: evaluate as constant
+         *
+         *  @endtext
+         **/
+        class exprseq_xs : public exprstate {
+        public:
+            explicit exprseq_xs(exprseqtype seqtype);
+
+            static void start(exprseqtype seqtype, parserstatemachine * p_psm);
+
+        public:
+            virtual const char * get_expect_str() const override;
+
+            // ----- token input methods -----
+
+            virtual void on_def_token(const token_type & tk,
+                                      parserstatemachine * p_psm) override;
+            virtual void on_if_token(const token_type & tk,
+                                     parserstatemachine * p_psm) override;
+            virtual void on_symbol_token(const token_type & tk,
+                                         parserstatemachine * p_psm) override;
+            virtual void on_bool_token(const token_type & tk,
+                                       parserstatemachine * p_psm) override;
+            virtual void on_i64_token(const token_type & tk,
+                                      parserstatemachine * p_psm) override;
+            virtual void on_f64_token(const token_type & tk,
+                                      parserstatemachine * p_psm) override;
+            virtual void on_string_token(const token_type & tk,
+                                         parserstatemachine * p_psm) final override;
+
+            // ----- victory methods -----
+
+            virtual void on_typedescr(TypeDescr td,
+                                      parserstatemachine * p_psm) override;
+            virtual void on_expr(bp<Expression> expr,
+                                 parserstatemachine * p_psm) override;
+            virtual void on_expr_with_semicolon(bp<Expression> expr,
+                                                parserstatemachine * p_psm) override;
+
+        private:
+            static std::unique_ptr<exprseq_xs> make(exprseqtype seqtype);
+
+            /** context for this expression sequence **/
+            exprseqtype xseqtype_;
+        };
+    } /*namespace scm*/
+} /*namespace xo*/
+
+
+/** end exprseq_xs.hpp **/
diff --git a/xo-reader/include/xo/reader/exprstate.hpp b/xo-reader/include/xo/reader/exprstate.hpp
new file mode 100644
index 00000000..ed3187c3
--- /dev/null
+++ b/xo-reader/include/xo/reader/exprstate.hpp
@@ -0,0 +1,317 @@
+/** @file exprstate.hpp
+ *
+ *  Author: Roland Conybeare
+ **/
+
+#pragma once
+
+#include "xo/expression/Expression.hpp"
+#include "xo/tokenizer/token.hpp"
+#include "xo/indentlog/print/ppdetail_atomic.hpp"
+#include <stack>
+//#include <cstdint>
+
+namespace xo {
+    namespace scm {
+        /** Identify current state in an expression state machine
+         **/
+        enum class exprstatetype {
+            invalid = -1,
+
+            /** toplevel of some translation unit **/
+            expect_toplevel_expression_sequence,
+
+            /** handle define-expression
+             *  see @ref define_xs
+             **/
+            defexpr,
+
+            /** handle lambda-expression
+             *  see @ref lambda_xs
+             **/
+            lambdaexpr,
+
+            /** handle apply expression (aka function call)
+             *  see @ref apply_xs
+             **/
+            applyexpr,
+
+            /** handle parenthesized expression
+             *  see @ref paren_xs
+             **/
+            parenexpr,
+
+            /** handle sequence expression (aka block)
+             *  see @ref sequence_xs
+             **/
+            sequenceexpr,
+
+            /** handle let1 (single local variable)
+             *  see @ref let1_xs
+             **/
+            let1expr,
+
+            /** handle if-else expression
+             *  see @ref if_else_xs
+             **/
+            ifexpr,
+
+            expect_rhs_expression,
+            expect_symbol,
+            expect_type,
+            /** handle formal argument list
+             *  see @ref expect_formal_arglist_xs
+             **/
+            expect_formal_arglist,
+            /** handle formal argument
+             *  see @ref expec_formal_xs
+             **/
+            expect_formal,
+
+            /** handle expression-in-progress,
+             *  in case infix operators to follow
+             *  see @ref progress_xs
+             **/
+            expr_progress,
+
+            n_exprstatetype
+        };
+
+        extern const char *
+        exprstatetype_descr(exprstatetype x);
+
+        inline std::ostream &
+        operator<< (std::ostream & os, exprstatetype x) {
+            os << exprstatetype_descr(x);
+            return os;
+        }
+
+        class parserstatemachine; /* see parserstatemachine.hpp */
+        class exprstatestack; /* see exprstatestack.hpp */
+
+        class formal_arg;
+
+        /** state associated with a partially-parsed expression.
+         **/
+        class exprstate {
+        public:
+            using Expression = xo::scm::Expression;
+            using Variable = xo::scm::Variable;
+            using exprtype = xo::scm::exprtype;
+            using token_type = token<char>;
+            using TypeDescr = xo::reflect::TypeDescr;
+
+        public:
+            exprstate() = default;
+            exprstate(exprstatetype exs_type)
+                : exs_type_{exs_type}
+                {}
+            virtual ~exprstate() = default;
+
+            exprstatetype exs_type() const { return exs_type_; }
+
+            /** update exprstate in response to incoming token @p tk,
+             *  forward instructions to parent parser
+             **/
+            void on_input(const token_type & tk,
+                          parserstatemachine * p_psm);
+
+            /** @return string describing expected/allowed input in current state **/
+            virtual const char * get_expect_str() const;
+
+            /** update exprstate in response to a successfully-parsed subexpression **/
+            virtual void on_expr(bp<Expression> expr,
+                                 parserstatemachine * p_psm);
+
+            /** update exprstate in response to a successfully-parsed subexpression, that ends with semicolon **/
+            virtual void on_expr_with_semicolon(bp<Expression> expr,
+                                                parserstatemachine * p_psm);
+
+            /** update exprstate when expecting a symbol **/
+            virtual void on_symbol(const std::string & symbol,
+                                   parserstatemachine * p_psm);
+
+            /** update exprstate when expeccting a typedescr **/
+            virtual void on_typedescr(TypeDescr td,
+                                      parserstatemachine * p_psm);
+
+            /** update exprstate when expecting a formal parameter **/
+            virtual void on_formal(const rp<Variable> & formal,
+                                   parserstatemachine * p_psm);
+
+            /** update expression when epecting a formal parameter list **/
+            virtual void on_formal_arglist(const std::vector<rp<Variable>> & argl,
+                                           parserstatemachine * p_psm);
+
+            /** print human-readable representation on @p os **/
+            virtual void print(std::ostream & os) const;
+
+            /** pretty-print using @p ppii **/
+            virtual bool pretty_print(const print::ppindentinfo & ppii) const;
+
+            // ----- input methods -----
+
+            /** handle incoming 'def' token **/
+            virtual void on_def_token(const token_type & tk,
+                                      parserstatemachine * p_psm);
+            /** handle incoming 'lambda' token **/
+            virtual void on_lambda_token(const token_type & tk,
+                                         parserstatemachine * p_psm);
+            /** handle incoming symbol token **/
+            virtual void on_symbol_token(const token_type & tk,
+                                         parserstatemachine * p_psm);
+            /** handle incoming ',' token **/
+            virtual void on_comma_token(const token_type & tk,
+                                        parserstatemachine * p_psm);
+            /** handle incoming ':' token **/
+            virtual void on_colon_token(const token_type & tk,
+                                        parserstatemachine * p_psm);
+            /** handle incoming ';' token **/
+            virtual void on_semicolon_token(const token_type & tk,
+                                            parserstatemachine * p_psm);
+            /** handle incoming '=' token **/
+            virtual void on_singleassign_token(const token_type & tk,
+                                               parserstatemachine * p_psm);
+            /** handle incoming ':=' token **/
+            virtual void on_assign_token(const token_type & tk,
+                                         parserstatemachine * p_psm);
+            /** handle incoming '(' token **/
+            virtual void on_leftparen_token(const token_type & tk,
+                                            parserstatemachine * p_psm);
+            /** handle incoming ')' token **/
+            virtual void on_rightparen_token(const token_type & tk,
+                                             parserstatemachine * p_psm);
+
+            /** handle incoming '{' token **/
+            virtual void on_leftbrace_token(const token_type & tk,
+                                            parserstatemachine * p_psm);
+
+            /** handle incoming '}' token **/
+            virtual void on_rightbrace_token(const token_type & tk,
+                                             parserstatemachine * p_psm);
+
+            /** handle incoming operator token **/
+            virtual void on_operator_token(const token_type & tk,
+                                           parserstatemachine * p_psm);
+
+            /** handle incoming if-keyword token **/
+            virtual void on_if_token(const token_type & tk,
+                                     parserstatemachine * p_psm);
+
+            /** handle incoming then-keyword token **/
+            virtual void on_then_token(const token_type & tk,
+                                       parserstatemachine * p_psm);
+
+            /** handle incoming then-keyword token **/
+            virtual void on_else_token(const token_type & tk,
+                                       parserstatemachine * p_psm);
+
+            /** handle incoming bool-literal token **/
+            virtual void on_bool_token(const token_type & tk,
+                                       parserstatemachine * p_psm);
+
+            /** handle incoming integer-literal token **/
+            virtual void on_i64_token(const token_type & tk,
+                                      parserstatemachine * p_psm);
+
+            /** handle incoming floating-point-literal token **/
+            virtual void on_f64_token(const token_type & tk,
+                                      parserstatemachine * p_psm);
+
+            /** handle incoming string-literal token **/
+            virtual void on_string_token(const token_type & tk,
+                                         parserstatemachine * p_psm);
+
+        protected:
+            /** throw exception when next token is inconsistent with
+             *  parsing state
+             **/
+            void illegal_input_error(const char * self_name,
+                                     const token_type & tk) const;
+
+            /** throw exception when next token is inconsistent with
+             *  parsing state
+             *
+             *  @p self_name   error detected in this (c++) function
+             *  @p expr        offending input expression
+             *  @p expect_str  indicate expected input in this state
+             *  @p p_psm       parser state machine
+             **/
+            void illegal_input_on_expr(const char * self_name,
+                                       bp<Expression> expr,
+                                       const char * expect_str,
+                                       parserstatemachine * p_psm) const;
+
+            /** throw exception when next token is inconsistent with
+             *  parsing state
+             *
+             *  @p self_name   error detected in this (c++) function
+             *  @p tk          offending input token
+             *  @p expect_str  indicate expected input in this state
+             *  @p p_psm       parser state machine
+             **/
+            void illegal_input_on_token(const char * self_name,
+                                        const token_type & tk,
+                                        const char * expect_str,
+                                        parserstatemachine * p_psm) const;
+
+            /** throw exception when next token is inconsistent with
+             *  parsing state
+             *
+             *  @p self_name   error detected in this (c++) function
+             *  @p symbol_name offending symbol name
+             *  @p expect_str  indicate expected input in this state
+             *  @p p_psm       parser state machine
+             **/
+            void illegal_input_on_symbol(const char * self_name,
+                                         const std::string & symbol_name,
+                                         const char * expect_str,
+                                         parserstatemachine * p_psm) const;
+
+            /** error when typename not expected in current parsing state
+             *
+             *  @p self_name   error detected in this (c++) function
+             *  @p symbol_name offending symbol name
+             *  @p expect_str  indicate expected input in this state
+             *  @p p_psm       parser state machine
+             **/
+            void illegal_input_on_type(const char * self_name,
+                                       TypeDescr td,
+                                       const char * expect_str,
+                                       parserstatemachine * p_psm) const;
+
+            /** capture error in @p *p_psm when unable to locate definition for a variable **/
+            void unknown_variable_error(const char * self_name,
+                                        const token_type & tk,
+                                        parserstatemachine * p_psm) const;
+
+        protected:
+            /** explicit subtype: identifies derived class **/
+            exprstatetype exs_type_;
+        }; /*exprstate*/
+
+        inline std::ostream &
+        operator<< (std::ostream & os, const exprstate & x) {
+            x.print(os);
+            return os;
+        }
+
+        inline std::ostream &
+        operator<< (std::ostream & os, const exprstate * x) {
+            if (x)
+                x->print(os);
+            else
+                os << "nullptr";
+            return os;
+        };
+    } /*namespace scm*/
+
+#ifndef ppdetail_atomic
+    namespace print {
+        PPDETAIL_ATOMIC(xo::scm::exprstatetype);
+        PPDETAIL_ATOMIC(xo::scm::exprstate);
+    } /*namespace print*/
+#endif
+} /*namespace xo*/
+
+/** end exprstate.hpp **/
diff --git a/xo-reader/include/xo/reader/exprstatestack.hpp b/xo-reader/include/xo/reader/exprstatestack.hpp
new file mode 100644
index 00000000..1186c552
--- /dev/null
+++ b/xo-reader/include/xo/reader/exprstatestack.hpp
@@ -0,0 +1,78 @@
+/* file exprstatestack.hpp
+ *
+ * author: Roland Conybeare, Aug 2024
+ */
+
+#pragma once
+
+#include "exprstate.hpp"
+#include "xo/indentlog/print/vector.hpp"
+#include "xo/indentlog/print/pretty.hpp"
+
+namespace xo {
+    namespace scm {
+        /** @class exprstatestack
+         *  @brief A stack of exprstate objects
+         **/
+        class exprstatestack {
+        public:
+            using ppstate = xo::print::ppstate;
+            using ppindentinfo = xo::print::ppindentinfo;
+
+        public:
+            exprstatestack() {}
+
+            bool empty() const { return stack_.empty(); }
+            std::size_t size() const { return stack_.size(); }
+
+            exprstate & top_exprstate();
+            void push_exprstate(std::unique_ptr<exprstate> exs);
+            std::unique_ptr<exprstate> pop_exprstate();
+
+            void reset_to_toplevel();
+
+            /** relative to top-of-stack.
+             *  0 -> top (last in),  z-1 -> bottom (first in)
+             **/
+            std::unique_ptr<exprstate> & operator[](std::size_t i) {
+                std::size_t z = stack_.size();
+
+                assert(i < z);
+
+                return stack_[z - i - 1];
+            }
+
+            const std::unique_ptr<exprstate> & operator[](std::size_t i) const {
+                std::size_t z = stack_.size();
+
+                assert(i < z);
+
+                return stack_[z - i - 1];
+            }
+
+            void print (std::ostream & os) const;
+            bool pretty_print(const ppindentinfo & ppii) const;
+
+        private:
+            std::vector<std::unique_ptr<exprstate>> stack_;
+        };
+
+        inline std::ostream &
+        operator<< (std::ostream & os, const exprstatestack & x) {
+            x.print(os);
+            return os;
+        }
+
+        inline std::ostream &
+        operator<< (std::ostream & os, const exprstatestack * x) {
+            if (x)
+                x->print(os);
+            else
+                os << "nullptr";
+            return os;
+        }
+    } /*namespace scm*/
+} /*namespace xo*/
+
+
+/* end exprstatestack.hpp */
diff --git a/xo-reader/include/xo/reader/formal_arg.hpp b/xo-reader/include/xo/reader/formal_arg.hpp
new file mode 100644
index 00000000..a94f45eb
--- /dev/null
+++ b/xo-reader/include/xo/reader/formal_arg.hpp
@@ -0,0 +1,58 @@
+/* file formal_arg.hpp
+ *
+ * author: Roland Conybeare, Aug 2024
+ */
+
+#pragma once
+
+#include "TypeDescr.hpp"
+#include "xo/indentlog/print/tag.hpp"
+
+namespace xo {
+    namespace scm {
+        /** @class formal_arg
+         *  @brief description of formal parameter in an argument list
+         *
+         *  Terminated by an argument separator ',' or rightparen ')'
+         **/
+        class formal_arg {
+        public:
+            using TypeDescr = xo::reflect::TypeDescr;
+
+        public:
+            formal_arg() = default;
+            formal_arg(const std::string & n, TypeDescr td) : name_{n}, td_{td} {}
+
+            const std::string & name() const { return name_; }
+            TypeDescr td() const { return td_; }
+
+            void assign_name(const std::string & x) { name_ = x; }
+            void assign_td(TypeDescr x) { td_ = x; }
+
+            void print(std::ostream & os) const {
+                os << "<formal_arg";
+                if (!name_.empty())
+                    os << xtag("name", name_);
+                if (td_)
+                    os << xtag("td", td_);
+                os << ">";
+            }
+
+        private:
+            /** formal parameter name **/
+            std::string name_;
+            /** type description for variable @p name **/
+            TypeDescr td_ = nullptr;
+        };
+
+        inline std::ostream &
+        operator<< (std::ostream & os,
+                    const formal_arg & x) {
+            x.print(os);
+            return os;
+        }
+    } /*namespace scm*/
+} /*namespace xo*/
+
+
+/* end formal_arg.hpp */
diff --git a/xo-reader/include/xo/reader/if_else_xs.hpp b/xo-reader/include/xo/reader/if_else_xs.hpp
new file mode 100644
index 00000000..05ab0c60
--- /dev/null
+++ b/xo-reader/include/xo/reader/if_else_xs.hpp
@@ -0,0 +1,109 @@
+/** @file if_else_xs.hpp
+ *
+ *  author: Roland Conybeare, Jul 2025
+ **/
+
+#pragma once
+
+#include "xo/expression/IfExpr.hpp"
+#include "exprstate.hpp"
+#include "xo/indentlog/print/ppdetail_atomic.hpp"
+
+namespace xo {
+    namespace scm {
+        /**
+         *   if test-expr then then-expr else else-expr ;
+         *  ^  ^         ^    ^         ^    ^         ^
+         *  |  |         |    |         |    |         |
+         *  |  if_1      if_2 if_3      if_4 if_5      if_6
+         *  if_0
+         *
+         *  if_0 --on_if_token()--> if_1
+         *  if_1 --on_expr()--> if_2
+         *  if_2 --on_then_token()--> if_3
+         *  if_3 --on_expr()--> if_4
+         *  if_4 --on_else_token()--> if_5
+         *       --on_semicolon_token()--> (done)
+         *  if_5 --on_expr()-->if_6
+         *  if_6 --on_semicolon_token()--> (done)
+         **/
+        enum class ifexprstatetype {
+            invalid = -1,
+
+            if_0,
+            if_1,
+            if_2,
+            if_3,
+            if_4,
+            if_5,
+            if_6,
+
+            n_ifexprstatetype,
+        };
+
+        extern const char * ifexprstatetype_descr(ifexprstatetype x);
+
+        std::ostream &
+        operator<<(std::ostream & os, ifexprstatetype x);
+
+        /** @class if_else_xs
+         *  @brief state to provide parsing of a conditional expression
+         **/
+        class if_else_xs : public exprstate {
+        public:
+            using IfExprAccess = xo::scm::IfExprAccess;
+
+        public:
+            if_else_xs(rp<IfExprAccess> if_expr);
+            virtual ~if_else_xs() = default;
+
+            static const if_else_xs * from(const exprstate * x) { return dynamic_cast<const if_else_xs *>(x); }
+
+            static void start(parserstatemachine * p_psm);
+
+            // ----- inherited from exprstate -----
+
+            virtual const char * get_expect_str() const override;
+
+            virtual void on_if_token(const token_type & tk,
+                                     parserstatemachine * p_psm) override;
+            virtual void on_then_token(const token_type & tk,
+                                       parserstatemachine * p_psm) override;
+            virtual void on_else_token(const token_type & tk,
+                                       parserstatemachine * p_psm) override;
+            virtual void on_semicolon_token(const token_type & tk,
+                                            parserstatemachine * p_psm) override;
+            virtual void on_rightbrace_token(const token_type & tk,
+                                             parserstatemachine * p_psm) override;
+
+            virtual void on_expr(bp<Expression> expr,
+                                 parserstatemachine * p_psm) override;
+            virtual void on_expr_with_semicolon(bp<Expression> expr,
+                                                parserstatemachine * p_psm) override;
+
+            virtual void print(std::ostream & os) const override;
+
+        private:
+            static std::unique_ptr<if_else_xs> make();
+
+            /** exit this exprstate,
+             *  and deliver @ref if_expr_ to parent exprstate
+             **/
+            void finish_and_continue(parserstatemachine * p_psm);
+
+        private:
+            ifexprstatetype ifxs_type_;
+            /** scaffold output expression here **/
+            rp<IfExprAccess> if_expr_;
+
+        };
+    } /*namespace scm*/
+
+    namespace print {
+#ifndef ppdetail_atomic
+        PPDETAIL_ATOMIC(xo::scm::ifexprstatetype);
+#endif
+    }
+} /*namespace xo*/
+
+/* end if_else_xs.hpp */
diff --git a/xo-reader/include/xo/reader/lambda_xs.hpp b/xo-reader/include/xo/reader/lambda_xs.hpp
new file mode 100644
index 00000000..0d4d89cb
--- /dev/null
+++ b/xo-reader/include/xo/reader/lambda_xs.hpp
@@ -0,0 +1,123 @@
+/** @file lambda_xs.hpp
+ *
+ *  Author: Roland Conybeare
+ **/
+
+#pragma once
+
+#include "exprstate.hpp"
+#include "xo/expression/LocalSymtab.hpp"
+//#include <cstdint>
+
+namespace xo {
+    namespace scm {
+        /**
+         * @text
+         *
+         *   lambda ( name(1) : type(1), ..., ) : type body-expr ;
+         *  ^      ^                           ^ ^    ^         ^
+         *  |      |                           | |    lm_4      lm_5
+         *  |      |                           | lm_3
+         *  lm_0   lm_1                        lm_2
+         *
+         *  lm_0 --on_lambda_token()--> lm_1
+         *  lm_1 --on_formal_arglist()--> lm_2
+         *  lm_2 --on_expr()--> lm_3
+         *  lm_5 --on_semicolon_token()--> (done)
+         *
+         * @endtext
+         **/
+        enum class lambdastatetype {
+            invalid = -1,
+
+            lm_0,
+            lm_1,
+            lm_2,
+            lm_3,
+            lm_4,
+            lm_5,
+
+            n_lambdastatetype
+        };
+
+        extern const char *
+        lambdastatetype_descr(lambdastatetype x);
+
+        inline std::ostream &
+        operator<< (std::ostream & os, lambdastatetype x) {
+            os << lambdastatetype_descr(x);
+            return os;
+        }
+
+        /** @class lambda_xs
+         *  @brief parsing state-machine for a lambda-expression
+         *
+         **/
+        class lambda_xs : public exprstate {
+        public:
+            using SymbolTable = xo::scm::SymbolTable;
+            using LocalSymtab = xo::scm::LocalSymtab;
+
+        public:
+            lambda_xs();
+
+            static void start(parserstatemachine * p_psm);
+
+            virtual const char * get_expect_str() const override;
+
+            virtual void on_lambda_token(const token_type & tk,
+                                         parserstatemachine * p_psm) override;
+            virtual void on_typedescr(TypeDescr td,
+                                      parserstatemachine * p_psm) override;
+            virtual void on_formal_arglist(const std::vector<rp<Variable>> & argl,
+                                           parserstatemachine * p_psm) override;
+            virtual void on_expr(bp<Expression> expr,
+                                 parserstatemachine * p_psm) override;
+            virtual void on_expr_with_semicolon(bp<Expression> expr,
+                                                parserstatemachine * p_psm) override;
+            virtual void on_leftbrace_token(const token_type & tk,
+                                            parserstatemachine * p_psm) override;
+            virtual void on_colon_token(const token_type & tk,
+                                        parserstatemachine * p_psm) override;
+            virtual void on_semicolon_token(const token_type & tk,
+                                            parserstatemachine * p_psm) override;
+            virtual void on_f64_token(const token_type & tk,
+                                      parserstatemachine * p_psm) final override;
+
+            virtual void print(std::ostream & os) const override;
+            virtual bool pretty_print(const print::ppindentinfo & ppii) const override;
+
+        private:
+            static std::unique_ptr<lambda_xs> make();
+
+        private:
+            /** parsing state-machine state **/
+            lambdastatetype lmxs_type_ = lambdastatetype::lm_0;
+
+            /** lambda environment (for formal parameters) **/
+            rp<LocalSymtab> local_env_;
+
+            /** explicit return type (if supplied) **/
+            TypeDescr explicit_return_td_ = nullptr;
+
+            /** lambda signature (when known) **/
+            TypeDescr lambda_td_ = nullptr;
+
+            /** body expression **/
+            rp<Expression> body_;
+
+            /** parent environment **/
+            rp<SymbolTable> parent_env_;
+
+        };
+    } /*namespace scm*/
+
+    namespace print {
+#ifndef ppdetail_atomic
+        PPDETAIL_ATOMIC(xo::scm::lambdastatetype);
+#endif
+    }
+} /*namespace xo*/
+
+
+/** end lambda_xs.hpp **/
diff --git a/xo-reader/include/xo/reader/let1_xs.hpp b/xo-reader/include/xo/reader/let1_xs.hpp
new file mode 100644
index 00000000..cdd00df4
--- /dev/null
+++ b/xo-reader/include/xo/reader/let1_xs.hpp
@@ -0,0 +1,66 @@
+/* file let1_xs.hpp
+ *
+ * author: Roland Conybeare, Aug 2024
+ */
+
+#pragma once
+
+#include "exprstate.hpp"
+#include "xo/expression/LocalSymtab.hpp"
+
+namespace xo {
+    namespace scm {
+        class let1_xs : public exprstate {
+        public:
+            using LocalEnv = xo::scm::LocalSymtab;
+
+        public:
+            /** given local definition equivalent to
+             *   def lhs_name = rhs;
+             *   rest...
+             *  parse sequence of incoming expressions rest... (until '}')
+             *
+             *  Result expression creates and inits @p lhs_name,
+             *  then evaluates expressions that follow definition
+             *  up to same-level '}'
+             **/
+            static void start(const std::string & lhs_name,
+                              const rp<Expression> & rhs,
+                              parserstatemachine * p_psm);
+
+            virtual void on_expr(bp<Expression> expr,
+                                 parserstatemachine * p_psm) override;
+            virtual void on_expr_with_semicolon(bp<Expression> expr,
+                                                parserstatemachine * p_psm) override;
+
+            virtual void on_rightbrace_token(const token_type & tk,
+                                             parserstatemachine * p_psm) override;
+
+        private:
+            let1_xs(std::string lhs_name,
+                    rp<LocalEnv> local_env,
+                    rp<Expression> rhs);
+
+            /** named ctor idiom **/
+            static std::unique_ptr<let1_xs> make(std::string lhs_name,
+                                                 rp<LocalEnv> local_env,
+                                                 rp<Expression> rhs);
+
+        private:
+            /** name for new local variable **/
+            std::string lhs_name_;
+            /** environment. contains just @ref lhs_name_ **/
+            rp<LocalEnv> local_env_;
+            /** set initial value for @ref lhs_name_ from value of this expression **/
+            rp<Expression> rhs_;
+
+            /** evaluate expressions in this sequence, in order, in environment
+             *  with variable @ref lhs_name_ defined
+             **/
+            std::vector<rp<Expression>> expr_v_;
+        };
+    } /*namespace scm*/
+} /*namespace xo*/
+
+
+/* end let1_xs.hpp */
diff --git a/xo-reader/include/xo/reader/paren_xs.hpp b/xo-reader/include/xo/reader/paren_xs.hpp
new file mode 100644
index 00000000..ab7da4fc
--- /dev/null
+++ b/xo-reader/include/xo/reader/paren_xs.hpp
@@ -0,0 +1,92 @@
+/** @file paren_xs.hpp
+ *
+ *  Author: Roland Conybeare
+ **/
+
+#pragma once
+
+#include "exprstate.hpp"
+//#include <cstdint>
+
+namespace xo {
+    namespace scm {
+        enum class parenexprstatetype {
+            invalid = -1,
+
+            lparen_0,
+            lparen_1,
+
+            n_parenexprstatetype,
+        };
+
+        extern const char *
+        parenexprstatetype_descr(parenexprstatetype x);
+
+        inline std::ostream &
+        operator<< (std::ostream & os, parenexprstatetype x) {
+            os << parenexprstatetype_descr(x);
+            return os;
+        }
+
+        /** @class paren_xs
+         *  @brief state machine for handling parentheses in expressions
+         **/
+        class paren_xs : public exprstate {
+        public:
+            paren_xs();
+            virtual ~paren_xs() = default;
+
+            static const paren_xs * from(const exprstate * x) { return dynamic_cast<const paren_xs *>(x); }
+
+            static void start(parserstatemachine * p_psm);
+
+            bool admits_f64() const;
+            bool admits_rightparen() const;
+
+            virtual void on_expr(bp<Expression> expr,
+                                 parserstatemachine * p_psm) override;
+            virtual void on_symbol(const std::string & symbol,
+                                   parserstatemachine * p_psm) override;
+            virtual void on_typedescr(TypeDescr td,
+                                      parserstatemachine * p_psm) override;
+
+            virtual void on_def_token(const token_type & tk,
+                                      parserstatemachine * p_psm) override;
+            virtual void on_symbol_token(const token_type & tk,
+                                         parserstatemachine * p_psm) override;
+            virtual void on_colon_token(const token_type & tk,
+                                        parserstatemachine * p_psm) override;
+            virtual void on_semicolon_token(const token_type & tk,
+                                            parserstatemachine * p_psm) override;
+            virtual void on_singleassign_token(const token_type & tk,
+                                               parserstatemachine * p_psm) override;
+            virtual void on_leftparen_token(const token_type & tk,
+                                            parserstatemachine * p_psm) override;
+            virtual void on_rightparen_token(const token_type & tk,
+                                             parserstatemachine * p_psm) override;
+            virtual void on_i64_token(const token_type & tk,
+                                      parserstatemachine * p_psm) override;
+            virtual void on_f64_token(const token_type & tk,
+                                      parserstatemachine * p_psm) override;
+
+            virtual void print(std::ostream & os) const override;
+
+        private:
+            static std::unique_ptr<paren_xs> make();
+
+        private:
+            /**
+             *  ( foo ... )
+             *   ^
+             *   |
+             *   lparen_0
+             **/
+            parenexprstatetype parenxs_type_;
+            /** populate expression (representing parenthesized value) here **/
+            rp<Expression> gen_expr_;
+        };
+    } /*namespace scm*/
+} /*namespace xo*/
+
+
+/** end paren_xs.hpp **/
diff --git a/xo-reader/include/xo/reader/parser.hpp b/xo-reader/include/xo/reader/parser.hpp
new file mode 100644
index 00000000..9db626ee
--- /dev/null
+++ b/xo-reader/include/xo/reader/parser.hpp
@@ -0,0 +1,262 @@
+/* file parser.hpp
+ *
+ * author: Roland Conybeare, Jul 2024
+ */
+
+#pragma once
+
+#include "exprstatestack.hpp"
+#include "envframestack.hpp"
+#include "parser_result.hpp"
+#include "parserstatemachine.hpp"
+#include "xo/expression/GlobalSymtab.hpp"
+#include <stdexcept>
+
+namespace xo {
+    namespace scm {
+        /** schematica parser
+         *
+         *  Examples:
+         *
+         *    decltype point
+         *
+         *    // forward declarations
+         *    decl pi : f64;
+         *    decl fib(n : i32) -> i32;
+         *
+         *    def pi = 3.14159265;  // constant. = is single assignment
+         *
+         *    def fib(n : i32) -> i32 {
+         *      // nested defs ok
+         *      def aux(n : i32, s1 : i32, s2 : i32) -> i32 {
+         *        // or:
+         *        //   (n == 0) ? s1 : aux(n - 1, s1 + s2, s1)
+         *        //
+         *        if (n == 0) {
+         *          s1;
+         *        } else {
+         *          aux(n - 1, s1 + s2, s1);
+         *        }
+         *
+         *        // or:
+         *        //  if (n == 0) ? s1 : aux(n - 1, s1 + s2, s1)
+         *      }
+         *
+         *      aux(n=n, s1=1, s2=0);
+         *    }
+         *
+         *    def x := "fu"; // non-constant
+         *    x += "bar";
+         *
+         *    def anotherfib = lambda(n : i32) { fib(n) };
+         *
+         *    def any : object;
+         *    def l : list<object> = '();
+         *
+         *    deftype point :: {x : f64, y : f64};
+         *    deftype polar :: {arg : f64, mag : f64};
+         *    deftype converter :: (point -> polar);
+         *
+         *    def polar2rect(pt : polar) -> point {
+         *      point(x = pt.mag * cos(arg),
+         *            y = pt.mag * sin(arg));
+         *    }
+         *
+         * Grammar:
+         *   toplevel-program = $toplevel-expression(1); ..; $toplevel-expression(n)
+         *
+         * if interactive:
+         *   toplevel-expression = expression
+         * else
+         *   toplevel-expression = type-decl | define-expr
+         *
+         *   type-decl        = decltype $typename [<$tp1 .. $tpn>]
+         *   expression       = type-decl
+         *                       | define-expr
+         *                       | literal-expr
+         *                       | variable-expr
+         *                       | apply-expr
+         *                       | if-expr
+         *                       | lambda-expr
+         *                       | arithmetic-expr
+         *                       | block
+         *
+         *   define-expr      = type-decl
+         *                       | type-def
+         *                       | variable-def
+         *                       | function-decl
+         *                       | function-def
+         *
+         *   type-def         = deftype $typename [<$tp1 .. $tpn>] :: type-def-rhs
+         *   type-def-rhs     = object
+         *                       | bool
+         *                       | i128 | i64 | i32 | i16 | i8
+         *                       | f128 | f64 | f32 | f16
+         *                       | struct $typename { ($membername(i) : $typename(i))* }
+         *                          [end $typename]
+         *                       | tuple $typename { $typename(1), .., $typename(n) }
+         *                          [end $typename]
+         *                       | copytype $typename
+         *                       | subtype $typename { ($member(i) : $typename(i))* }
+         *
+         *   variable-def     = decl $varname [: $typename] [= expression]
+         *   function-decl    = decl $functionname($varname(1) : $typename(1),
+         *                                         ..,
+         *                                         $varname(n) : $typename(n)) -> $typename[ret]
+         *   function-def     = def $functionname($varname(1) : $typename(1),
+         *                                        ..,
+         *                                        $varname(n) : $typename(n)) [-> $typename[ret]]
+         *                       body-expr
+         *                       [ end $functionname ]
+         *   literal-expr     = boolean-literal
+         *                       | integer-literal
+         *                       | fp-literal
+         *                       | string-literal
+         *                       | symbol-literal
+         *                       | struct-literal
+         *
+         *
+         *   boolean-literal  = true | false
+         *
+         *   variable-expr    = $varname
+         *   apply-expr       = fn-expr(arg-expr(1), .., arg-expr(n))
+         *     fn-expr          = expression
+         *     arg-expr(i)      = expression
+         *
+         *   if-expr          = if (test-expr) then-block else else-block
+         *                       | ((test-expr) ? then-expr : else-expr)
+         *     test-expr        = expression
+         *     then-block       = block
+         *     else-block       = block
+         *
+         *   block            = { (definition | expression)* }
+         *
+         *   lambda-expr      = lambda ($paramname(1) : $type(1),
+         *                              ..,
+         *                              $paramname(n) : $type(n)) body-expr
+         *    body-expr       = expression
+         *
+         *   arithmetic-expr  = expression binop expression
+         *
+         *    binop           = +
+         *                       | -
+         *                       | *
+         *                       | /
+         *                       | |
+         *                       | &
+         *                       | ^
+         *                       | ==
+         *                       | !=
+         *                       | <
+         *                       | <=
+         *                       | =>
+         *                       | >
+         *
+         **/
+        class parser {
+        public:
+            using Expression = xo::scm::Expression;
+            using token_type = exprstate::token_type; // token<char>;
+
+        public:
+            /** create parser in initial state;
+             *  parser is ready to receive tokens via @ref include_token
+             *
+             *  At least for xo-interpreter will have non-empty symbol table.
+             *
+             *  @p toplevel_symtab  symbol table.
+             *  @p debug_flag  true to enable debug logging
+             **/
+            parser(const rp<GlobalSymtab> & toplevel_symtab, bool debug_flag);
+
+            bool debug_flag() const { return psm_.debug_flag(); }
+
+            /** true if parser is at top-level,
+             *  i.e. ready for next top-level expression
+             **/
+            bool is_at_toplevel() const { return stack_size() == 0; }
+
+            /** for diagnostics: number of entries in parser stack **/
+            std::size_t stack_size() const { return psm_.xs_stack_.size(); }
+            /** for diagnostics: exprstatetype at level @p i
+             *  (taken relative to top of stack)
+             *
+             *  @pre 0 <= i < stack_size
+             **/
+            exprstatetype i_exstype(std::size_t i) const {
+                std::size_t z = psm_.xs_stack_.size();
+
+                if (i < z) {
+                    return psm_.xs_stack_[i]->exs_type();
+                }
+
+                /* out of bounds */
+                return exprstatetype::invalid;
+            }
+
+            exprstate const * i_exstate(std::size_t i) const {
+                std::size_t z = psm_.xs_stack_.size();
+
+                if (i < z) {
+                    return psm_.xs_stack_[i].get();
+                }
+
+                /* out of bounds */
+                return nullptr;
+            }
+
+            /** true iff parser contains state for an incomplete expression.
+             *  For this to be true,  parser must have consumed at least one token
+             *  since end of last toplevel expression
+             **/
+            bool has_incomplete_expr() const;
+
+            /** put parser into state for beginning an interactive session.
+             **/
+            void begin_interactive_session();
+
+            /** put parser into state for beginning of a translation unit
+             *  (i.e. input stream)
+             **/
+            void begin_translation_unit();
+
+            /** include next token @p tk and increment parser state.
+             *
+             *  @param tk  next input token
+             *  @return parsed expression, if @p tk completes an expression.
+             *  otherwise nullptr
+             **/
+            const parser_result & include_token(const token_type & tk);
+
+            /** reset parsed result expression; use using return value from
+             *  @ref include_token. Complicating api here to avoid copying parser_result
+             *  on each token
+             **/
+            void reset_result();
+
+            /** reset to starting parsing state.
+             *  use this after encountering an error, to avoid cascade of
+             *  spurious secondary errors..  particularly important when
+             *  invoked asa part of a REPL.
+             **/
+            void reset_to_idle_toplevel();
+
+            /** print human-readable representation on stream @p os **/
+            void print(std::ostream & os) const;
+
+        private:
+            /** state machine **/
+            parserstatemachine psm_;
+        }; /*parser*/
+
+        inline std::ostream &
+        operator<< (std::ostream & os,
+                    const parser & x) {
+            x.print(os);
+            return os;
+        }
+
+    } /*namespace scm*/
+} /*namespace xo*/
+
+/* end parser.hpp */
diff --git a/xo-reader/include/xo/reader/parser_result.hpp b/xo-reader/include/xo/reader/parser_result.hpp
new file mode 100644
index 00000000..8ccee992
--- /dev/null
+++ b/xo-reader/include/xo/reader/parser_result.hpp
@@ -0,0 +1,65 @@
+/* file parser_result.hpp
+ *
+ * author: Roland Conybeare, Jul 2025
+ */
+
+#pragma once
+
+#include "xo/expression/Expression.hpp"
+
+namespace xo {
+    namespace scm {
+        enum parser_result_type {
+            /** no result yet (incomplete expression) **/
+            none,
+            /** emit expression **/
+            expression,
+            /** emit error **/
+            error
+        };
+
+        struct parser_result {
+            using Expression = xo::scm::Expression;
+
+        public:
+            parser_result() = default;
+            parser_result(parser_result_type type, rp<Expression> expr, const char * src_fn, std::string errmsg);
+
+            static parser_result none();
+            static parser_result error(const char * error_src_function,
+                                       std::string errmsg);
+            static parser_result expression(rp<Expression> expr);
+
+            bool is_none() const { return result_type_ == parser_result_type::none; }
+            bool is_expression() const { return result_type_ == parser_result_type::expression; }
+            bool is_error() const { return result_type_ == parser_result_type::error; }
+
+            parser_result_type result_type() const { return result_type_; }
+            const rp<Expression> & result_expr() const { return result_expr_; }
+            const char * error_src_function() const { return error_src_function_; }
+            const std::string & error_description() const { return error_description_; }
+
+        public:
+            /** none|expression|error_description
+             *
+             *  @text
+             *   result_type | error_src_function | error_description
+             *  -------------+--------------------+-------------------
+             *          none |            nullptr |             empty
+             *    expression |            nullptr |             empty
+             *         error |           non-null |         non-empty
+             *  @endtext
+             **/
+            parser_result_type result_type_ = parser_result_type::none;
+            /** if @ref result_state is parser_result_state::expression -> non-null result expression **/
+            rp<Expression> result_expr_;
+            /** if @ref result_state is parser_result_state::error -> non-null source function **/
+            const char * error_src_function_ = nullptr;
+            /** if @ref result_state is parser_result_state::error -> non-empty error description **/
+            std::string error_description_;
+        };
+
+    } /*namespace scm*/
+} /*namespace xo*/
+
+/* end parser_result.hpp */
diff --git a/xo-reader/include/xo/reader/parserstatemachine.hpp b/xo-reader/include/xo/reader/parserstatemachine.hpp
new file mode 100644
index 00000000..9cec6ee3
--- /dev/null
+++ b/xo-reader/include/xo/reader/parserstatemachine.hpp
@@ -0,0 +1,129 @@
+/* file parserstatemachine.hpp
+ *
+ * author: Roland Conybeare, Aug 2024
+ */
+
+#pragma once
+
+#include "exprstate.hpp"
+#include "exprstatestack.hpp"
+#include "envframestack.hpp"
+#include "parser_result.hpp"
+#include "xo/expression/typeinf/type_unifier.hpp"
+
+namespace xo {
+    namespace scm {
+        /** @class parserstatemachine
+         *  @brief public parser state.
+         *
+         *  Schematica parser state; sent to subsidiary single-feature state machines.
+         *  For example entry points for the lambda feature (@ref lambda_xs)
+         *  will accept a non-const parserstatemachine pointer argument
+         **/
+        class parserstatemachine {
+        public:
+            using Expression = xo::scm::Expression;
+            using Variable = xo::scm::Variable;
+            using LocalEnv = xo::scm::LocalSymtab;
+            using token_type = token<char>;
+
+        public:
+            explicit parserstatemachine(bool debug_flag)
+                : debug_flag_{debug_flag}
+                {}
+
+            //const parser_result & result() const { return result_; }
+            //parser_result_state result_state() const { return result_state_; }
+            //const rp<Expression> & result_expr() const { return result_expr_; }
+            //const char * error_src_function() const { return error_src_function_; }
+            //const std::string & error_description() const { return error_description_; }
+
+            std::unique_ptr<exprstate> pop_exprstate();
+            exprstate & top_exprstate();
+            /** get exprstate @p i levels from the top **/
+            const exprstate & lookup_exprstate(size_t i) const;
+            void push_exprstate(std::unique_ptr<exprstate> x);
+            /** @return number of stacked expression states **/
+            size_t exprstate_stack_size() const { return  xs_stack_.size(); }
+
+            bool debug_flag() const { return debug_flag_; }
+
+            /** lookup variable name in lexical context represented by
+             *  this psm.  nullptr if not found
+             **/
+            bp<Variable> lookup_var(const std::string & x) const;
+
+            /** update/replace binding for variable @p x in lexical context
+             *  represented by this psm.  Always acts on innermost frame.
+             **/
+            void upsert_var(bp<Variable> x);
+
+            /** @return available variable bindings in current parsing state **/
+            bp<SymbolTable> top_envframe() const;
+            /** @return frame @p i levels from the top **/
+            bp<SymbolTable> lookup_envframe(std::size_t i) const;
+            /** push frame @p x (with new variable bindings) onto environment stack **/
+            void push_envframe(const rp<LocalEnv> & x);
+            /** @return pop innermost environment frame and return it **/
+            rp<SymbolTable> pop_envframe();
+            /** @return number of stacked environment frames **/
+            size_t env_stack_size() const { return  env_stack_.size(); }
+
+            // ----- parsing outputs -----
+
+            void on_expr(bp<Expression> expr);
+            void on_expr_with_semicolon(bp<Expression> expr);
+            void on_symbol(const std::string & symbol);
+
+            // ----- parsing inputs -----
+
+            void on_semicolon_token(const token_type & tk);
+            void on_operator_token(const token_type & tk);
+            void on_leftbrace_token(const token_type & tk);
+            void on_rightbrace_token(const token_type & tk);
+            void on_then_token(const token_type & tk);
+            void on_else_token(const token_type & tk);
+            void on_f64_token(const token_type & tk);
+
+            // ----- parsing error -----
+
+            /** @p self_name  location (implementation function) where error detected
+             **/
+            void on_error(const char * self_name, std::string error_description);
+
+            /** write human-readable representation on @p os **/
+            void print(std::ostream & os) const;
+
+        public:
+            /** state recording state associated with enclosing expressions.
+             *
+             *  Note: at least asof c++23, the std::stack api doesn't support access
+             *  to members other than the top.
+             *
+             *  for stack with N elements (N = stack_.size()):
+             *  - bottom of stack is stack_[0]
+             *  - top of stack is stack_[N-1]
+             **/
+            exprstatestack xs_stack_;
+            /** environment frames for lexical context.
+             *  push a frame on each nested lambda;
+             *  pop when lambda body goes out of scope
+             **/
+            envframestack env_stack_;
+            /** type inference/unification.
+             *  apply to unresolved types associated with @ref Expression instances.
+             **/
+            type_unifier unifier_;
+            /** parser result state (as of last call to @ref exprstate::on_input) **/
+            parser_result result_;
+            /** enable/disable debug logging **/
+            bool debug_flag_ = false;
+        };
+
+        inline std::ostream &
+        operator<<(std::ostream & os, const parserstatemachine & x) {
+            x.print(os);
+            return os;
+        }
+    } /*namespace scm*/
+} /*namespace xo*/
diff --git a/xo-reader/include/xo/reader/pretty_envframestack.hpp b/xo-reader/include/xo/reader/pretty_envframestack.hpp
new file mode 100644
index 00000000..842368fa
--- /dev/null
+++ b/xo-reader/include/xo/reader/pretty_envframestack.hpp
@@ -0,0 +1,28 @@
+/* file pretty_envframestack.hpp
+ *
+ * author: Roland Conybeare, Jul 2025
+ */
+
+#pragma once
+
+#include "envframestack.hpp"
+#include "xo/indentlog/print/pretty.hpp"
+
+namespace xo {
+    namespace print {
+        template <>
+        struct ppdetail<const xo::scm::envframestack*> {
+            static inline bool print_pretty(const ppindentinfo & ppii, const xo::scm::envframestack * p) {
+                return p->pretty_print(ppii);
+            }
+        };
+
+        template <>
+        struct ppdetail<xo::scm::envframestack*> {
+            static inline bool print_pretty(const ppindentinfo & ppii, const xo::scm::envframestack * p) {
+                return p->pretty_print(ppii);
+            }
+        };
+
+    } /*namespace print*/
+} /*namespace xo*/
diff --git a/xo-reader/include/xo/reader/pretty_exprstatestack.hpp b/xo-reader/include/xo/reader/pretty_exprstatestack.hpp
new file mode 100644
index 00000000..bc8f6606
--- /dev/null
+++ b/xo-reader/include/xo/reader/pretty_exprstatestack.hpp
@@ -0,0 +1,34 @@
+/* file pretty_exprstatestack.hpp
+ *
+ * author: Roland Conybeare, Jul 2025
+ */
+
+#pragma once
+
+#include "exprstatestack.hpp"
+#include "xo/indentlog/print/pretty.hpp"
+
+namespace xo {
+    namespace print {
+        template <>
+        struct ppdetail<xo::scm::exprstatestack*> {
+            static inline bool print_pretty(const ppindentinfo & ppii, const xo::scm::exprstatestack * p) {
+                return p->pretty_print(ppii);
+            }
+        };
+
+        template <>
+        struct ppdetail<const xo::scm::exprstatestack*> {
+            static inline bool print_pretty(const ppindentinfo & ppii, const xo::scm::exprstatestack * p) {
+                return p->pretty_print(ppii);
+            }
+        };
+
+        template <>
+        struct ppdetail<xo::scm::exprstate*> {
+            static inline bool print_pretty(const ppindentinfo & ppii, const xo::scm::exprstate * p) {
+                return p->pretty_print(ppii);
+            }
+        };
+    } /*namespace print*/
+} /*namespace xo*/
diff --git a/xo-reader/include/xo/reader/pretty_parserstatemachine.hpp b/xo-reader/include/xo/reader/pretty_parserstatemachine.hpp
new file mode 100644
index 00000000..50e6737f
--- /dev/null
+++ b/xo-reader/include/xo/reader/pretty_parserstatemachine.hpp
@@ -0,0 +1,23 @@
+/* file pretty_parserstatemachine.hpp
+ *
+ * author: Roland Conybeare, Jul 2025
+ */
+
+#pragma once
+
+#include "parserstatemachine.hpp"
+#include "xo/indentlog/print/pretty.hpp"
+
+namespace xo {
+    namespace print {
+        template<>
+        struct ppdetail<xo::scm::parserstatemachine> {
+            static bool print_pretty(const ppindentinfo & ppii, const xo::scm::parserstatemachine & x);
+        };
+
+        template<>
+        struct ppdetail<xo::scm::parserstatemachine*> {
+            static bool print_pretty(const ppindentinfo & ppii, const xo::scm::parserstatemachine * x);
+        };
+    }
+} /*namespace xo*/
diff --git a/xo-reader/include/xo/reader/progress_xs.hpp b/xo-reader/include/xo/reader/progress_xs.hpp
new file mode 100644
index 00000000..1884623a
--- /dev/null
+++ b/xo-reader/include/xo/reader/progress_xs.hpp
@@ -0,0 +1,189 @@
+/** @file progress_xs.hpp
+ *
+ *  Author: Roland Conybeare
+ **/
+
+#pragma once
+
+#include "exprstate.hpp"
+#include "xo/reflect/TypeDescr.hpp"
+#include <iostream>
+//#include <cstdint>
+
+namespace xo {
+    namespace scm {
+        /** represent an infix operator.
+         *
+         *  See @ref progress_xs::assemble_expr() for translation
+         *  to Expression
+         **/
+        enum class optype {
+            invalid = -1,
+
+            /** op:= **/
+            op_assign,
+
+            /** op< **/
+            op_less,
+            /** op<= **/
+            op_less_equal,
+            /** op== **/
+            op_equal,
+            /** op!= **/
+            op_not_equal,
+            /** op> **/
+            op_great,
+            /** op>= **/
+            op_great_equal,
+
+            /** op+ **/
+            op_add,
+            /** op- **/
+            op_subtract,
+
+            /** op* **/
+            op_multiply,
+            /** op/ **/
+            op_divide,
+
+            n_optype
+        };
+
+        extern const char *
+        optype_descr(optype x);
+
+        /** report operator precedence.
+         *  lowest operator precedence is 1
+         **/
+        extern int
+        precedence(optype x);
+
+        inline std::ostream &
+        operator<< (std::ostream & os, optype x) {
+            os << optype_descr(x);
+            return os;
+        }
+
+        /** @class progress_xs
+         *  @brief state machine for parsing a schematica runtime-value-expression
+         *
+         *  Handles an expression that produces a value, for example appearing on the
+         *  right-hand side of a definition.
+         *
+         *  Deals with infix operators, handles operator precedence.
+         *  Also generates argument-type-specific arithmetic expressions,
+         *  for example using ``Apply::make_add2_f64()`` when adding floating-point numbers
+         *
+         *  One reason for this to exist is to simulate one-token lookahead.
+         *  To look at but not consume a token T, can push a progress_xs instance P,
+         *  then send T to P.
+         **/
+        class progress_xs : public exprstate {
+        public:
+            progress_xs(rp<Expression> valex, optype op);
+            virtual ~progress_xs() = default;
+
+            static const progress_xs * from(const exprstate * x) {
+                return dynamic_cast<const progress_xs *>(x);
+            }
+
+            static void start(rp<Expression> valex,
+                              optype optype,
+                              parserstatemachine * p_psm);
+            static void start(rp<Expression> valex,
+                              parserstatemachine * p_psm);
+
+            bool admits_f64() const;
+
+            void apply_type_error(const char * self_name,
+                                  optype op,
+                                  bp<Expression> expr1,
+                                  bp<Expression> expr2,
+                                  parserstatemachine * p_psm) const;
+
+            virtual const char * get_expect_str() const final override;
+
+            virtual void on_expr(bp<Expression> expr,
+                                 parserstatemachine * p_psm) override;
+            virtual void on_expr_with_semicolon(bp<Expression> expr,
+                                                parserstatemachine * p_psm) override;
+            virtual void on_symbol_token(const token_type & tk,
+                                         parserstatemachine * p_psm) override;
+            virtual void on_comma_token(const token_type & tk,
+                                        parserstatemachine * p_psm) final override;
+            virtual void on_typedescr(TypeDescr td,
+                                      parserstatemachine * p_psm) override;
+
+            virtual void on_def_token(const token_type & tk,
+                                      parserstatemachine * p_psm) override;
+            virtual void on_colon_token(const token_type & tk,
+                                        parserstatemachine * p_psm) override;
+            virtual void on_semicolon_token(const token_type & tk,
+                                            parserstatemachine * p_psm) override;
+            virtual void on_singleassign_token(const token_type & tk,
+                                               parserstatemachine * p_psm) override;
+            virtual void on_assign_token(const token_type & tk,
+                                         parserstatemachine * p_psm) final override;
+            virtual void on_leftparen_token(const token_type & tk,
+                                            parserstatemachine * p_psm) override;
+            virtual void on_rightparen_token(const token_type & tk,
+                                             parserstatemachine * p_psm) override;
+            virtual void on_rightbrace_token(const token_type & tk,
+                                             parserstatemachine * p_psm) override;
+            virtual void on_then_token(const token_type & tk,
+                                       parserstatemachine * p_psm) override;
+            virtual void on_else_token(const token_type & tk,
+                                       parserstatemachine * p_psm) override;
+
+            /* entry point for an infix operator token */
+            virtual void on_operator_token(const token_type & tk,
+                                           parserstatemachine * p_psm) final override;
+
+            virtual void on_bool_token(const token_type & tk,
+                                       parserstatemachine * p_psm) override;
+
+            virtual void on_i64_token(const token_type & tk,
+                                      parserstatemachine * p_psm) override;
+
+            virtual void on_f64_token(const token_type & tk,
+                                      parserstatemachine * p_psm) override;
+
+            virtual void print(std::ostream & os) const override;
+            virtual bool pretty_print(const print::ppindentinfo & ppii) const override;
+
+        private:
+            static std::unique_ptr<progress_xs> make(rp<Expression> valex,
+                                                     optype optype = optype::invalid);
+
+        private:
+            /** assemble expression representing
+             *  value of
+             *  @code
+             *    f(lhs_, rhs_)
+             *  @endcode
+             *
+             *  where f determined by @ref op_type_
+             **/
+            rp<Expression> assemble_expr(parserstatemachine * p_psm);
+
+        private:
+            /** populate an expression here, may be followed by an operator **/
+            rp<Expression> lhs_;
+
+            /** infix operator,  if supplied **/
+            optype op_type_ = optype::invalid;
+
+            /** populate an expression here, following infix operator */
+            rp<Expression> rhs_;
+        };
+    } /*namespace scm*/
+
+#ifndef ppdetail_atomic
+    namespace print {
+        PPDETAIL_ATOMIC(xo::scm::optype);
+    }
+#endif
+} /*namespace xo*/
+
+
+/** end progress_xs.hpp **/
diff --git a/xo-reader/include/xo/reader/reader.hpp b/xo-reader/include/xo/reader/reader.hpp
new file mode 100644
index 00000000..5d0ec503
--- /dev/null
+++ b/xo-reader/include/xo/reader/reader.hpp
@@ -0,0 +1,139 @@
+/* file reader.hpp
+ *
+ * author: Roland Conybeare, Aug 2024
+ */
+
+#pragma once
+
+#include "parser.hpp"
+#include "reader_error.hpp"
+#include "xo/expression/Expression.hpp"
+#include "xo/expression/GlobalSymtab.hpp"
+#include "xo/expression/pretty_expression.hpp"
+#include "xo/tokenizer/tokenizer.hpp"
+
+namespace xo {
+    namespace scm {
+        /** @class parse_result
+         *  @brief Result object returned from reader::read_expr
+         **/
+        struct reader_result {
+            using Expression = xo::scm::Expression;
+            using span_type = span<const char>;
+
+            reader_result(rp<Expression> expr, span_type rem, std::size_t psz, const reader_error & error)
+                : expr_{std::move(expr)}, rem_{rem}, parser_stack_size_{psz}, error_{error} {}
+
+            /** true if reader parsed a complete expression **/
+            bool expr_complete() const { return expr_.get(); }
+
+            /** parsed schematica expression **/
+            rp<Expression> expr_;
+            /** span giving text input consumed to construct expr,
+             *  including any leading whitespace.
+             *  This is the span returned in result of tokenizer<char>::scan()
+             **/
+            span_type rem_;
+
+            /** parser nesting level when this result delivered
+             *  will be zero whenever @ref expr_ is non-null
+             **/
+            std::size_t parser_stack_size_ = 0;
+
+            /** error description, whenever .error_.is_error() is true **/
+            reader_error error_;
+        };
+
+        /**
+         *  Use:
+         *  @code
+         *    reader rdr;
+         *    rdr.begin_translation_unit()
+         *
+         *    bool eof = false;
+         *    while (!eof) {
+         *        auto input = ins.read_some();
+         *        // eof: true if no more input will be forthcoming from this stream
+         *        eof = ins.eof();
+         *
+         *        for (auto rem = input; !rem.empty();) {
+         *            // res: (parsed-expr, used)
+         *            auto [expres = rdr.read_expr(rem, eof);
+         *
+         *            if (res.first) {
+         *                // do something with res.first (parsed expr)
+         *                ...
+         *            }
+         *
+         *            rem = rem.suffix_after(res.second);
+         *        }
+         *    }
+         *
+         *    // expect !rdr.has_prefix()
+         *
+         *  @endcode
+         **/
+        class reader {
+        public:
+            using tokenizer_type = tokenizer<char>;
+            using span_type = tokenizer_type::span_type;
+
+        public:
+            reader(const rp<GlobalSymtab> & toplevel_symtab, bool debug_flag);
+
+            bool debug_flag() const { return parser_.debug_flag(); }
+
+            /** call once before calling .read_expr()
+             *  for a new interactive session
+             **/
+            void begin_interactive_session();
+
+            /** counterpart to .begin_interactive_session()
+             **/
+            reader_result end_interactive_session();
+
+            /** call once before calling .read_expr():
+             *  1. with new reader
+             *  2. if last read_expr() call had eof=true
+             **/
+            void begin_translation_unit();
+
+            /** counterpart to .begin_translation_unit(),
+             *  provided for symmetry's sake
+             *
+             *  Equivalent to:
+             *  @code
+             *    read_expr(span_type(nullptr, nullptr), true);
+             *  @endcode
+             **/
+            reader_result end_translation_unit();
+
+            /** Try to read one expression from @p input.
+             *  Return struct containing parsed expression
+             *  and span of characters comprising that expression
+             *
+             *  @param input  Supply this input span of chars
+             *  @param eof.  True if input stream supplying @p input
+             *         reports end-of-file immediately after the last char
+             *         in @p input.
+             **/
+            reader_result read_expr(const span_type & input, bool eof);
+
+            /** reset to known starting point after encountering an error.
+             *  - remainder of stashed current line.
+             *    Necesary for well-formatted error reporting.
+             *  - current parsing state
+             **/
+            void reset_to_idle_toplevel();
+
+        private:
+            /** tokenizer: text -> tokens **/
+            tokenizer_type tokenizer_;
+
+            /** parser: tokens -> expressions **/
+            parser parser_;
+        };
+    } /*namespace scm*/
+} /*namespace xo*/
+
+/* end reader.hpp */
diff --git a/xo-reader/include/xo/reader/reader_error.hpp b/xo-reader/include/xo/reader/reader_error.hpp
new file mode 100644
index 00000000..d61db03e
--- /dev/null
+++ b/xo-reader/include/xo/reader/reader_error.hpp
@@ -0,0 +1,55 @@
+/* reader_error.hpp
+ *
+ * Author: Roland Conybeare, Jul 2025
+ */
+
+#pragma once
+
+#include "xo/tokenizer/tokenizer_error.hpp"
+
+namespace xo {
+    namespace scm {
+        class reader_error {
+        public:
+            using input_state_type = typename tokenizer_error<char>::input_state_type;
+
+        public:
+            /** default ctor represents a not-an-error sentinel object **/
+            reader_error() = default;
+            /** construct to capture parsing error context
+             *  @
+             **/
+            reader_error(const char * src_function,
+                         std::string error_description,
+                         const input_state_type & input_state,
+                         size_t error_pos)
+                : tk_error_{src_function, error_description, input_state, error_pos}
+                {}
+
+            const tokenizer_error<char> & tk_error() const { return tk_error_; }
+
+            /** true, except for sentinel not-an-error object **/
+            bool is_error() const { return tk_error_.is_error(); }
+            /** false, except for object in sentinel state **/
+            bool is_not_an_error() const { return tk_error_.is_not_an_error(); }
+
+            const char * src_function() const { return tk_error_.src_function(); }
+
+            /** print error representation to stream @p os.  Intended for parser/tokenizer
+             *  diagnostics.  For Schematika errors prefer @ref report
+             **/
+            void print(std::ostream & os) const { tk_error_.print(os); }
+
+            /** print human-oriented error report on @p os. **/
+            void report(std::ostream & os) const { tk_error_.report(os); }
+
+        private:
+            /** for parser-level errors, will still use this for
+             *  {src function, error description, input state and error pos}
+             **/
+            tokenizer_error<char> tk_error_;
+        };
+    }
+}
+
+/* end reader_error.hpp */
diff --git a/xo-reader/include/xo/reader/sequence_xs.hpp b/xo-reader/include/xo/reader/sequence_xs.hpp
new file mode 100644
index 00000000..cad81cf2
--- /dev/null
+++ b/xo-reader/include/xo/reader/sequence_xs.hpp
@@ -0,0 +1,52 @@
+/** @file sequence_xs.hpp
+ *
+ *  Author: Roland Conybeare
+ **/
+
+#pragma once
+
+#include "exprstate.hpp"
+#include <vector>
+
+namespace xo {
+    namespace scm { class Sequence; }
+    namespace scm { class Lambda; }
+
+    namespace scm {
+        class sequence_xs : public exprstate {
+        public:
+            using Sequence = xo::scm::Sequence;
+            using Lambda = xo::scm::Lambda;
+
+        public:
+            /** start parsing a sequence-expr.
+             *  input begins with first expression in the sequence.
+             **/
+            static void start(parserstatemachine * p_psm);
+
+            virtual void on_expr(bp<Expression> expr,
+                                 parserstatemachine * p_psm) override;
+            virtual void on_expr_with_semicolon(bp<Expression> expr,
+                                                parserstatemachine * p_psm) override;
+
+            virtual void on_rightbrace_token(const token_type & tk,
+                                             parserstatemachine * p_psm) override;
+
+            virtual void print(std::ostream & os) const override;
+            virtual bool pretty_print(const xo::print::ppindentinfo & ppii) const override;
+
+        private:
+            sequence_xs();
+
+            /** named ctor idiom **/
+            static std::unique_ptr<sequence_xs> make();
+
+        private:
+            /** will build SequenceExpr from in-order contents of this vector **/
+            std::vector<rp<Expression>> expr_v_;
+        };
+    } /*namespace scm*/
+} /*namespace xo*/
+
+
+/** end sequence_xs.hpp **/
diff --git a/xo-reader/src/reader/CMakeLists.txt b/xo-reader/src/reader/CMakeLists.txt
new file mode 100644
index 00000000..e8e8bf02
--- /dev/null
+++ b/xo-reader/src/reader/CMakeLists.txt
@@ -0,0 +1,33 @@
+# reader/CMakeLists.txt
+
+set(SELF_LIB xo_reader)
+set(SELF_SRCS
+    parser_result.cpp
+    parser.cpp
+    parserstatemachine.cpp
+    reader.cpp
+    exprstate.cpp
+    exprstatestack.cpp
+    define_xs.cpp
+    if_else_xs.cpp
+    progress_xs.cpp
+    apply_xs.cpp
+    paren_xs.cpp
+    sequence_xs.cpp
+    exprseq_xs.cpp
+    expect_expr_xs.cpp
+    expect_symbol_xs.cpp
+    expect_formal_xs.cpp
+    expect_formal_arglist_xs.cpp
+    expect_type_xs.cpp
+    lambda_xs.cpp
+    let1_xs.cpp
+    envframestack.cpp
+    pretty_parserstatemachine.cpp
+)
+
+xo_add_shared_library4(${SELF_LIB} ${PROJECT_NAME}Targets ${PROJECT_VERSION} 1 ${SELF_SRCS})
+xo_dependency(${SELF_LIB} xo_expression)
+xo_dependency(${SELF_LIB} xo_tokenizer)
+
+# end CMakeLists.txt
diff --git a/xo-reader/src/reader/apply_xs.cpp b/xo-reader/src/reader/apply_xs.cpp
new file mode 100644
index 00000000..8f5b557a
--- /dev/null
+++ b/xo-reader/src/reader/apply_xs.cpp
@@ -0,0 +1,189 @@
+/* @file apply_xs.cpp */
+
+#include "apply_xs.hpp"
+#include "parserstatemachine.hpp"
+#include "expect_expr_xs.hpp"
+
+namespace xo {
+    namespace scm {
+        // ----- applyexprstatetype -----
+
+        const char *
+        applyexprstatetype_descr(applyexprstatetype x) {
+            switch (x) {
+            case applyexprstatetype::invalid: return "invalid";
+            case applyexprstatetype::apply_0: return "apply_0";
+            case applyexprstatetype::apply_1: return "apply_1";
+            case applyexprstatetype::apply_2: return "apply_2";
+            case applyexprstatetype::apply_3: return "apply_3";
+            case applyexprstatetype::n_applyexprstatetype: break;
+            }
+
+            return "???applyexprstatetype";
+        }
+
+        std::ostream &
+        operator<<(std::ostream & os, applyexprstatetype x) {
+            os << applyexprstatetype_descr(x);
+            return os;
+        }
+
+        // ----- apply_xs -----
+
+        std::unique_ptr<apply_xs>
+        apply_xs::make() {
+            return std::make_unique<apply_xs>(apply_xs());
+        }
+
+        void
+        apply_xs::start(rp<Expression> fn_expr,
+                        parserstatemachine * p_psm)
+        {
+            scope log(XO_DEBUG(p_psm->debug_flag()));
+
+            p_psm->push_exprstate(apply_xs::make());
+            p_psm->top_exprstate().on_expr(fn_expr.get(), p_psm);
+            p_psm->top_exprstate().on_leftparen_token(token_type::leftparen(), p_psm);
+        }
+
+        apply_xs::apply_xs()
+            : exprstate(exprstatetype::applyexpr)
+        {}
+
+        const char *
+        apply_xs::get_expect_str() const {
+            switch(applyxs_type_) {
+            case applyexprstatetype::invalid: return "invalid";
+            case applyexprstatetype::apply_0: return "expr";
+            case applyexprstatetype::apply_1: return "lparen";
+            case applyexprstatetype::apply_2: return "expr";
+            case applyexprstatetype::apply_3: return "comma|rparen";
+            case applyexprstatetype::n_applyexprstatetype: break;
+            }
+
+            return "?expect";
+        }
+
+        void
+        apply_xs::on_expr(bp<Expression> expr,
+                          parserstatemachine * p_psm)
+        {
+            scope log(XO_DEBUG(p_psm->debug_flag()));
+
+            switch (applyxs_type_) {
+            case applyexprstatetype::invalid:
+            case applyexprstatetype::n_applyexprstatetype:
+                // unreachable
+                break;
+            case applyexprstatetype::apply_0:
+                log && log("stash fn -> new state apply_1");
+                this->fn_expr_ = expr.promote();
+                this->applyxs_type_ = applyexprstatetype::apply_1;
+                return;
+            case applyexprstatetype::apply_1:
+                log && log("error: was expecting lparen");
+                // error, expecting lparen
+                break;
+            case applyexprstatetype::apply_2:
+                log && log(xtag("expr", expr), xtag("do", "stash expr -> new state apply_3"));
+                this->args_expr_v_.push_back(expr.promote());
+                this->applyxs_type_ = applyexprstatetype::apply_3;
+                return;
+            case applyexprstatetype::apply_3:
+                // error, expecting comma|rparen
+                break;
+            }
+
+            /* control here --implies-> error state */
+
+            constexpr const char * c_self_name = "apply_xs::on_expr";
+            const char * exp = this->get_expect_str();
+
+            this->illegal_input_on_expr(c_self_name, expr, exp, p_psm);
+        }
+
+        void
+        apply_xs::on_comma_token(const token_type & tk,
+                                 parserstatemachine * p_psm)
+        {
+            scope log(XO_DEBUG(p_psm->debug_flag()));
+
+            if (this->applyxs_type_ == applyexprstatetype::apply_3) {
+                this->applyxs_type_ = applyexprstatetype::apply_2;
+                expect_expr_xs::start(p_psm);
+            } else {
+                constexpr const char * c_self_name = "apply_xs::on_comma_token";
+                const char * exp = this->get_expect_str();
+
+                this->illegal_input_on_token(c_self_name, tk, exp, p_psm);
+            }
+        }
+
+        void
+        apply_xs::on_leftparen_token(const token_type & tk,
+                                     parserstatemachine * p_psm)
+        {
+            scope log(XO_DEBUG(p_psm->debug_flag()));
+
+            log && log("applyxs_type", applyxs_type_);
+
+            if (this->applyxs_type_ == applyexprstatetype::apply_1) {
+                this->applyxs_type_ = applyexprstatetype::apply_2;
+                expect_expr_xs::start(p_psm);
+            } else {
+                constexpr const char * c_self_name = "apply_xs::on_leftparen_token";
+                const char * exp = this->get_expect_str();
+
+                this->illegal_input_on_token(c_self_name, tk, exp, p_psm);
+            }
+        }
+
+        void
+        apply_xs::on_rightparen_token(const token_type & tk,
+                                      parserstatemachine * p_psm)
+        {
+            scope log(XO_DEBUG(p_psm->debug_flag()));
+
+            log && log("applyxs_type", applyxs_type_);
+
+            if (this->applyxs_type_ == applyexprstatetype::apply_3) {
+                /* (done) state */
+                log("apply complete -> pop + send expr");
+
+                rp<Apply> apply_expr = Apply::make(this->fn_expr_, this->args_expr_v_);
+
+                std::unique_ptr<exprstate> self = p_psm->pop_exprstate();
+
+                p_psm->top_exprstate().on_expr(apply_expr, p_psm);
+                return;
+            }
+
+            constexpr const char * c_self_name = "apply_xs::on_rightparen_token";
+            const char * exp = this->get_expect_str();
+
+            this->illegal_input_on_token(c_self_name, tk, exp, p_psm);
+        }
+
+        void
+        apply_xs::print(std::ostream & os) const
+        {
+            os << "<apply_xs"
+               << xtag("this", (void*)this)
+               << xtag("applyxs_type", applyxs_type_);
+            os << ">";
+        }
+
+        bool
+        apply_xs::pretty_print(const xo::print::ppindentinfo & ppii) const
+        {
+            return ppii.pps()->pretty_struct(ppii, "apply_xs",
+                                             refrtag("applyxs_type", applyxs_type_),
+                                             refrtag("fn_expr", fn_expr_),
+                                             refrtag("args_expr_v", args_expr_v_));
+        }
+
+    } /*namespace scm*/
+} /*namespace xo*/
+
+
+/* end apply_xs.cpp */
diff --git a/xo-reader/src/reader/define_xs.cpp b/xo-reader/src/reader/define_xs.cpp
new file mode 100644
index 00000000..d5cf23df
--- /dev/null
+++ b/xo-reader/src/reader/define_xs.cpp
@@ -0,0 +1,368 @@
+/* @file define_xs.cpp */
+
+#include "define_xs.hpp"
+#include "parserstatemachine.hpp"
+#include "expect_symbol_xs.hpp"
+#include "expect_expr_xs.hpp"
+#include "expect_type_xs.hpp"
+#include "pretty_expression.hpp"
+
+namespace xo {
+    namespace scm {
+        // ----- defexprstatetype -----
+
+        const char *
+        defexprstatetype_descr(defexprstatetype x) {
+            switch (x) {
+            case defexprstatetype::invalid: return "invalid";
+            case defexprstatetype::def_0: return "def_0";
+            case defexprstatetype::def_1: return "def_1";
+            case defexprstatetype::def_2: return "def_2";
+            case defexprstatetype::def_3: return "def_3";
+            case defexprstatetype::def_4: return "def_4";
+            case defexprstatetype::def_5: return "def_5";
+            case defexprstatetype::def_6: return "def_6";
+            case defexprstatetype::n_defexprstatetype: break;
+            }
+
+            return "???defexprstatetype";
+        }
+
+        std::ostream &
+        operator<<(std::ostream & os, defexprstatetype x) {
+            os << defexprstatetype_descr(x);
+            return os;
+        }
+
+        // ----- define_xs -----
+
+        std::unique_ptr<define_xs>
+        define_xs::make() {
+            return std::make_unique<define_xs>(define_xs(DefineExprAccess::make_empty()));
+        }
+
+        void
+        define_xs::start(parserstatemachine * p_psm)
+        {
+            scope log(XO_DEBUG(p_psm->debug_flag()));
+
+            p_psm->push_exprstate(define_xs::make());
+            p_psm->top_exprstate().on_def_token(token_type::def(), p_psm);
+        }
+
+        define_xs::define_xs(rp<DefineExprAccess> def_expr)
+            : exprstate(exprstatetype::defexpr),
+              defxs_type_{defexprstatetype::def_0},
+              def_expr_{std::move(def_expr)}
+        {}
+
+        const char *
+        define_xs::get_expect_str() const
+        {
+            /*
+             *   def foo       = 1 ;
+             *   def foo : f64 = 1 ;
+             *  ^   ^   ^ ^   ^ ^ ^ ^
+             *  |   |   | |   | | | (done)
+             *  |   |   | |   | | def_6
+             *  |   |   | |   | def_5:expect_rhs_expression
+             *  |   |   | |   def_4
+             *  |   |   | def_3:expect_type
+             *  |   |   def_2
+             *  |   def_1:expect_symbol
+             *  expect_toplevel_expression_sequence
+             *
+             * note that we skip from def_2 -> def_5 if '=' instead of ':'
+             */
+            switch (this->defxs_type_) {
+            case defexprstatetype::invalid:
+            case defexprstatetype::def_0:
+            case defexprstatetype::n_defexprstatetype:
+                assert(false);  // impossible
+                return nullptr;
+            case defexprstatetype::def_1:
+                return "symbol";
+            case defexprstatetype::def_2:
+                return "singleassign|colon";
+            case defexprstatetype::def_4:
+                return "singleassign";
+            case defexprstatetype::def_3:
+                return "type";
+            case defexprstatetype::def_5:
+                return "expression";
+            case defexprstatetype::def_6:
+                return "semicolon";
+            }
+
+            return "?expect";
+        }
+
+        void
+        define_xs::on_expr(bp<Expression> expr,
+                           parserstatemachine * p_psm)
+        {
+            scope log(XO_DEBUG(p_psm->debug_flag()));
+
+            log && log(xtag("defxs_type", defxs_type_));
+
+            if (this->defxs_type_ == defexprstatetype::def_5) {
+                /* have all the ingredients to create an expression
+                 * representing a definition
+                 *
+                 * 1. if ir_type is a symbol,  interpret as variable name.
+                 *    Need to be able to locate variable by type
+                 * 2. if ir_type is an expression,  adopt as rhs
+                 */
+                rp<Expression> rhs_value = expr.promote();
+
+                if (this->cvt_expr_) {
+                    this->cvt_expr_->assign_arg(rhs_value);
+                } else {
+                    /* note: establishes .def_expr_ valuetype */
+                    this->def_expr_->assign_rhs(rhs_value);
+                }
+
+                rp<Expression> def_expr = this->def_expr_;
+
+                this->defxs_type_ = defexprstatetype::def_6;
+                return;
+            }
+
+            constexpr const char * c_self_name = "define_xs::on_expr";
+            const char * exp = get_expect_str();
+
+            this->illegal_input_on_expr(c_self_name, expr, exp, p_psm);
+        }
+
+        void
+        define_xs::on_expr_with_semicolon(bp<Expression> expr,
+                                          parserstatemachine * p_psm)
+        {
+            scope log(XO_DEBUG(p_psm->debug_flag()));
+
+            log && log(xtag("defxs_type", defxs_type_));
+
+            this->on_expr(expr, p_psm);
+            /* semicolon is allowed to terminate def expr */
+            this->on_semicolon_token(token_type::semicolon(), p_psm);
+        }
+
+        void
+        define_xs::on_symbol(const std::string & symbol_name,
+                             parserstatemachine * p_psm)
+        {
+            scope log(XO_DEBUG(p_psm->debug_flag()));
+
+            log && log(xtag("defxs_type", defxs_type_), xtag("env_stack_size", p_psm->env_stack_size()));
+
+            if (this->defxs_type_ == defexprstatetype::def_1) {
+                this->defxs_type_ = defexprstatetype::def_2;
+                this->def_expr_->assign_lhs_name(symbol_name);
+
+                // if this is a genuine top-level define (i.e. nesting level = 0),
+                // then we need to upsert so we can refer to rhs later.
+                //
+                // In other contexts (e.g. body-of-lambda) will be rewriting
+                //    {
+                //       def y = foo(x,x);
+                //       bar(y,y);
+                //    }
+                // into something like
+                //    {
+                //       (lambda (y123) bar(y123,y123))(foo(x,x));
+                //    }
+                //
+                // This works in the body of lambda, because we don't evaluate anything
+                // until lambda definition is complete.
+                //
+                // For interactive top-level defs we want to evaluate as we go,
+                // so need incremental bindings.
+
+                if (p_psm->env_stack_size() == 1) {
+                    /* remember variable binding in lexical context,
+                     * so we can refer to it later
+                     */
+                    p_psm->upsert_var(this->def_expr_->lhs_variable());
+                }
+
+                return;
+            }
+
+            constexpr const char * c_self_name = "define_xs::on_symbol";
+            const char * exp = this->get_expect_str();
+
+            this->illegal_input_on_symbol(c_self_name, symbol_name, exp, p_psm);
+        }
+
+        void
+        define_xs::on_typedescr(TypeDescr td,
+                                parserstatemachine * p_psm)
+        {
+            scope log(XO_DEBUG(p_psm->debug_flag()));
+
+            log && log("defxs_type", defxs_type_);
+
+            if (this->defxs_type_ == defexprstatetype::def_3) {
+                this->defxs_type_ = defexprstatetype::def_4;
+                this->cvt_expr_ = ConvertExprAccess::make(td /*dest_type*/,
+                                                          nullptr /*source_expr*/);
+                /* note: establishes .def_expr_ valuetype */
+                this->def_expr_->assign_rhs(this->cvt_expr_);
+                return;
+            }
+
+            constexpr const char * c_self_name = "define_xs::on_symbol";
+            const char * exp = this->get_expect_str();
+
+            this->illegal_input_on_type(c_self_name, td, exp, p_psm);
+        }
+
+        void
+        define_xs::on_def_token(const token_type & tk,
+                                parserstatemachine * p_psm)
+        {
+            constexpr bool c_debug_flag = true;
+            scope log(XO_DEBUG(c_debug_flag));
+
+            log && log("defxs_type", defxs_type_);
+
+            if (this->defxs_type_ == defexprstatetype::def_0) {
+                this->defxs_type_ = defexprstatetype::def_1;
+
+                expect_symbol_xs::start(p_psm);
+                return;
+            }
+
+            constexpr const char * c_self_name = "define_xs::on_def_token";
+            const char * exp = this->get_expect_str();
+
+            this->illegal_input_on_token(c_self_name, tk, exp, p_psm);
+        }
+
+        void
+        define_xs::on_colon_token(const token_type & tk,
+                                  parserstatemachine * p_psm)
+        {
+            constexpr bool c_debug_flag = true;
+            scope log(XO_DEBUG(c_debug_flag));
+
+            log && log("defxs_type", defxs_type_);
+
+            if (this->defxs_type_ == defexprstatetype::def_2) {
+                this->defxs_type_ = defexprstatetype::def_3;
+
+                expect_type_xs::start(p_psm);
+                return;
+            }
+
+            constexpr const char * c_self_name = "define_xs::on_symbol";
+            const char * exp = this->get_expect_str();
+
+            this->illegal_input_on_token(c_self_name, tk, exp, p_psm);
+        }
+
+        void
+        define_xs::on_semicolon_token(const token_type & tk,
+                                      parserstatemachine * p_psm)
+        {
+            /* def expr consumes semicolon */
+
+            scope log(XO_DEBUG(p_psm->debug_flag()));
+
+            log && log("defxs_type", defxs_type_);
+
+            if (this->defxs_type_ == defexprstatetype::def_6) {
+                rp<DefineExprAccess> def_expr = this->def_expr_;
+
+                std::unique_ptr<exprstate> self = p_psm->pop_exprstate();
+
+                p_psm->top_exprstate().on_expr(def_expr, p_psm);
+                return;
+            }
+
+            constexpr const char * c_self_name = "define_xs::on_symbol";
+            const char * exp = this->get_expect_str();
+
+            this->illegal_input_on_token(c_self_name, tk, exp, p_psm);
+        }
+
+        void
+        define_xs::on_singleassign_token(const token_type & tk,
+                                         parserstatemachine * p_psm)
+        {
+            constexpr bool c_debug_flag = true;
+            scope log(XO_DEBUG(c_debug_flag));
+
+            log && log("defxs_type", defxs_type_);
+
+            if ((this->defxs_type_ == defexprstatetype::def_2)
+                || (this->defxs_type_ == defexprstatetype::def_4))
+            {
+                this->defxs_type_ = defexprstatetype::def_5;
+                expect_expr_xs::start(p_psm);
+                return;
+            }
+
+            constexpr const char * c_self_name = "define_xs::on_singleassign_token";
+            const char * exp = get_expect_str();
+
+            this->illegal_input_on_token(c_self_name, tk, exp, p_psm);
+        }
+
+        void
+        define_xs::on_rightparen_token(const token_type & tk,
+                                       parserstatemachine * p_psm)
+        {
+            constexpr bool c_debug_flag = true;
+            scope log(XO_DEBUG(c_debug_flag));
+
+            constexpr const char * c_self_name = "define_xs::on_rightparen";
+            const char * exp = get_expect_str();
+
+            this->illegal_input_on_token(c_self_name, tk, exp, p_psm);
+        }
+
+        void
+        define_xs::on_i64_token(const token_type & tk,
+                                parserstatemachine * p_psm)
+        {
+            constexpr bool c_debug_flag = true;
+            scope log(XO_DEBUG(c_debug_flag));
+
+            constexpr const char * c_self_name = "define_xs::on_i64";
+            const char * exp = get_expect_str();
+
+            this->illegal_input_on_token(c_self_name, tk, exp, p_psm);
+        }
+
+        void
+        define_xs::on_f64_token(const token_type & tk,
+                                parserstatemachine * p_psm)
+        {
+            constexpr bool c_debug_flag = true;
+            scope log(XO_DEBUG(c_debug_flag));
+
+            constexpr const char * c_self_name = "define_xs::on_f64";
+            const char * exp = get_expect_str();
+
+            this->illegal_input_on_token(c_self_name, tk, exp, p_psm);
+        }
+
+        void
+        define_xs::print(std::ostream & os) const {
+            os << "<define_xs"
+               << xtag("defxs_type", defxs_type_);
+            os << ">";
+        }
+
+        bool
+        define_xs::pretty_print(const xo::print::ppindentinfo & ppii) const
+        {
+            return ppii.pps()->pretty_struct(ppii, "define_xs",
+                                             refrtag("defxs_type", defxs_type_));
+        }
+
+    } /*namespace scm*/
+} /*namespace xo*/
+
+/* end define_xs.cpp */
diff --git a/xo-reader/src/reader/envframe.cpp b/xo-reader/src/reader/envframe.cpp
new file mode 100644
index 00000000..985bc1c6
--- /dev/null
+++ b/xo-reader/src/reader/envframe.cpp
@@ -0,0 +1,41 @@
+/* file envframe.cpp
+ *
+ * author: Roland Conybeare
+ */
+
+#include "envframe.hpp"
+#include "xo/indentlog/print/vector.hpp"
+
+namespace xo {
+    using xo::scm::Variable;
+
+    namespace scm {
+#ifdef OBSOLETE
+        envframe::envframe(const std::vector<rp<Variable>> & argl,
+                           const rp<Environment>& parent_env)
+        {
+            this->env_ = LocalEnv::make(argl, parent_env);
+        }
+
+        bp<Variable>
+        envframe::lookup(const std::string & target) const {
+            return env_->lookup_local(target);
+        }
+
+        void
+        envframe::upsert(bp<Variable> target) {
+            env_->upsert_local(target);
+        }
+
+        void
+        envframe::print(std::ostream & os) const {
+            os << "<envframe"
+               << xtag("argv", env_->argv())
+               << ">";
+        }
+#endif
+    } /*namespace scm */
+} /*namespace xo*/
+
+
+/* end envframe.cpp */
diff --git a/xo-reader/src/reader/envframestack.cpp b/xo-reader/src/reader/envframestack.cpp
new file mode 100644
index 00000000..19e15d27
--- /dev/null
+++ b/xo-reader/src/reader/envframestack.cpp
@@ -0,0 +1,139 @@
+/* file envframestack.cpp
+ *
+ * author: Roland Conybeare
+ */
+
+#include "envframestack.hpp"
+#include "pretty_envframestack.hpp"
+#include "pretty_localenv.hpp"
+
+namespace xo {
+    using xo::scm::LocalSymtab;
+    using xo::scm::Variable;
+
+    namespace scm {
+        bp<SymbolTable>
+        envframestack::top_envframe() const {
+            std::size_t z = stack_.size();
+
+            if (z == 0) {
+                throw std::runtime_error
+                    ("parser::top_exprstate: unexpected empty stack");
+            }
+
+            return stack_[z-1].get();
+        }
+
+        void
+        envframestack::push_envframe(const rp<SymbolTable> & frame)
+        {
+            constexpr bool c_debug_flag = true;
+            scope log(XO_DEBUG(c_debug_flag),
+                      xtag("frame", frame));
+
+            std::size_t z = stack_.size();
+
+            stack_.resize(z+1);
+
+            stack_[z] = frame;
+        }
+
+        rp<SymbolTable>
+        envframestack::pop_envframe() {
+            constexpr bool c_debug_flag = true;
+            scope log(XO_DEBUG(c_debug_flag));
+
+            std::size_t z = stack_.size();
+
+            if (z > 0) {
+                //std::unique_ptr<exprstate> top = std::move(stack_[z-1]);
+
+                rp<SymbolTable> retval = stack_.at(z-1);
+
+                stack_.resize(z-1);
+
+                return retval;
+            } else {
+                return nullptr;
+            }
+        }
+
+        bp<Expression>
+        envframestack::lookup(const std::string & x) const {
+            for (std::size_t i = 0, z = this->size(); i < z; ++i) {
+                const auto & frame = (*this)[i];
+
+                auto retval = frame->lookup_local(x);
+
+                if (retval)
+                    return retval;
+            }
+
+            return bp<Variable>::from_native(nullptr);
+        }
+
+        void
+        envframestack::upsert(bp<Variable> x) {
+            /* upsert should always happen in the innermost lexical context.
+             * We are providing new variable binding (perhaps shadowing an existing binding)
+             */
+            this->top_envframe()->upsert_local(x);
+        }
+
+        void
+        envframestack::print(std::ostream & os) const {
+            os << "<envframestack"
+               << xtag("size", stack_.size())
+               << std::endl;
+
+            for (std::size_t i = 0, z = stack_.size(); i < z; ++i) {
+                os << "  [" << z-i-1 << "] "
+                   << stack_[i]
+                   << std::endl;
+            }
+
+            os << ">" << std::endl;
+        }
+
+        bool
+        envframestack::pretty_print(const ppindentinfo & ppii) const
+        {
+            ppstate * pps = ppii.pps();
+
+            if (ppii.upto()) {
+                if (stack_.size() > 1)
+                    return false;
+
+                if (!pps->print_upto("<envframestack"))
+                    return false;
+
+                if (!pps->print_upto_tag("size", stack_.size()))
+                    return false;
+
+                if ((stack_.size() > 0)
+                    && !pps->print_upto_tag("[0]", stack_[0]))
+                {
+                    return false;
+                }
+
+                pps->write(">");
+
+                return true;
+            } else {
+                pps->write("<envframestack");
+
+                pps->newline_pretty_tag(ppii.ci1(), "size", stack_.size());
+
+                for (std::size_t i = 0, z = stack_.size(); i < z; ++i) {
+                    std::string i_str = tostr("[", z-i-1, "]");
+                    pps->newline_pretty_tag(ppii.ci1(), i_str, stack_[i]);
+                }
+                pps->write(">");
+
+                return false;
+            }
+        }
+    } /*namespace scm*/
+} /*namespace xo*/
+
+/* end envframestack.cpp */
diff --git a/xo-reader/src/reader/expect_expr_xs.cpp b/xo-reader/src/reader/expect_expr_xs.cpp
new file mode 100644
index 00000000..10caafeb
--- /dev/null
+++ b/xo-reader/src/reader/expect_expr_xs.cpp
@@ -0,0 +1,294 @@
+/* file expect_expr_xs.cpp
+ *
+ * author: Roland Conybeare
+ */
+
+#include "expect_expr_xs.hpp"
+#include "parserstatemachine.hpp"
+#include "exprstatestack.hpp"
+#include "define_xs.hpp"
+#include "lambda_xs.hpp"
+#include "if_else_xs.hpp"
+#include "paren_xs.hpp"
+#include "sequence_xs.hpp"
+#include "progress_xs.hpp"
+#include "xo/expression/Lambda.hpp"
+#include "xo/expression/Constant.hpp"
+#include "xo/expression/pretty_expression.hpp"
+
+namespace xo {
+    using xo::scm::Constant;
+
+    namespace scm {
+
+        std::unique_ptr<expect_expr_xs>
+        expect_expr_xs::make(bool allow_defs,
+                             bool cxl_on_rightbrace)
+        {
+            return std::make_unique<expect_expr_xs>(expect_expr_xs(allow_defs,
+                                                                   cxl_on_rightbrace));
+
+        }
+
+        void
+        expect_expr_xs::start(bool allow_defs,
+                              bool cxl_on_rightbrace,
+                              parserstatemachine * p_psm)
+        {
+            p_psm->push_exprstate(expect_expr_xs::make(allow_defs,
+                                                       cxl_on_rightbrace));
+        }
+
+        void
+        expect_expr_xs::start(parserstatemachine * p_psm) {
+            start(false /*!allow_defs*/,
+                  false /*!cxl_on_rightbrace*/,
+                  p_psm);
+        }
+
+        expect_expr_xs::expect_expr_xs(bool allow_defs,
+                                       bool cxl_on_rightbrace)
+            : exprstate(exprstatetype::expect_rhs_expression),
+              allow_defs_{allow_defs},
+              cxl_on_rightbrace_{cxl_on_rightbrace}
+        {}
+
+        const char *
+        expect_expr_xs::get_expect_str() const
+        {
+            if (allow_defs_) {
+                return "def|lambda|lparen|lbrace|literal|var";
+            } else {
+                return "lambda|lparen|lbrace|literal|var";
+            }
+        }
+
+        void
+        expect_expr_xs::on_def_token(const token_type & tk,
+                                     parserstatemachine * p_psm)
+        {
+            scope log(XO_DEBUG(p_psm->debug_flag()));
+
+            if (allow_defs_) {
+                define_xs::start(p_psm);
+            } else {
+                exprstate::on_def_token(tk, p_psm);
+            }
+        }
+
+        void
+        expect_expr_xs::on_lambda_token(const token_type & /*tk*/,
+                                        parserstatemachine * p_psm)
+        {
+            scope log(XO_DEBUG(p_psm->debug_flag()));
+
+            //constexpr const char * self_name = "exprstate::on_leftparen";
+
+            lambda_xs::start(p_psm);
+        }
+
+        void
+        expect_expr_xs::on_if_token(const token_type & /*tk*/,
+                                    parserstatemachine * p_psm)
+        {
+            if_else_xs::start(p_psm);
+        }
+
+        void
+        expect_expr_xs::on_leftparen_token(const token_type & /*tk*/,
+                                           parserstatemachine * p_psm)
+        {
+            scope log(XO_DEBUG(p_psm->debug_flag()));
+
+            //constexpr const char * self_name = "exprstate::on_leftparen";
+
+            /* push lparen_0 to remember to look for subsequent rightparen. */
+            paren_xs::start(p_psm);
+        }
+
+        void
+        expect_expr_xs::on_leftbrace_token(const token_type & /*tk*/,
+                                           parserstatemachine * p_psm)
+        {
+            scope log(XO_DEBUG(p_psm->debug_flag()));
+
+            /* push lparen_0 to remember to look for subsequent rightparen. */
+            sequence_xs::start(p_psm);
+        }
+
+        void
+        expect_expr_xs::on_rightbrace_token(const token_type & tk,
+                                            parserstatemachine * p_psm)
+        {
+            constexpr bool c_debug_flag = true;
+            scope log(XO_DEBUG(c_debug_flag));
+
+            if (cxl_on_rightbrace_) {
+                auto self = p_psm->pop_exprstate();
+
+                /* do not call .on_expr(), since '}' cancelled */
+
+                p_psm->on_rightbrace_token(tk);
+            } else {
+                exprstate::on_rightbrace_token(tk, p_psm);
+            }
+        }
+
+        void
+        expect_expr_xs::on_symbol_token(const token_type & tk,
+                                        parserstatemachine * p_psm)
+        {
+            scope log(XO_DEBUG(p_psm->debug_flag()));
+
+            log && log(xtag("tk", tk));
+
+            constexpr const char * c_self_name = "expect_expr_xs::on_symbol_token";
+
+            /* various possibilities when looking for rhs expression:
+             *
+             *   x := y       // (1)
+             *   x := f(a)    // (2)
+             *   x := f(a,b)  // (3)
+             *
+             * need lookahead token following symbol to distinguish
+             * between (1) (symbol completes rhs expression)
+             * and {(2), (3)} (symbol is function call)
+             */
+
+            bp<Variable> var = p_psm->lookup_var(tk.text());
+
+            if (!var) {
+                this->unknown_variable_error(c_self_name, tk, p_psm);
+                return;
+            }
+
+            /* e.g.
+             *   def pi = 3.14159265;
+             *   def mypi = pi;
+             *              ^
+             *   def pi2 = pi * 2;
+             *             ^
+             *   def y = foo(pi2);
+             *           ^
+             */
+            progress_xs::start(var.promote(), p_psm);
+
+ #ifdef NOT_YET
+            p_stack->push_exprstate(exprstate(exprstatetype::expr_progress,
+                                              Variable::make(name, type)));
+#endif
+
+#ifdef LATER
+            p_psm->pop_exprstate();
+            p_psm->top_exprstate().on_symbol(tk.text(),
+                                               p_stack, p_emit_expr);
+#endif
+            return;
+        }
+
+        void
+        expect_expr_xs::on_bool_token(const token_type & tk,
+                                      parserstatemachine * p_psm)
+        {
+            scope log(XO_DEBUG(p_psm->debug_flag()));
+
+            progress_xs::start
+                (Constant<bool>::make(tk.bool_value()),
+                 p_psm);
+        }
+
+        void
+        expect_expr_xs::on_i64_token(const token_type & tk,
+                                     parserstatemachine * p_psm)
+        {
+            scope log(XO_DEBUG(p_psm->debug_flag()),
+                      xtag("tk", tk),
+                      xtag("do", "push progress xs w/ tk value"));
+
+            progress_xs::start
+                (Constant<int64_t>::make(tk.i64_value()),
+                 p_psm);
+        }
+
+        void
+        expect_expr_xs::on_f64_token(const token_type & tk,
+                                     parserstatemachine * p_psm)
+        {
+            scope log(XO_DEBUG(p_psm->debug_flag()));
+
+            //constexpr const char * self_name = "exprstate::on_f64_token";
+
+            /* e.g.
+             *   def pi = 3.14159265;
+             *            \---tk---/
+             */
+            progress_xs::start
+                (Constant<double>::make(tk.f64_value()),
+                 p_psm);
+        }
+
+        void
+        expect_expr_xs::on_string_token(const token_type & tk,
+                                        parserstatemachine * p_psm)
+        {
+            scope log(XO_DEBUG(p_psm->debug_flag()));
+
+            /* e.g.
+             *   def msg = "hello, world";
+             *              \----tk----/
+             */
+            progress_xs::start
+                (Constant<std::string>::make(tk.text()),
+                 p_psm);
+        }
+
+        void
+        expect_expr_xs::on_expr(bp<Expression> expr,
+                                parserstatemachine * p_psm)
+        {
+            scope log(XO_DEBUG(p_psm->debug_flag()));
+
+            log && log(xtag("exstype", this->exs_type_),
+                       xtag("expr", expr.promote()));
+            log && log("pop expect_expr_xs, forward to parent");
+
+            std::unique_ptr<exprstate> self = p_psm->pop_exprstate();
+
+            p_psm->on_expr(expr);
+        } /*on_expr*/
+
+        void
+        expect_expr_xs::on_expr_with_semicolon(bp<Expression> expr,
+                                               parserstatemachine * p_psm)
+        {
+            scope log(XO_DEBUG(p_psm->debug_flag()));
+
+            log && log(xtag("exstype", this->exs_type_),
+                       xtag("expr", expr.promote()));
+            log && log("pop expect_expr_xs, forward to parent");
+
+            std::unique_ptr<exprstate> self = p_psm->pop_exprstate();
+
+            p_psm->on_expr_with_semicolon(expr);
+        } /*on_expr_with_semicolon*/
+
+        void
+        expect_expr_xs::print(std::ostream & os) const {
+            os << "<expect_expr_xs"
+               << xtag("allow_defs", allow_defs_)
+               << xtag("cxl_on_rightbrace", cxl_on_rightbrace_)
+               << ">";
+        }
+
+        bool
+        expect_expr_xs::pretty_print(const xo::print::ppindentinfo & ppii) const
+        {
+            return ppii.pps()->pretty_struct(ppii, "expect_expr_xs",
+                                             refrtag("allow_defs", allow_defs_),
+                                             refrtag("cxl_on_rightbrace", cxl_on_rightbrace_));
+        }
+
+    } /*namespace scm*/
+} /*namespace xo*/
+
+/* end expect_expr_xs.cpp */
diff --git a/xo-reader/src/reader/expect_formal_arglist_xs.cpp b/xo-reader/src/reader/expect_formal_arglist_xs.cpp
new file mode 100644
index 00000000..f05680d9
--- /dev/null
+++ b/xo-reader/src/reader/expect_formal_arglist_xs.cpp
@@ -0,0 +1,131 @@
+/* file expect_formal_arglist_xs.cpp
+ *
+ * author: Roland Conybeare
+ */
+
+#include "expect_formal_arglist_xs.hpp"
+#include "parserstatemachine.hpp"
+#include "exprstatestack.hpp"
+#include "expect_formal_xs.hpp"
+#include "expect_symbol_xs.hpp"
+#include "xo/expression/Variable.hpp"
+#include "xo/indentlog/print/vector.hpp"
+
+namespace xo {
+    namespace scm {
+        const char *
+        formalarglstatetype_descr(formalarglstatetype x) {
+            switch (x) {
+            case formalarglstatetype::invalid:
+                return "invalid";
+            case formalarglstatetype::argl_0:
+                return "argl_0";
+            case formalarglstatetype::argl_1a:
+                return "argl_1a";
+            case formalarglstatetype::argl_1b:
+                return "argl_1b";
+            case formalarglstatetype::n_formalarglstatetype:
+                break;
+            }
+
+            return "?formalarglstatetype";
+        }
+
+        std::unique_ptr<expect_formal_arglist_xs>
+        expect_formal_arglist_xs::make() {
+            return std::make_unique<expect_formal_arglist_xs>
+                (expect_formal_arglist_xs());
+        }
+
+        void
+        expect_formal_arglist_xs::start(parserstatemachine * p_psm)
+        {
+            p_psm->push_exprstate(expect_formal_arglist_xs::make());
+        }
+
+        const char *
+        expect_formal_arglist_xs::get_expect_str() const {
+            switch (farglxs_type_) {
+            case formalarglstatetype::invalid:
+            case formalarglstatetype::n_formalarglstatetype:
+                assert(false); // impossible
+                break;
+            case formalarglstatetype::argl_0:
+                return "leftparen";
+            case formalarglstatetype::argl_1a:
+                return "formal-name";
+            case formalarglstatetype::argl_1b:
+                return "comma|rightparen";
+            }
+
+            return "?expect";
+        }
+
+        expect_formal_arglist_xs::expect_formal_arglist_xs()
+            : exprstate(exprstatetype::expect_formal_arglist),
+              farglxs_type_{formalarglstatetype::argl_0}
+        {}
+
+        void
+        expect_formal_arglist_xs::on_leftparen_token(const token_type & tk,
+                                                     parserstatemachine * p_psm)
+        {
+            if (farglxs_type_ == formalarglstatetype::argl_0) {
+                this->farglxs_type_ = formalarglstatetype::argl_1a;
+                /* TODO: refactor to have setup method on each exprstate */
+                expect_formal_xs::start(p_psm);
+            } else {
+                exprstate::on_leftparen_token(tk, p_psm);
+            }
+        }
+
+        void
+        expect_formal_arglist_xs::on_formal(const rp<Variable> & formal,
+                                            parserstatemachine * p_psm)
+        {
+            if (farglxs_type_ == formalarglstatetype::argl_1a) {
+                this->farglxs_type_ = formalarglstatetype::argl_1b;
+                this->argl_.push_back(formal);
+            } else {
+                exprstate::on_formal(formal, p_psm);
+            }
+        }
+
+        void
+        expect_formal_arglist_xs::on_comma_token(const token_type & tk,
+                                                 parserstatemachine * p_psm)
+        {
+            if (farglxs_type_ == formalarglstatetype::argl_1b) {
+                this->farglxs_type_ = formalarglstatetype::argl_1a;
+                expect_formal_xs::start(p_psm);
+            } else {
+                exprstate::on_comma_token(tk, p_psm);
+            }
+        }
+
+        void
+        expect_formal_arglist_xs::on_rightparen_token(const token_type & tk,
+                                                      parserstatemachine * p_psm)
+        {
+            if (farglxs_type_ == formalarglstatetype::argl_1b) {
+                std::unique_ptr<exprstate> self = p_psm->pop_exprstate();
+
+                p_psm->top_exprstate().on_formal_arglist(this->argl_, p_psm);
+            } else {
+                exprstate::on_rightparen_token(tk, p_psm);
+            }
+        }
+
+        void
+        expect_formal_arglist_xs::print(std::ostream & os) const {
+            os << "<expect_formal_arglist_xs"
+               << xtag("type", farglxs_type_);
+            os << xtag("farglxs_type", farglxs_type_);
+            os << xtag("argl", argl_);
+            os << ">";
+        }
+    } /*namespace scm*/
+} /*namespace xo*/
+
+
+/* end expect_formal_arglist_xs.cpp */
diff --git a/xo-reader/src/reader/expect_formal_xs.cpp b/xo-reader/src/reader/expect_formal_xs.cpp
new file mode 100644
index 00000000..3bb72dad
--- /dev/null
+++ b/xo-reader/src/reader/expect_formal_xs.cpp
@@ -0,0 +1,109 @@
+/* file expect_formal_xs.cpp
+ *
+ * author: Roland Conybeare
+ */
+
+#include "expect_formal_xs.hpp"
+#include "expect_symbol_xs.hpp"
+#include "expect_type_xs.hpp"
+#include "parserstatemachine.hpp"
+#include "exprstatestack.hpp"
+#include "xo/expression/Variable.hpp"
+
+namespace xo {
+    using xo::scm::Variable;
+    using xo::reflect::TypeDescr;
+
+    namespace scm{
+        const char *
+        formalstatetype_descr(formalstatetype x) {
+            switch (x) {
+            case formalstatetype::invalid:
+            case formalstatetype::n_formalstatetype:
+                return "?formalstatetype";
+            case formalstatetype::formal_0:
+                return "formal_0";
+            case formalstatetype::formal_1:
+                return "formal_1";
+            case formalstatetype::formal_2:
+                return "formal_2";
+            }
+
+            return "???formalstatetype";
+        }
+
+        std::unique_ptr<expect_formal_xs>
+        expect_formal_xs::make() {
+            return std::make_unique<expect_formal_xs>(expect_formal_xs());
+        }
+
+        void
+        expect_formal_xs::start(parserstatemachine * p_psm) {
+            p_psm->push_exprstate(expect_formal_xs::make());
+
+            expect_symbol_xs::start(p_psm);
+        }
+
+        expect_formal_xs::expect_formal_xs()
+            : exprstate(exprstatetype::expect_formal)
+        {}
+
+        void
+        expect_formal_xs::on_symbol(const std::string & symbol_name,
+                                    parserstatemachine * p_psm)
+        {
+            if (this->formalxs_type_ == formalstatetype::formal_0) {
+                this->formalxs_type_ = formalstatetype::formal_1;
+                this->result_.assign_name(symbol_name);
+            } else {
+                exprstate::on_symbol(symbol_name, p_psm);
+            }
+        }
+
+        void
+        expect_formal_xs::on_colon_token(const token_type & tk,
+                                         parserstatemachine * p_psm)
+        {
+            if (this->formalxs_type_ == formalstatetype::formal_1) {
+                this->formalxs_type_ = formalstatetype::formal_2;
+                expect_type_xs::start(p_psm);
+                /* control reenters via expect_formal_xs::on_typedescr() */
+            } else {
+                exprstate::on_colon_token(tk,
+                                          p_psm);
+            }
+        }
+
+        void
+        expect_formal_xs::on_typedescr(TypeDescr td,
+                                       parserstatemachine * p_psm)
+        {
+            if (this->formalxs_type_ == formalstatetype::formal_2) {
+                this->result_.assign_td(td);
+
+                std::unique_ptr<exprstate> self = p_psm->pop_exprstate();
+
+                rp<Variable> var = Variable::make(result_.name(),
+                                                  result_.td());
+
+                p_psm->top_exprstate().on_formal(var, p_psm);
+            } else {
+                exprstate::on_typedescr(td, p_psm);
+            }
+        }
+
+        void
+        expect_formal_xs::print(std::ostream & os) const {
+            os << "<expect_formal_xs"
+               << xtag("type", formalxs_type_);
+            if (!result_.name().empty())
+                os << xtag("result.name", result_.name());
+            if (result_.td())
+                os << xtag("result.td", result_.td());
+            os << ">";
+        }
+    } /*namespace scm*/
+} /*namespace xo*/
+
+
+/* end expect_formal_xs.cpp */
diff --git a/xo-reader/src/reader/expect_symbol_xs.cpp b/xo-reader/src/reader/expect_symbol_xs.cpp
new file mode 100644
index 00000000..1baa4178
--- /dev/null
+++ b/xo-reader/src/reader/expect_symbol_xs.cpp
@@ -0,0 +1,49 @@
+/* file expect_symbol_xs.cpp
+ *
+ * author: Roland Conybeare
+ */
+
+#include "expect_symbol_xs.hpp"
+#include "parserstatemachine.hpp"
+#include "exprstatestack.hpp"
+
+namespace xo {
+    namespace scm {
+        std::unique_ptr<expect_symbol_xs>
+        expect_symbol_xs::make() {
+            return std::make_unique<expect_symbol_xs>(expect_symbol_xs());
+        }
+
+        void
+        expect_symbol_xs::start(parserstatemachine * p_psm)
+        {
+            p_psm->push_exprstate(expect_symbol_xs::make());
+        }
+
+        expect_symbol_xs::expect_symbol_xs()
+            : exprstate(exprstatetype::expect_symbol)
+        {}
+
+        void
+        expect_symbol_xs::on_symbol_token(const token_type & tk,
+                                          parserstatemachine * p_psm)
+        {
+            constexpr bool c_debug_flag = true;
+            scope log(XO_DEBUG(c_debug_flag));
+
+            log && log(xtag("tk", tk));
+
+            assert(&p_psm->top_exprstate() == this);
+
+            /* have to do pop first, before sending symbol to
+             * the o.g. symbol-requester
+             */
+            std::unique_ptr<exprstate> self{p_psm->pop_exprstate()};
+
+            p_psm->on_symbol(tk.text());
+        }
+    } /*namespace scm*/
+} /*namespace xo*/
+
+
+/* end expect_symbol_xs.cpp */
diff --git a/xo-reader/src/reader/expect_type_xs.cpp b/xo-reader/src/reader/expect_type_xs.cpp
new file mode 100644
index 00000000..62d797f5
--- /dev/null
+++ b/xo-reader/src/reader/expect_type_xs.cpp
@@ -0,0 +1,79 @@
+/* file expect_type_xs.cpp
+ *
+ * author: Roland Conybeare
+ */
+
+#include "expect_type_xs.hpp"
+#include "parserstatemachine.hpp"
+#include "exprstatestack.hpp"
+#include "xo/reflect/Reflect.hpp"
+
+namespace xo {
+    using xo::reflect::Reflect;
+
+    namespace scm {
+
+        std::unique_ptr<expect_type_xs>
+        expect_type_xs::make() {
+            return std::make_unique<expect_type_xs>(expect_type_xs());
+        }
+
+        void
+        expect_type_xs::start(parserstatemachine * p_psm) {
+            p_psm->push_exprstate(expect_type_xs::make());
+        }
+
+        expect_type_xs::expect_type_xs()
+            : exprstate(exprstatetype::expect_type)
+        {}
+
+        const char *
+        expect_type_xs::get_expect_str() const
+        {
+            return "typename";
+        }
+
+        void
+        expect_type_xs::on_symbol_token(const token_type & tk,
+                                        parserstatemachine * p_psm)
+        {
+            const char * c_self_name = "expect_type_xs::on_symbol_token";
+
+            TypeDescr td = nullptr;
+
+            /* TODO: replace with typetable lookup */
+
+            if (tk.text() == "bool")
+                td = Reflect::require<bool>();
+            else if (tk.text() == "str")
+                td = Reflect::require<std::string>();
+            else if (tk.text() == "f64")
+                td = Reflect::require<double>();
+            else if(tk.text() == "f32")
+                td = Reflect::require<float>();
+            else if(tk.text() == "i16")
+                td = Reflect::require<std::int16_t>();
+            else if(tk.text() == "i32")
+                td = Reflect::require<std::int32_t>();
+            else if(tk.text() == "i64")
+                td = Reflect::require<std::int64_t>();
+
+            if (!td) {
+                const char * exp = get_expect_str();
+
+                std::string errmsg = tostr("expect_type_xs: unexpected token for parsing state",
+                                           xtag("expecting", exp),
+                                           xtag("token", tk.tk_type()),
+                                           xtag("text", tk.text()),
+                                           xtag("state", this->exs_type()));
+
+                p_psm->on_error(c_self_name, std::move(errmsg));
+            }
+
+            std::unique_ptr<exprstate> self = p_psm->pop_exprstate();
+            p_psm->top_exprstate().on_typedescr(td, p_psm);
+        }
+    } /*namespace scm*/
+} /*namespace xo*/
+
+/* end expect_type_xs.cpp */
diff --git a/xo-reader/src/reader/exprseq_xs.cpp b/xo-reader/src/reader/exprseq_xs.cpp
new file mode 100644
index 00000000..48307d77
--- /dev/null
+++ b/xo-reader/src/reader/exprseq_xs.cpp
@@ -0,0 +1,276 @@
+/* @file exprseq_xs.cpp */
+
+#include "exprseq_xs.hpp"
+#include "parserstatemachine.hpp"
+#include "exprstatestack.hpp"
+#include "exprseq_xs.hpp"
+//#include "expect_expr_xs.hpp"
+#include "progress_xs.hpp"
+#include "define_xs.hpp"
+#include "if_else_xs.hpp"
+#include "expect_symbol_xs.hpp"
+#include "xo/expression/Constant.hpp"
+
+namespace xo {
+    namespace scm {
+        std::unique_ptr<exprseq_xs>
+        exprseq_xs::make(exprseqtype seqtype)
+        {
+            return std::make_unique<exprseq_xs>(exprseq_xs(seqtype));
+        }
+
+        void
+        exprseq_xs::start(exprseqtype seqtype, parserstatemachine * p_psm)
+        {
+            p_psm->push_exprstate(exprseq_xs::make(seqtype));
+        }
+
+        exprseq_xs::exprseq_xs(exprseqtype x)
+            : exprstate(exprstatetype::expect_toplevel_expression_sequence),
+              xseqtype_{x}
+        {
+        }
+
+        const char *
+        exprseq_xs::get_expect_str() const
+        {
+            /*
+             *   def...
+             *  ^
+             *  exprseq_xs
+             */
+            switch (this->xseqtype_) {
+            case exprseqtype::toplevel_interactive:
+                return "def|expression";
+            case exprseqtype::toplevel_batch:
+                return "def";
+            }
+
+            return "?expect";
+        }
+
+        void
+        exprseq_xs::on_def_token(const token_type & /*tk*/,
+                                 parserstatemachine * p_psm)
+        {
+            constexpr bool c_debug_flag = true;
+            scope log(XO_DEBUG(c_debug_flag));
+
+            define_xs::start(p_psm);
+
+            /* keyword 'def' introduces a definition:
+             *   def pi : f64 = 3.14159265
+             *   def sq(x : f64) -> f64 { (x * x) }
+             */
+        }
+
+        void
+        exprseq_xs::on_if_token(const token_type & tk,
+                                parserstatemachine * p_psm)
+        {
+            if (xseqtype_ == exprseqtype::toplevel_interactive)
+            {
+                /* in interactive session, allow top-level if-expressions.
+                 * Could be:
+                 *   if sometest() then do_something() else do_otherthing();
+                 */
+                if_else_xs::start(p_psm);
+            } else {
+                constexpr const char * c_self_name = "exprseq_xs::on_if_token";
+                const char * exp = get_expect_str();
+
+                this->illegal_input_on_token(c_self_name, tk, exp, p_psm);
+            }
+        }
+
+        void
+        exprseq_xs::on_symbol_token(const token_type & tk,
+                                    parserstatemachine * p_psm)
+        {
+            constexpr const char * c_self_name = "exprseq_xs::on_symbol_token";
+
+            if (xseqtype_ == exprseqtype::toplevel_interactive)
+            {
+                /* In interactive session, allow top-level variable reference.
+                 * This could be:
+                 *   a;      // variable references
+                 *   a = 1;  // single assignment
+                 *   a == 1; // rhs expression
+                 *   a + b;  // rhs expression
+                 *   a(1,2); // apply expression
+                 * Variable must have been defined!
+                 */
+                bp<Variable> var = p_psm->lookup_var(tk.text());
+
+                if (var.get()) {
+                    progress_xs::start(var.promote(), p_psm);
+                } else {
+                    this->unknown_variable_error(c_self_name, tk, p_psm);
+                }
+            } else {
+                /* policy: don't allow variable references as toplevel expressions
+                 * unless interactive session
+                 */
+                const char * exp = get_expect_str();
+
+                this->illegal_input_on_token(c_self_name,
+                                             tk,
+                                             exp,
+                                             p_psm);
+            }
+        }
+
+        void
+        exprseq_xs::on_bool_token(const token_type & tk,
+                                  parserstatemachine * p_psm)
+        {
+            using xo::scm::Constant;
+
+            constexpr bool c_debug_flag = true;
+            scope log(XO_DEBUG(c_debug_flag));
+
+            constexpr const char * c_self_name = "exprseq_xs::on_bool_token";
+
+            if (xseqtype_ == exprseqtype::toplevel_interactive)
+            {
+                progress_xs::start(Constant<bool>::make(tk.bool_value()), p_psm);
+            } else {
+                /* policy: don't allow literals as toplevel expressions
+                 * unless interactive session
+                 */
+                const char * exp = get_expect_str();
+
+                this->illegal_input_on_token(c_self_name,
+                                             tk,
+                                             exp,
+                                             p_psm);
+            }
+        }
+
+        void
+        exprseq_xs::on_i64_token(const token_type & tk,
+                                 parserstatemachine * p_psm)
+        {
+            using xo::scm::Constant;
+
+            scope log(XO_DEBUG(p_psm->debug_flag()));
+
+            constexpr const char * c_self_name = "exprseq_xs::on_i64_token";
+
+            if (xseqtype_ == exprseqtype::toplevel_interactive)
+            {
+                progress_xs::start(Constant<int64_t>::make(tk.i64_value()), p_psm);
+            } else {
+                /* policy: don't allow literals as toplevel expressions
+                 * unless interactive session.
+                 */
+                const char * exp = get_expect_str();
+
+                this->illegal_input_on_token(c_self_name,
+                                             tk,
+                                             exp,
+                                             p_psm);
+            }
+        }
+
+        void
+        exprseq_xs::on_f64_token(const token_type & tk,
+                                 parserstatemachine * p_psm)
+        {
+            using xo::scm::Constant;
+
+            scope log(XO_DEBUG(p_psm->debug_flag()));
+
+            constexpr const char * c_self_name = "exprseq_xs::on_f64_token";
+
+            if (xseqtype_ == exprseqtype::toplevel_interactive)
+            {
+                progress_xs::start(Constant<double>::make(tk.f64_value()), p_psm);
+            } else {
+                /* policy: don't allow literals as toplevel expressions
+                 * unless interactive session.
+                 */
+                const char * exp = get_expect_str();
+
+                this->illegal_input_on_token(c_self_name,
+                                             tk,
+                                             exp,
+                                             p_psm);
+            }
+        }
+
+        void
+        exprseq_xs::on_string_token(const token_type & tk,
+                                    parserstatemachine * p_psm)
+        {
+            using xo::scm::Constant;
+
+            scope log(XO_DEBUG(p_psm->debug_flag()));
+
+            constexpr const char * c_self_name = "exprseq_xs::on_string_token";
+
+            if (xseqtype_ == exprseqtype::toplevel_interactive)
+            {
+                // remark:
+                // 1. Constant is an expression. At present (nov 2025) these are
+                //    reference-counted (+ leak in xo-interpreter).
+                // 2. Could fix leak by adding a finalization feature to GC.
+                //    Do intend to eventually support finalization,
+                //    but not to use it here.
+                // 3. Instead mean to change allocation strategy for Expression
+                //    to use GC instead.
+                // 4. As intermediate step try migrating Expression hierarchy
+                //    to support arena allocation.
+                //    See xo/alloc/ArenaAllocT.hpp + assoc'd unit test
+                //
+                progress_xs::start(Constant<std::string>::make(tk.text()), p_psm);
+            } else {
+                /* policy: don't allow literals as toplevel expressions
+                 * unless interactive session.
+                 */
+                const char * exp = get_expect_str();
+
+                this->illegal_input_on_token(c_self_name,
+                                             tk,
+                                             exp,
+                                             p_psm);
+            }
+        }
+
+        void
+        exprseq_xs::on_typedescr(TypeDescr /*td*/,
+                                 parserstatemachine * /*p_psm*/)
+        {
+            /* unreachable - typedescr should never get delivered to exprseq */
+            assert(false);
+            return;
+        }
+
+        void
+        exprseq_xs::on_expr(bp<Expression> expr,
+                            parserstatemachine * p_psm)
+        {
+            /* toplevel expression sequence accepts an
+             * arbitrary number of expressions.
+             */
+
+            p_psm->result_ = parser_result::expression(expr.promote());
+        }
+
+        void
+        exprseq_xs::on_expr_with_semicolon(bp<Expression> expr,
+                                           parserstatemachine * p_psm)
+        {
+            /* toplevel expression sequence accepts an
+             * arbitrary number of expressions.
+             *
+             * semicolons are sometimes mandatory to avoid ambiguity.
+             */
+
+            p_psm->result_ = parser_result::expression(expr.promote());
+        }
+
+    } /*namespace scm*/
+} /*namespace xo*/
+
+/* end exprseq_xs.cpp */
diff --git a/xo-reader/src/reader/exprstate.cpp b/xo-reader/src/reader/exprstate.cpp
new file mode 100644
index 00000000..5bbfcb86
--- /dev/null
+++ b/xo-reader/src/reader/exprstate.cpp
@@ -0,0 +1,675 @@
+/* @file exprstate.cpp */
+
+#include "exprstate.hpp"
+#include "exprstatestack.hpp"
+#include "parserstatemachine.hpp"
+#include "pretty_parserstatemachine.hpp"
+#include "pretty_expression.hpp"
+//#include "formal_arg.hpp"
+#include "xo/expression/Variable.hpp"
+#include "xo/indentlog/print/vector.hpp"
+#include "xo/indentlog/print/pretty_vector.hpp"
+#include <stdexcept>
+//#include "define_xs.hpp"
+//#include "progress_xs.hpp"
+//#include "paren_xs.hpp"
+//#include "expect_expr_xs.hpp"
+//#include "xo/expression/Constant.hpp"
+//#include "xo/reflect/Reflect.hpp"
+
+namespace xo {
+    //using xo::scm::Constant;
+    //using xo::reflect::Reflect;
+    using xo::reflect::TypeDescr;
+    using xo::print::ppindentinfo;
+
+    namespace scm {
+        const char *
+        exprstatetype_descr(exprstatetype x) {
+            switch (x) {
+            case exprstatetype::invalid:
+                return "?invalid";
+            case exprstatetype::expect_toplevel_expression_sequence:
+                return "expect_toplevel_expression_sequence";
+            case exprstatetype::defexpr:
+                return "defexpr";
+            case exprstatetype::lambdaexpr:
+                return "lambdaexpr";
+            case exprstatetype::applyexpr:
+                return "applyexpr";
+            case exprstatetype::parenexpr:
+                return "parenexpr";
+            case exprstatetype::sequenceexpr:
+                return "sequenceexpr";
+            case exprstatetype::let1expr:
+                return "let1expr";
+            case exprstatetype::ifexpr:
+                return "ifexpr";
+            case exprstatetype::expect_rhs_expression:
+                return "expect_rhs_expression";
+            case exprstatetype::expect_symbol:
+                return "expect_symbol";
+            case exprstatetype::expect_type:
+                return "expect_type";
+            case exprstatetype::expect_formal_arglist:
+                return "expect_formal_arglist";
+            case exprstatetype::expect_formal:
+                return "expect_formal";
+            case exprstatetype::expr_progress:
+                return "expr_progress";
+            case exprstatetype::n_exprstatetype:
+                break;
+            }
+
+            return "???";
+        }
+
+        void
+        exprstate::on_def_token(const token_type & tk,
+                                parserstatemachine * p_psm)
+        {
+            scope log(XO_DEBUG(p_psm->debug_flag()));
+
+            log && log(xtag("exstype", p_psm->top_exprstate().exs_type()));
+
+            constexpr const char * c_self_name = "exprstate::on_def_token";
+            const char * exp = get_expect_str();
+
+            this->illegal_input_on_token(c_self_name, tk, exp, p_psm);
+        }
+
+        void
+        exprstate::on_lambda_token(const token_type & tk,
+                                   parserstatemachine * p_psm)
+        {
+            constexpr const char * c_self_name = "exprstate::on_lambda_token";
+            const char * exp = this->get_expect_str();
+
+            this->illegal_input_on_token(c_self_name, tk, exp, p_psm);
+        }
+
+        void
+        exprstate::on_symbol_token(const token_type & tk,
+                                   parserstatemachine * p_psm)
+        {
+            constexpr bool c_debug_flag = true;
+            scope log(XO_DEBUG(c_debug_flag));
+
+            log && log(xtag("exstype", p_psm->top_exprstate().exs_type()));
+
+            constexpr const char * c_self_name = "exprstate::on_symbol_token";
+            const char * exp = get_expect_str();
+
+            this->illegal_input_on_token(c_self_name, tk, exp, p_psm);
+        }
+
+        void
+        exprstate::on_typedescr(TypeDescr td,
+                                parserstatemachine * p_psm)
+        {
+            /* returning type description to something that wants it */
+
+            scope log(XO_DEBUG(p_psm->debug_flag()));
+
+            log && log(xtag("exstype",
+                            p_psm->top_exprstate().exs_type()));
+
+            constexpr const char * c_self_name = "exprstate::on_typedescr";
+            const char * exp = get_expect_str();
+
+            this->illegal_input_on_type(c_self_name, td, exp, p_psm);
+        }
+
+        void
+        exprstate::on_formal(const rp<Variable> & formal,
+                             parserstatemachine * p_psm)
+        {
+            /* returning type description to something that wants it */
+
+            constexpr bool c_debug_flag = true;
+            scope log(XO_DEBUG(c_debug_flag));
+
+            log && log(xtag("exstype",
+                            p_psm->top_exprstate().exs_type()));
+
+            constexpr const char * c_self_name = "exprstate::on_formal";
+            const char * exp = this->get_expect_str();
+
+            std::string errmsg = tostr("unexpected formal-arg for parsing state",
+                                       xtag("expecting", exp),
+                                       xtag("formal", formal),
+                                       xtag("state", this->exs_type()));
+
+            p_psm->on_error(c_self_name, std::move(errmsg));
+        }
+
+        void
+        exprstate::on_formal_arglist(const std::vector<rp<Variable>> & argl,
+                                     parserstatemachine * p_psm)
+        {
+            /* returning type description to something that wants it */
+
+            constexpr bool c_debug_flag = true;
+            scope log(XO_DEBUG(c_debug_flag));
+
+            log && log(xtag("exstype",
+                            p_psm->top_exprstate().exs_type()));
+
+            constexpr const char * c_self_name = "exprstate::on_formal_arglist";
+            const char * exp = get_expect_str();
+
+            std::string errmsg = tostr("unexpected formal-arglist for parsing state",
+                                       xtag("expecting", exp),
+                                       xtag("argl", argl),
+                                       xtag("state", this->exs_type()));
+
+            p_psm->on_error(c_self_name, std::move(errmsg));
+        }
+
+        void
+        exprstate::on_colon_token(const token_type & tk,
+                                  parserstatemachine * p_psm)
+        {
+            scope log(XO_DEBUG(p_psm->debug_flag()));
+
+            constexpr const char * c_self_name = "exprstate::on_colon";
+            const char * exp = get_expect_str();
+
+            this->illegal_input_on_token(c_self_name, tk, exp, p_psm);
+        }
+
+        void
+        exprstate::on_comma_token(const token_type & tk,
+                                  parserstatemachine * p_psm)
+        {
+            constexpr bool c_debug_flag = true;
+            scope log(XO_DEBUG(c_debug_flag));
+
+            constexpr const char * c_self_name = "exprstate::on_comma";
+            const char * exp = get_expect_str();
+
+            this->illegal_input_on_token(c_self_name, tk, exp, p_psm);
+        }
+
+        void
+        exprstate::on_semicolon_token(const token_type & tk,
+                                      parserstatemachine * p_psm)
+        {
+            constexpr bool c_debug_flag = true;
+            scope log(XO_DEBUG(c_debug_flag));
+
+            constexpr const char * c_self_name = "exprstate::on_semicolon";
+            const char * exp = get_expect_str();
+
+            this->illegal_input_on_token(c_self_name, tk, exp, p_psm);
+        }
+
+        void
+        exprstate::on_singleassign_token(const token_type & tk,
+                                         parserstatemachine * p_psm) {
+            constexpr bool c_debug_flag = true;
+            scope log(XO_DEBUG(c_debug_flag));
+
+            constexpr const char * c_self_name = "exprstate::on_singleassign_token";
+            const char * exp = get_expect_str();
+
+            this->illegal_input_on_token(c_self_name, tk, exp, p_psm);
+        }
+
+        void
+        exprstate::on_assign_token(const token_type & tk,
+                                   parserstatemachine * p_psm)
+        {
+            constexpr bool c_debug_flag = true;
+            scope log(XO_DEBUG(c_debug_flag));
+
+            constexpr const char * c_self_name = "exprstate::on_assign_token";
+            const char * exp = get_expect_str();
+
+            this->illegal_input_on_token(c_self_name, tk, exp, p_psm);
+        }
+
+
+        void
+        exprstate::on_leftparen_token(const token_type & tk,
+                                      parserstatemachine * p_psm)
+        {
+            scope log(XO_DEBUG(p_psm->debug_flag()));
+
+            constexpr const char * c_self_name = "exprstate::on_leftparen_token";
+            const char * exp = get_expect_str();
+
+            this->illegal_input_on_token(c_self_name, tk, exp, p_psm);
+        }
+
+        void
+        exprstate::on_rightparen_token(const token_type & tk,
+                                       parserstatemachine * p_psm)
+        {
+            constexpr bool c_debug_flag = true;
+            scope log(XO_DEBUG(c_debug_flag));
+
+            constexpr const char * c_self_name = "exprstate::on_rightparen";
+            const char * exp = get_expect_str();
+
+            this->illegal_input_on_token(c_self_name, tk, exp, p_psm);
+        }
+
+        void
+        exprstate::on_leftbrace_token(const token_type & tk,
+                                      parserstatemachine * p_psm)
+        {
+            constexpr bool c_debug_flag = true;
+            scope log(XO_DEBUG(c_debug_flag));
+
+            constexpr const char * c_self_name = "exprstate::on_leftbrace_token";
+            const char * exp = get_expect_str();
+
+            this->illegal_input_on_token(c_self_name, tk, exp, p_psm);
+        }
+
+        void
+        exprstate::on_rightbrace_token(const token_type & tk,
+                                       parserstatemachine * p_psm)
+        {
+            constexpr bool c_debug_flag = true;
+            scope log(XO_DEBUG(c_debug_flag));
+
+            constexpr const char * c_self_name = "exprstate::on_rightbrace_token";
+            const char * exp = get_expect_str();
+
+            this->illegal_input_on_token(c_self_name, tk, exp, p_psm);
+        }
+
+        void
+        exprstate::on_operator_token(const token_type & tk,
+                                     parserstatemachine * p_psm)
+        {
+            constexpr bool c_debug_flag = true;
+            scope log(XO_DEBUG(c_debug_flag));
+
+            constexpr const char * c_self_name = "exprstate::on_operator_token";
+            const char * exp = get_expect_str();
+
+            this->illegal_input_on_token(c_self_name, tk, exp, p_psm);
+        }
+
+        void
+        exprstate::on_if_token(const token_type & tk,
+                               parserstatemachine * p_psm)
+        {
+            scope log(XO_DEBUG(p_psm->debug_flag()));
+
+            constexpr const char * c_self_name = "exprstate::on_if_token";
+            const char * exp = get_expect_str();
+
+            this->illegal_input_on_token(c_self_name, tk, exp, p_psm);
+        }
+
+        void
+        exprstate::on_then_token(const token_type & tk,
+                               parserstatemachine * p_psm)
+        {
+            scope log(XO_DEBUG(p_psm->debug_flag()));
+
+            constexpr const char * c_self_name = "exprstate::on_then_token";
+            const char * exp = get_expect_str();
+
+            this->illegal_input_on_token(c_self_name, tk, exp, p_psm);
+        }
+
+        void
+        exprstate::on_else_token(const token_type & tk,
+                               parserstatemachine * p_psm)
+        {
+            scope log(XO_DEBUG(p_psm->debug_flag()));
+
+            constexpr const char * c_self_name = "exprstate::on_else_token";
+            const char * exp = get_expect_str();
+
+            this->illegal_input_on_token(c_self_name, tk, exp, p_psm);
+        }
+
+        void
+        exprstate::on_bool_token(const token_type & tk,
+                                 parserstatemachine * p_psm)
+        {
+            scope log(XO_DEBUG(p_psm->debug_flag()));
+
+            constexpr const char * c_self_name = "exprstate::on_bool_token";
+            const char * exp = get_expect_str();
+
+            this->illegal_input_on_token(c_self_name, tk, exp, p_psm);
+        }
+
+        void
+        exprstate::on_i64_token(const token_type & tk,
+                                parserstatemachine * p_psm)
+        {
+            scope log(XO_DEBUG(p_psm->debug_flag()));
+
+            constexpr const char * c_self_name = "exprstate::on_i64_token";
+            const char * exp = get_expect_str();
+
+            this->illegal_input_on_token(c_self_name, tk, exp, p_psm);
+        }
+
+        void
+        exprstate::on_f64_token(const token_type & tk,
+                                parserstatemachine * p_psm)
+        {
+            scope log(XO_DEBUG(p_psm->debug_flag()));
+
+            constexpr const char * c_self_name = "exprstate::on_f64_token";
+            const char * exp = get_expect_str();
+
+            this->illegal_input_on_token(c_self_name, tk, exp, p_psm);
+        }
+
+        void
+        exprstate::on_string_token(const token_type & tk,
+                                   parserstatemachine * p_psm)
+        {
+            scope log(XO_DEBUG(p_psm->debug_flag()));
+
+            constexpr const char * c_self_name = "exprstate::on_string_token";
+            const char * exp = get_expect_str();
+
+            this->illegal_input_on_token(c_self_name, tk, exp, p_psm);
+        }
+
+        void
+        exprstate::on_input(const token_type & tk,
+                            parserstatemachine * p_psm)
+        {
+            scope log(XO_DEBUG(p_psm->debug_flag()));
+            log && log(xtag("tk", tk));
+            log && log(xtag("state", *this));
+            log && log(xtag("psm", p_psm));
+            log && log(xtag("proofoflogging", true));
+
+            switch (tk.tk_type()) {
+
+            case tokentype::tk_def:
+                this->on_def_token(tk, p_psm);
+                return;
+
+            case tokentype::tk_lambda:
+                this->on_lambda_token(tk, p_psm);
+                return;
+
+            case tokentype::tk_bool:
+                this->on_bool_token(tk, p_psm);
+                return;
+
+            case tokentype::tk_i64:
+                this->on_i64_token(tk, p_psm);
+                return;
+
+            case tokentype::tk_f64:
+                this->on_f64_token(tk, p_psm);
+                return;
+
+            case tokentype::tk_string:
+                this->on_string_token(tk, p_psm);
+                return;
+
+            case tokentype::tk_symbol:
+                this->on_symbol_token(tk, p_psm);
+                return;
+
+            case tokentype::tk_leftparen:
+                this->on_leftparen_token(tk, p_psm);
+                return;
+
+            case tokentype::tk_rightparen:
+                this->on_rightparen_token(tk, p_psm);
+                return;
+
+            case tokentype::tk_leftbracket:
+            case tokentype::tk_rightbracket:
+                assert(false);
+                break;
+
+            case tokentype::tk_leftbrace:
+                this->on_leftbrace_token(tk, p_psm);
+                return;
+
+            case tokentype::tk_rightbrace:
+                this->on_rightbrace_token(tk, p_psm);
+                return;
+
+            case tokentype::tk_leftangle:
+            case tokentype::tk_rightangle:
+            case tokentype::tk_lessequal:
+            case tokentype::tk_greatequal:
+                this->on_operator_token(tk, p_psm);
+                return;
+
+            case tokentype::tk_dot:
+                assert(false);
+                return;
+
+            case tokentype::tk_comma:
+                this->on_comma_token(tk, p_psm);
+                return;
+
+            case tokentype::tk_colon:
+                this->on_colon_token(tk, p_psm);
+                return;
+
+            case tokentype::tk_doublecolon:
+                assert(false);
+                return;
+
+            case tokentype::tk_semicolon:
+                this->on_semicolon_token(tk, p_psm);
+                return;
+
+            case tokentype::tk_singleassign:
+                this->on_singleassign_token(tk, p_psm);
+                return;
+
+            case tokentype::tk_assign:
+                this->on_assign_token(tk, p_psm);
+                return;
+
+            case tokentype::tk_yields:
+                assert(false);
+                break;
+
+            case tokentype::tk_plus:
+            case tokentype::tk_minus:
+            case tokentype::tk_star:
+            case tokentype::tk_slash:
+            case tokentype::tk_cmpeq:
+            case tokentype::tk_cmpne:
+                this->on_operator_token(tk, p_psm);
+                return;
+
+            case tokentype::tk_type:
+                assert(false);
+                return;
+
+            case tokentype::tk_if:
+                this->on_if_token(tk, p_psm);
+                return;
+
+            case tokentype::tk_then:
+                this->on_then_token(tk, p_psm);
+                return;
+
+            case tokentype::tk_else:
+                this->on_else_token(tk, p_psm);
+                return;
+
+            case tokentype::tk_let:
+
+            case tokentype::tk_in:
+            case tokentype::tk_end:
+                assert(false);
+                return;
+
+            case tokentype::tk_invalid:
+            case tokentype::n_tokentype:
+                assert(false);
+                return;
+            }
+
+            assert(false);
+        }
+
+        const char *
+        exprstate::get_expect_str() const
+        {
+            return "?expect";
+        }
+
+        void
+        exprstate::on_expr(bp<Expression> expr,
+                           parserstatemachine * p_psm)
+        {
+            constexpr bool c_debug_flag = true;
+            scope log(XO_DEBUG(c_debug_flag));
+
+            log && log(xtag("exstype", this->exs_type_),
+                       xtag("expr", expr));
+
+            constexpr const char * c_self_name = "exprstate::on_expr";
+            const char * exp = get_expect_str();
+
+            this->illegal_input_on_expr(c_self_name, expr, exp, p_psm);
+        } /*on_expr*/
+
+        void
+        exprstate::on_expr_with_semicolon(bp<Expression> expr,
+                                          parserstatemachine * p_psm)
+        {
+            constexpr bool c_debug_flag = true;
+            scope log(XO_DEBUG(c_debug_flag));
+
+            log && log(xtag("exstype", this->exs_type_),
+                       xtag("expr", expr));
+
+            constexpr const char * c_self_name = "exprstate::on_expr_with_semicolon";
+            const char * exp = get_expect_str();
+
+            this->illegal_input_on_expr(c_self_name, expr, exp, p_psm);
+        } /*on_expr_with_semicolon*/
+
+        void
+        exprstate::on_symbol(const std::string & symbol_name,
+                             parserstatemachine * p_psm)
+        {
+            /* unreachable - derived class that can receive
+             * will override this method
+             */
+            constexpr bool c_debug_flag = true;
+            scope log(XO_DEBUG(c_debug_flag));
+
+            log && log(xtag("exstype", this->exs_type_),
+                       xtag("symbol_name", symbol_name));
+
+            constexpr const char * c_self_name = "exprstate::on_symbol";
+            const char * exp = get_expect_str();
+
+            this->illegal_input_on_symbol(c_self_name, symbol_name, exp, p_psm);
+        }
+
+        void
+        exprstate::print(std::ostream & os) const {
+            os << "<exprstate"
+               << xtag("this", (void*)this)
+               << xtag("type", exs_type_);
+            os << ">";
+        }
+
+        bool
+        exprstate::pretty_print(const ppindentinfo & ppii) const
+        {
+            return ppii.pps()->pretty_struct(ppii, "exprstate",
+                                             refrtag("type", exs_type_));
+        }
+
+        void
+        exprstate::illegal_input_error(const char * self_name,
+                                       const token_type & tk) const
+        {
+            throw std::runtime_error
+                (tostr(self_name,
+                       ": unexpected input token for parsing state",
+                       xtag("token", tk),
+                       xtag("state", *this)));
+        }
+
+        void
+        exprstate::illegal_input_on_expr(const char * self_name,
+                                        bp<Expression> expr,
+                                        const char * expect_str,
+                                        parserstatemachine * p_psm) const
+        {
+            std::string errmsg = tostr("unexpected expression for parsing state",
+                                       xtag("expecting", expect_str),
+                                       xtag("expr", expr),
+                                       xtag("state", this->exs_type()));
+
+            p_psm->on_error(self_name, std::move(errmsg));
+        }
+
+        void
+        exprstate::illegal_input_on_token(const char * self_name,
+                                          const token_type & tk,
+                                          const char * expect_str,
+                                          parserstatemachine * p_psm) const
+        {
+            std::string errmsg = tostr("exprstate::illegal_input_on_token: unexpected token for parsing state",
+                                       xtag("expecting", expect_str),
+                                       xtag("token", tk.tk_type()),
+                                       xtag("text", tk.text()),
+                                       xtag("state", this->exs_type()));
+
+            p_psm->on_error(self_name, std::move(errmsg));
+        }
+
+        void
+        exprstate::illegal_input_on_symbol(const char * self_name,
+                                           const std::string & symbol,
+                                           const char * expect_str,
+                                           parserstatemachine * p_psm) const
+        {
+            std::string errmsg = tostr("unexpected symbol",
+                                       xtag("expecting", expect_str),
+                                       xtag("symbol", symbol),
+                                       xtag("state", this->exs_type()));
+
+            p_psm->on_error(self_name, std::move(errmsg));
+        }
+
+        void
+        exprstate::illegal_input_on_type(const char * self_name,
+                                         const TypeDescr td,
+                                         const char * expect_str,
+                                         parserstatemachine * p_psm) const
+        {
+            std::string errmsg = tostr("unexpected type",
+                                       xtag("expecting", expect_str),
+                                       xtag("type", td),
+                                       xtag("state", this->exs_type()));
+
+            p_psm->on_error(self_name, std::move(errmsg));
+        }
+
+        void
+        exprstate::unknown_variable_error(const char * self_name,
+                                          const token_type & tk,
+                                          parserstatemachine * p_psm) const
+        {
+            std::string errmsg = tostr("unknown variable name",
+                                       xtag("var", tk.text()));
+
+            p_psm->on_error(self_name, std::move(errmsg));
+        }
+    } /*namespace scm*/
+} /*namespace xo*/
+
+/* end exprstate.cpp */
diff --git a/xo-reader/src/reader/exprstatestack.cpp b/xo-reader/src/reader/exprstatestack.cpp
new file mode 100644
index 00000000..96852b73
--- /dev/null
+++ b/xo-reader/src/reader/exprstatestack.cpp
@@ -0,0 +1,120 @@
+/* file exprstatestack.cpp
+ *
+ * author: Roland Conybeare
+ */
+
+#include "exprstatestack.hpp"
+#include "pretty_exprstatestack.hpp"
+#include <cstdint>
+
+namespace xo {
+    namespace scm {
+        exprstate &
+        exprstatestack::top_exprstate() {
+            std::size_t z = stack_.size();
+
+            if (z == 0) {
+                throw std::runtime_error
+                    ("parser::top_exprstate: unexpected empty stack");
+            }
+
+            return *(stack_[z-1]);
+        }
+
+        void
+        exprstatestack::reset_to_toplevel() {
+            this->stack_.resize(1);
+        }
+
+        void
+        exprstatestack::push_exprstate(std::unique_ptr<exprstate> exs) {
+            constexpr bool c_debug_flag = false;
+            scope log(XO_DEBUG(c_debug_flag),
+                      xtag("exs", exs.get()));
+
+            std::size_t z = stack_.size();
+
+            stack_.resize(z+1);
+
+            stack_[z] = std::move(exs);
+        }
+
+        std::unique_ptr<exprstate>
+        exprstatestack::pop_exprstate() {
+            constexpr bool c_debug_flag = false;
+            scope log(XO_DEBUG(c_debug_flag),
+                      xtag("top.exstype", top_exprstate().exs_type()));
+
+            std::size_t z = stack_.size();
+
+            if (z > 0) {
+                std::unique_ptr<exprstate> top = std::move(stack_[z-1]);
+
+                stack_.resize(z-1);
+
+                return top;
+            } else {
+                return nullptr;
+            }
+        }
+
+        void
+        exprstatestack::print(std::ostream & os) const {
+            os << "<exprstatestack"
+               << xtag("size", stack_.size())
+               << std::endl;
+
+            for (std::size_t i = 0, z = stack_.size(); i < z; ++i) {
+                os << "  [" << z-i-1 << "] "
+                   << stack_[i].get()
+                   << std::endl;
+            }
+
+            os << ">" << std::endl;
+        }
+
+        bool
+        exprstatestack::pretty_print(const ppindentinfo & ppii) const
+        {
+            ppstate * pps = ppii.pps();
+
+            if (ppii.upto()) {
+                if (stack_.size() > 1)
+                    return false;
+
+                if (!pps->print_upto("<exprstatestack"))
+                    return false;
+
+                if (!pps->print_upto_tag("size", stack_.size()))
+                    return false;
+
+                /** always multiple lines if more than one element in stack **/
+                if ((stack_.size() > 0)
+                    && !pps->print_upto_tag("[0]", stack_[0].get()))
+                {
+                    return false;
+                }
+
+                pps->write(">");
+
+                return true;
+            } else {
+                pps->write("<exprstatestack");
+
+                pps->newline_pretty_tag(ppii.ci1(), "size", stack_.size());
+
+                for (std::size_t i = 0, z = stack_.size(); i < z; ++i) {
+                    std::string i_str = tostr("[", z-i-1, "]");
+
+                    pps->newline_pretty_tag(ppii.ci1(), i_str, stack_[i].get());
+                }
+
+                pps->write(">");
+
+                return false;
+            }
+        }
+    } /*namespace scm*/
+} /*namespace xo*/
+
+/* end exprstatestack.cpp */
diff --git a/xo-reader/src/reader/if_else_xs.cpp b/xo-reader/src/reader/if_else_xs.cpp
new file mode 100644
index 00000000..01d142e0
--- /dev/null
+++ b/xo-reader/src/reader/if_else_xs.cpp
@@ -0,0 +1,288 @@
+/** @file if_else_xs.cpp
+ *
+ *  author: Roland Conybeare, Jul 2025
+ **/
+
+#include "if_else_xs.hpp"
+//#include "exprstatestack.hpp"
+#include "parserstatemachine.hpp"
+#include "expect_expr_xs.hpp"
+#include "xo/indentlog/print/ppdetail_atomic.hpp"
+
+namespace xo {
+    namespace scm {
+        // ----- ifexprstatetype -----
+
+        const char *
+        ifexprstatetype_descr(ifexprstatetype x) {
+            switch (x) {
+            case ifexprstatetype::invalid: return "invalid";
+            case ifexprstatetype::if_0: return "if_0";
+            case ifexprstatetype::if_1: return "if_1";
+            case ifexprstatetype::if_2: return "if_2";
+            case ifexprstatetype::if_3: return "if_3";
+            case ifexprstatetype::if_4: return "if_4";
+            case ifexprstatetype::if_5: return "if_5";
+            case ifexprstatetype::if_6: return "if_6";
+            case ifexprstatetype::n_ifexprstatetype: break;
+            }
+
+            return "???ifexprstatetype";
+        }
+
+        std::ostream &
+        operator<<(std::ostream & os, ifexprstatetype x) {
+            os << ifexprstatetype_descr(x);
+            return os;
+        }
+
+        // ----- if_else_xs -----
+
+        std::unique_ptr<if_else_xs>
+        if_else_xs::make() {
+            return std::make_unique<if_else_xs>(if_else_xs(IfExprAccess::make_empty()));
+        }
+
+        void
+        if_else_xs::start(parserstatemachine * p_psm)
+        {
+            constexpr bool c_debug_flag = true;
+            scope log(XO_DEBUG(c_debug_flag));
+
+            p_psm->push_exprstate(if_else_xs::make());
+            p_psm->top_exprstate().on_if_token(token_type::if_token(), p_psm);
+        }
+
+        if_else_xs::if_else_xs(rp<IfExprAccess> if_expr)
+            : exprstate(exprstatetype::ifexpr),
+              ifxs_type_{ifexprstatetype::if_0},
+              if_expr_{std::move(if_expr)}
+        {}
+
+        const char *
+        if_else_xs::get_expect_str() const
+        {
+            /**
+             *   if test-expr then then-expr else else-expr ;
+             *  ^  ^         ^    ^         ^    ^         ^
+             *  |  |         |    |         |    |         |
+             *  |  if_1      if_2 if_3      if_4 if_5      if_6
+             *  if_0
+             *
+             *  if_0 --on_if_token()--> if_1
+             *  if_1 --on_expr()--> if_2
+             *  if_2 --on_then_token()--> if_3
+             *  if_3 --on_expr()--> if_4
+             *  if_4 --on_else_token()--> if_5
+             *       --on_semicolon_token()--> (done)
+             *  if_5 --on_expr()-->if_6
+             *  if_6 --on_semicolon_token()--> (done)
+             **/
+            switch (this->ifxs_type_) {
+            case ifexprstatetype::invalid:
+            case ifexprstatetype::if_0:
+            case ifexprstatetype::n_ifexprstatetype:
+                assert(false); // unreachable
+                return nullptr;
+            case ifexprstatetype::if_1:
+                return "expression";
+            case ifexprstatetype::if_2:
+                return "then";
+            case ifexprstatetype::if_3:
+                return "expression";
+            case ifexprstatetype::if_4:
+                return "else|semicolon";
+            case ifexprstatetype::if_5:
+                return "expression";
+            case ifexprstatetype::if_6:
+                return "semicolon";
+            }
+
+            return "?expect";
+        }
+
+        void
+        if_else_xs::on_if_token(const token_type & tk,
+                                parserstatemachine * p_psm)
+        {
+            scope log(XO_DEBUG(p_psm->debug_flag()));
+
+            log && log("ifxs_type", ifxs_type_);
+
+            if (this->ifxs_type_ == ifexprstatetype::if_0) {
+                this->ifxs_type_ = ifexprstatetype::if_1;
+
+                expect_expr_xs::start(p_psm);
+                return;
+            }
+
+            constexpr const char * c_self_name = "if_else_xs::on_if_token";
+            const char * exp = this->get_expect_str();
+
+            this->illegal_input_on_token(c_self_name, tk, exp, p_psm);
+        }
+
+        void
+        if_else_xs::on_then_token(const token_type & tk,
+                                  parserstatemachine * p_psm)
+        {
+            scope log(XO_DEBUG(p_psm->debug_flag()));
+
+            log && log("ifxs_type", ifxs_type_);
+
+            if (this->ifxs_type_ == ifexprstatetype::if_2) {
+                this->ifxs_type_ = ifexprstatetype::if_3;
+
+                expect_expr_xs::start(p_psm);
+                return;
+            }
+
+            constexpr const char * c_self_name = "if_else_xs::on_then_token";
+            const char * exp = this->get_expect_str();
+
+            this->illegal_input_on_token(c_self_name, tk, exp, p_psm);
+        }
+
+        void
+        if_else_xs::on_else_token(const token_type & tk,
+                                  parserstatemachine * p_psm)
+        {
+            scope log(XO_DEBUG(p_psm->debug_flag()));
+
+            log && log("ifxs_type", ifxs_type_);
+
+            if (this->ifxs_type_ == ifexprstatetype::if_4) {
+                this->ifxs_type_ = ifexprstatetype::if_5;
+
+                expect_expr_xs::start(p_psm);
+                return;
+            }
+
+            constexpr const char * c_self_name = "if_else_xs::on_else_token";
+            const char * exp = this->get_expect_str();
+
+            this->illegal_input_on_token(c_self_name, tk, exp, p_psm);
+        }
+
+        void
+        if_else_xs::finish_and_continue(parserstatemachine * p_psm)
+        {
+            rp<IfExprAccess> if_expr = this->if_expr_;
+            std::unique_ptr<exprstate> self = p_psm->pop_exprstate();
+
+            if (this->ifxs_type_ == ifexprstatetype::if_4) {
+                /* if no else-branch, then if-expr can't have valuetype */
+                if_expr->assign_valuetype(nullptr);
+            }
+
+            p_psm->top_exprstate().on_expr(if_expr, p_psm);
+        }
+
+        void
+        if_else_xs::on_rightbrace_token(const token_type & tk,
+                                        parserstatemachine * p_psm)
+        {
+            scope log(XO_DEBUG(p_psm->debug_flag()));
+
+            this->finish_and_continue(p_psm);
+            p_psm->on_rightbrace_token(tk);
+        }
+
+        void
+        if_else_xs::on_semicolon_token(const token_type & tk,
+                                       parserstatemachine * p_psm)
+        {
+            scope log(XO_DEBUG(p_psm->debug_flag()));
+
+            log && log("ifxs_type", ifxs_type_);
+
+            const char * c_self_name = "if_else_xs::on_semicolon_token";
+
+            switch (this->ifxs_type_) {
+            case ifexprstatetype::invalid:
+            case ifexprstatetype::if_0:
+            case ifexprstatetype::n_ifexprstatetype:
+                // unreachable
+                assert(false);
+                break;
+
+            case ifexprstatetype::if_1:
+            case ifexprstatetype::if_2:
+            case ifexprstatetype::if_3:
+            case ifexprstatetype::if_5:
+                this->illegal_input_on_token(c_self_name, tk, get_expect_str(), p_psm);
+                break;
+            case ifexprstatetype::if_4:
+            case ifexprstatetype::if_6: {
+                this->finish_and_continue(p_psm);
+                break;
+            }
+            }
+        }
+
+        void
+        if_else_xs::on_expr(bp<Expression> expr,
+                            parserstatemachine * p_psm)
+        {
+            scope log(XO_DEBUG(p_psm->debug_flag()));
+
+            log && log(xtag("ifxs_type", ifxs_type_));
+
+            switch (this->ifxs_type_) {
+            case ifexprstatetype::invalid:
+            case ifexprstatetype::if_0:
+            case ifexprstatetype::n_ifexprstatetype:
+                assert(false); // unreachable
+                return;
+            case ifexprstatetype::if_1:
+                if_expr_->assign_test(expr.promote());
+                ifxs_type_ = ifexprstatetype::if_2;
+                return;
+            case ifexprstatetype::if_2:
+                /** error: expecting 'then' **/
+                break;
+            case ifexprstatetype::if_3:
+                if_expr_->assign_when_true(expr.promote());
+                ifxs_type_ = ifexprstatetype::if_4;
+                return;
+            case ifexprstatetype::if_4:
+                /** error: expecting 'else' or ';' **/
+                break;
+            case ifexprstatetype::if_5:
+                if_expr_->assign_when_false(expr.promote());
+                ifxs_type_ = ifexprstatetype::if_6;
+                return;
+            case ifexprstatetype::if_6:
+                /** error: expecting ';' **/
+                break;
+            }
+
+            constexpr const char* c_self_name = "if_else_xs::on_expr";
+            const char * exp = get_expect_str();
+
+            this->illegal_input_on_expr(c_self_name, expr, exp, p_psm);
+        }
+
+        void
+        if_else_xs::on_expr_with_semicolon(bp<Expression> expr,
+                                           parserstatemachine * p_psm)
+        {
+            scope log(XO_DEBUG(p_psm->debug_flag()));
+
+
+            log && log(xtag("ifxs_type", ifxs_type_));
+
+            this->on_expr(expr, p_psm);
+            this->on_semicolon_token(token_type::semicolon(), p_psm);
+        }
+
+        void
+        if_else_xs::print(std::ostream & os) const {
+            os << "<if_else_xs"
+               << xtag("this", (void*)this)
+               << xtag("ifxs_type", ifxs_type_)
+               << ">";
+        }
+
+    } /*namespace scm*/
+} /*namespace xo*/
diff --git a/xo-reader/src/reader/lambda_xs.cpp b/xo-reader/src/reader/lambda_xs.cpp
new file mode 100644
index 00000000..ca070627
--- /dev/null
+++ b/xo-reader/src/reader/lambda_xs.cpp
@@ -0,0 +1,315 @@
+/* @file lambda_xs.cpp */
+
+#include "lambda_xs.hpp"
+#include "define_xs.hpp"
+#include "parserstatemachine.hpp"
+#include "exprstatestack.hpp"
+#include "expect_formal_arglist_xs.hpp"
+#include "expect_expr_xs.hpp"
+#include "expect_type_xs.hpp"
+#include "pretty_expression.hpp"
+#include "pretty_variable.hpp"
+#include "xo/expression/Lambda.hpp"
+
+namespace xo {
+    using xo::scm::Lambda;
+    using xo::scm::LocalSymtab;
+
+    namespace scm {
+        const char *
+        lambdastatetype_descr(lambdastatetype x) {
+            switch(x) {
+            case lambdastatetype::invalid: return "invalid";
+            case lambdastatetype::lm_0: return "lm_0";
+            case lambdastatetype::lm_1: return "lm_1";
+            case lambdastatetype::lm_2: return "lm_2";
+            case lambdastatetype::lm_3: return "lm_3";
+            case lambdastatetype::lm_4: return "lm_4";
+            case lambdastatetype::lm_5: return "lm_5";
+            default: break;
+            }
+
+            return "???lambdastatetype";
+        }
+
+        // ----- lambda_xs - ----
+
+        std::unique_ptr<lambda_xs>
+        lambda_xs::make() {
+            return std::make_unique<lambda_xs>(lambda_xs());
+        }
+
+        void
+        lambda_xs::start(parserstatemachine * p_psm)
+        {
+            p_psm->push_exprstate(lambda_xs::make());
+            p_psm->top_exprstate()
+                .on_lambda_token(token_type::lambda(), p_psm);
+        }
+
+        lambda_xs::lambda_xs() : exprstate(exprstatetype::lambdaexpr) {}
+
+        const char *
+        lambda_xs::get_expect_str() const
+        {
+            /*
+             *   lambda (x : f64) : f64 { ... } ;
+             *  ^      ^         ^ ^   ^       ^
+             *  |      |         | |   |       lm_5
+             *  |      |         | |   lm_4:expect_expression
+             *  |      |         | lm_3
+             *  |      |         lm_2
+             *  |      lm_1:
+             *  expect_expression
+             */
+             switch (this->lmxs_type_) {
+             case lambdastatetype::invalid:
+             case lambdastatetype::lm_0:
+             case lambdastatetype::n_lambdastatetype:
+                 assert(false); // impossible
+                 return nullptr;
+             case lambdastatetype::lm_1:
+                 return "lambda-params";
+             case lambdastatetype::lm_2:
+                 return "colon|lambda-body";
+             case lambdastatetype::lm_3:
+                 return "type";
+             case lambdastatetype::lm_4:
+                 return "lambda-body";
+             case lambdastatetype::lm_5:
+                 return "semicolon";
+             }
+
+             return "?expect";
+        }
+
+        void
+        lambda_xs::on_lambda_token(const token_type & tk,
+                                   parserstatemachine * p_psm)
+        {
+            if (lmxs_type_ == lambdastatetype::lm_0) {
+                this->lmxs_type_ = lambdastatetype::lm_1;
+                expect_formal_arglist_xs::start(p_psm);
+            } else {
+                exprstate::on_lambda_token(tk, p_psm);
+            }
+        }
+
+        void
+        lambda_xs::on_formal_arglist(const std::vector<rp<Variable>> & argl,
+                                     parserstatemachine * p_psm)
+        {
+            if (lmxs_type_ == lambdastatetype::lm_1) {
+                this->lmxs_type_ = lambdastatetype::lm_2;
+                this->parent_env_ = p_psm->top_envframe().promote();
+                this->local_env_ = LocalSymtab::make(argl, parent_env_);
+
+                p_psm->push_envframe(local_env_);
+
+                //expect_expr_xs::start(p_psm);
+            } else {
+                exprstate::on_formal_arglist(argl, p_psm);
+            }
+        }
+
+        void
+        lambda_xs::on_expr_with_semicolon(bp<Expression> expr,
+                                          parserstatemachine * p_psm)
+        {
+            this->on_expr(expr, p_psm);
+            this->on_semicolon_token(token_type::semicolon(), p_psm);
+        }
+
+        void
+        lambda_xs::on_colon_token(const token_type & tk,
+                                  parserstatemachine * p_psm)
+        {
+            constexpr const char * c_self_name = "lambda_xs::on_colon_token";
+
+            if (lmxs_type_ == lambdastatetype::lm_2) {
+                this->lmxs_type_ = lambdastatetype::lm_3;
+                expect_type_xs::start(p_psm);
+                /* control reenters via .on_typedescr() */
+            } else {
+                this->illegal_input_on_token(c_self_name, tk, this->get_expect_str(), p_psm);
+            }
+        }
+
+        void
+        lambda_xs::on_leftbrace_token(const token_type & tk,
+                                      parserstatemachine * p_psm)
+        {
+            constexpr const char * c_self_name = "lambda_xs::on_leftbrace_token";
+
+            if (lmxs_type_ == lambdastatetype::lm_2)
+                this->lmxs_type_ = lambdastatetype::lm_4;
+
+            if (lmxs_type_ == lambdastatetype::lm_4) {
+                expect_expr_xs::start(p_psm);
+                /* want { to start expr sequence, that finishes on matching } */
+                p_psm->on_leftbrace_token(token_type::leftbrace());
+            } else {
+                this->illegal_input_on_token(c_self_name, tk, this->get_expect_str(), p_psm);
+            }
+        }
+
+        void
+        lambda_xs::on_typedescr(TypeDescr td,
+                                parserstatemachine * p_psm)
+        {
+            constexpr const char * c_self_name = "lambda_xs::on_typedescr";
+            scope log(XO_DEBUG(p_psm->debug_flag()));
+
+            assert(td);
+
+            if (lmxs_type_ == lambdastatetype::lm_3) {
+                this->lmxs_type_ = lambdastatetype::lm_4;
+                this->explicit_return_td_ = td;
+
+                this->lambda_td_ = Lambda::assemble_lambda_td(local_env_->argv(),
+                                                              explicit_return_td_);
+
+                /* 1. at this point we know function signature (@ref lambda_td_)
+                 * 2. if this lambda appears on the rhs of a define,
+                 *    propagate function signature to the define.
+                 * 3. this makes recursive function definitions like this work
+                 *    without relying on type inference:
+                 *       def fact = lambda (n : i64) : i64 {
+                 *         if (n == 0) then
+                 *           1
+                 *         else
+                 *           n * fact(n - 1)
+                 *       }
+                 * 4. while parsing the body of the lambda, we want environment
+                 *    to already associate the lambda's signature with variable 'fact',
+                 *    so that when parser encounters 'fact(n - 1)' the expression has
+                 *    known valuetype.
+                 */
+
+                if ((p_psm->exprstate_stack_size() >= 3)
+                    && (p_psm->lookup_exprstate(1).exs_type() == exprstatetype::expect_rhs_expression)
+                    && (p_psm->lookup_exprstate(2).exs_type() == exprstatetype::defexpr)
+                    && (p_psm->env_stack_size() >= 2)
+                    )
+                {
+                    const define_xs * def_xs = dynamic_cast<const define_xs*>(&(p_psm->lookup_exprstate(2)));
+
+                    assert(def_xs);
+
+                    bp<Variable> def_var = def_xs->lhs_variable();
+
+                    if (def_var->valuetype() == nullptr) {
+                        log && log("assign discovered lambda type T to enclosing define",
+                                   xtag("lhs", def_var.get()),
+                                   xtag("T", print::unq(this->lambda_td_->canonical_name())));
+
+                        def_var->assign_valuetype(lambda_td_);
+                    } else {
+                        /* don't need to unify here.  if def already hasa a type,
+                         * that's because it was explicitly specified.
+                         * will discover any conflict after reporting parsed lambda
+                         * to define_xs
+                         */
+                    }
+                }
+
+                expect_expr_xs::start(p_psm);
+                /* control reenters via .on_expr() or .on_expr_with_semicolon() */
+            } else {
+                this->illegal_input_on_type(c_self_name, td, this->get_expect_str(), p_psm);
+            }
+        }
+
+        void
+        lambda_xs::on_expr(bp<Expression> expr,
+                           parserstatemachine * p_psm)
+        {
+            constexpr const char * c_self_name = "lambda_xs::on_expr";
+
+            if (lmxs_type_ == lambdastatetype::lm_4) {
+                this->lmxs_type_ = lambdastatetype::lm_5;
+                this->body_ = expr.promote();
+            } else {
+                this->illegal_input_on_expr(c_self_name, expr, this->get_expect_str(), p_psm);
+            }
+        }
+
+        void
+        lambda_xs::on_semicolon_token(const token_type & tk,
+                                      parserstatemachine * p_psm)
+        {
+            if (lmxs_type_ == lambdastatetype::lm_5) {
+                /* done! */
+
+                std::unique_ptr<exprstate> self = p_psm->pop_exprstate();
+
+                std::string name = Variable::gensym("lambda");
+
+                /* top env frame recorded arguments to this lambda */
+                p_psm->pop_envframe();
+
+                rp<Lambda> lm;
+
+                /* TODO: unify explicit_return_td_ with body_ */
+
+                if (lambda_td_) {
+                    lm = Lambda::make(name, lambda_td_, local_env_, body_);
+                } else {
+                    lm = Lambda::make_from_env(name, local_env_,
+                                               explicit_return_td_, body_);
+                }
+
+                p_psm->top_exprstate().on_expr(lm, p_psm);
+                p_psm->top_exprstate().on_semicolon_token(tk, p_psm);
+
+                return;
+            }
+
+            exprstate::on_semicolon_token(tk, p_psm);
+        }
+
+        void
+        lambda_xs::on_f64_token(const token_type & tk,
+                                parserstatemachine * p_psm)
+        {
+            constexpr const char * c_self_name = "lambda_xs::on_f64_token";
+
+            /* f64 literal can begin lambda body, otherwise illegal.
+             * for example:
+             *   def foo = lambda (x: bool) 3.14;
+             */
+            if (lmxs_type_ == lambdastatetype::lm_2) {
+                /* omitting return type.
+                 * omitting left brace.
+                 */
+                this->lmxs_type_ = lambdastatetype::lm_4;
+
+                expect_expr_xs::start(p_psm);
+                p_psm->on_f64_token(tk);
+            } else {
+                this->illegal_input_on_token(c_self_name, tk, this->get_expect_str(), p_psm);
+            }
+        }
+
+        // TODO: on_i64_token, on_bool token
+
+        void
+        lambda_xs::print(std::ostream & os) const {
+            os << "<lambda_xs"
+               << xtag("lmxs_type", lmxs_type_)
+               << ">";
+        }
+
+        bool
+        lambda_xs::pretty_print(const xo::print::ppindentinfo & ppii) const
+        {
+            return ppii.pps()->pretty_struct(ppii, "lambda_xs",
+                                             refrtag("lmxs_type", lmxs_type_),
+                                             refrtag("body", body_));
+        }
+
+    } /*namespace scm*/
+} /*namespace xo*/
+
+
+/* end lambda_xs.cpp */
diff --git a/xo-reader/src/reader/let1_xs.cpp b/xo-reader/src/reader/let1_xs.cpp
new file mode 100644
index 00000000..2a65b2a3
--- /dev/null
+++ b/xo-reader/src/reader/let1_xs.cpp
@@ -0,0 +1,162 @@
+/* file let1_xs.cpp
+ *
+ * author: Roland Conybeare
+ */
+
+#include "let1_xs.hpp"
+#include "expect_expr_xs.hpp"
+#include "parserstatemachine.hpp"
+#include "xo/expression/Sequence.hpp"
+#include "xo/expression/DefineExpr.hpp"
+#include "xo/expression/Apply.hpp"
+#include "xo/expression/Lambda.hpp"
+
+namespace xo {
+    using Sequence = xo::scm::Sequence;
+    using DefineExpr = xo::scm::DefineExpr;
+    using Apply = xo::scm::Apply;
+    using Lambda = xo::scm::Lambda;
+    using LambdaAccess = xo::scm::LambdaAccess;
+    using Environment = xo::scm::SymbolTable;
+    using LocalEnv = xo::scm::LocalSymtab;
+    using Variable = xo::scm::Variable;
+
+    namespace scm {
+        std::unique_ptr<let1_xs>
+        let1_xs::make(std::string lhs_name,
+                      rp<LocalEnv> local_env,
+                      rp<Expression> rhs)
+        {
+            return std::make_unique<let1_xs>(let1_xs(std::move(lhs_name),
+                                                     std::move(local_env),
+                                                     std::move(rhs)));
+        }
+
+        void
+        let1_xs::start(const std::string & lhs_name,
+                       const rp<Expression> & rhs,
+                       parserstatemachine * p_psm)
+        {
+            rp<SymbolTable> parent_env = p_psm->top_envframe().promote();
+            rp<Variable> var1 = Variable::make(lhs_name, rhs->valuetype());
+            rp<LocalEnv> let_env = LocalEnv::make1(var1, parent_env);
+
+            p_psm->push_envframe(let_env);
+
+            // TODO: stash let_env in let1_xs, then pick up directly in .on_rightbrace_token()
+            //       still have to push here so vars can find it
+            //
+            p_psm->push_exprstate(let1_xs::make(lhs_name, let_env, rhs));
+
+            expect_expr_xs::start(true /*allow_defs*/,
+                                  true /*cxl_on_rightbrace*/,
+                                  p_psm);
+        }
+
+        let1_xs::let1_xs(std::string lhs_name,
+                         rp<LocalEnv> local_env,
+                         rp<Expression> rhs)
+            : exprstate(exprstatetype::let1expr),
+              lhs_name_{std::move(lhs_name)},
+              local_env_{std::move(local_env)},
+              rhs_{std::move(rhs)}
+        {}
+
+        void
+        let1_xs::on_expr(bp<Expression> expr,
+                         parserstatemachine * p_psm)
+        {
+            constexpr bool c_debug_flag = true;
+            scope log(XO_DEBUG(c_debug_flag));
+
+            bp<DefineExpr> def_expr = DefineExpr::from(expr);
+
+            if (def_expr) {
+                /** starting a nested let here:
+                 *  control returns via
+                 *   .on_expr(x)
+                 *      with x something like:
+                 *    Apply(Lambda(gensym(),
+                 *                 [Variable(def_expr->lhs_name(),
+                 *                           def_expr->valuetype())],
+                 *                 body...))
+                 *  followed immediately by
+                 *   .on_rightbrace_token()
+                 **/
+                let1_xs::start(def_expr->lhs_name(),
+                               def_expr->rhs(),
+                               p_psm);
+            } else {
+                this->expr_v_.push_back(expr.promote());
+
+                expect_expr_xs::start(true /*allow_defs*/,
+                                      true /*cxl_on_rightbrace*/,
+                                      p_psm);
+            }
+        }
+
+        void
+        let1_xs::on_expr_with_semicolon(bp<Expression> expr,
+                                        parserstatemachine * p_psm)
+        {
+            /* same as on_expr(), since we only use let1_xs inside a block { .. }
+             * This means final ';' is unnecessary
+             */
+
+            constexpr bool c_debug_flag = true;
+            scope log(XO_DEBUG(c_debug_flag));
+
+            bp<DefineExpr> def_expr = DefineExpr::from(expr);
+
+            if (def_expr) {
+                let1_xs::start(def_expr->lhs_name(),
+                               def_expr->rhs(),
+                               p_psm);
+            } else {
+                this->expr_v_.push_back(expr.promote());
+
+                expect_expr_xs::start(true /*allow_defs*/,
+                                      true /*cxl_on_rightbvrace*/,
+                                      p_psm);
+            }
+        }
+
+        void
+        let1_xs::on_rightbrace_token(const token_type & tk,
+                                     parserstatemachine * p_psm)
+        {
+            auto self = p_psm->pop_exprstate();
+
+            auto expr = Sequence::make(this->expr_v_);
+
+            /* top env frame was established by let1_xs::start();
+             * now unwind it
+             */
+            p_psm->pop_envframe();
+
+            std::string lambda_name = Variable::gensym("let1");
+
+            rp<SymbolTable> parent_env = p_psm->top_envframe().promote();
+
+            rp<Expression> lambda
+                = Lambda::make_from_env(lambda_name,
+                                        local_env_,
+                                        nullptr /*explicit_return_td*/,
+                                        expr);
+
+            rp<Expression> result
+                = Apply::make(lambda, {this->rhs_});
+
+            p_psm->top_exprstate().on_expr(result, p_psm);
+
+            /* caller of let1_xs expects the same rightbrace '}'
+             * -- remember we pushed let1_xs to handle an embedded def-expr
+             * in a sequence
+             */
+            p_psm->on_rightbrace_token(tk);
+        }
+    } /*namespace scm*/
+} /*namespace xo*/
+
+
+/* end let1_xs.cpp */
diff --git a/xo-reader/src/reader/paren_xs.cpp b/xo-reader/src/reader/paren_xs.cpp
new file mode 100644
index 00000000..950a1547
--- /dev/null
+++ b/xo-reader/src/reader/paren_xs.cpp
@@ -0,0 +1,265 @@
+/* @file paren_xs.cpp */
+
+#include "paren_xs.hpp"
+#include "parserstatemachine.hpp"
+#include "exprstatestack.hpp"
+#include "progress_xs.hpp"
+#include "expect_expr_xs.hpp"
+#include "xo/expression/pretty_expression.hpp"
+
+namespace xo {
+    namespace scm {
+        const char *
+        parenexprstatetype_descr(parenexprstatetype x)
+        {
+            switch(x) {
+            case parenexprstatetype::invalid: return "invalid";
+            case parenexprstatetype::lparen_0: return "lparen_0";
+            case parenexprstatetype::lparen_1: return "lparen_1";
+            case parenexprstatetype::n_parenexprstatetype: break;
+            }
+
+            return "???parenexprstatetype";
+        }
+
+        paren_xs::paren_xs()
+            : exprstate(exprstatetype::parenexpr),
+              parenxs_type_{parenexprstatetype::lparen_0}
+        {}
+
+        std::unique_ptr<paren_xs>
+        paren_xs::make() {
+            return std::make_unique<paren_xs>(paren_xs());
+        }
+
+        void
+        paren_xs::start(parserstatemachine * p_psm)
+        {
+            p_psm->push_exprstate(paren_xs::make());
+            expect_expr_xs::start(p_psm);
+        }
+
+        bool
+        paren_xs::admits_rightparen() const {
+            switch (parenxs_type_) {
+            case parenexprstatetype::lparen_0:
+                /* unreachable */
+                assert(false);
+                return false;
+
+            case parenexprstatetype::lparen_1:
+                return true;
+
+            case parenexprstatetype::invalid:
+            case parenexprstatetype::n_parenexprstatetype:
+                /* unreachable */
+                assert(false);
+                return false;
+            }
+
+            return false;
+        }
+
+        bool
+        paren_xs::admits_f64() const {
+            switch (parenxs_type_) {
+            case parenexprstatetype::lparen_0:
+                return true;
+
+            case parenexprstatetype::lparen_1:
+                return false;
+
+            case parenexprstatetype::invalid:
+            case parenexprstatetype::n_parenexprstatetype:
+                /* unreachable */
+                assert(false);
+                return false;
+            }
+
+            return false;
+        }
+
+        void
+        paren_xs::on_def_token(const token_type & tk,
+                               parserstatemachine * /*p_psm*/)
+        {
+            constexpr const char * c_self_name = "paren_xs::on_def";
+
+            this->illegal_input_error(c_self_name, tk);
+        }
+
+        void
+        paren_xs::on_symbol_token(const token_type & /*tk*/,
+                                  parserstatemachine * p_psm)
+        {
+            constexpr bool c_debug_flag = true;
+            scope log(XO_DEBUG(c_debug_flag));
+
+            log && log(xtag("exstype", p_psm->top_exprstate().exs_type()));
+
+            //constexpr const char * self_name = "paren_xs::on_symbol";
+
+            /* TODO: lparen_0: treat as variable reference */
+
+            assert(false);
+        }
+
+        void
+        paren_xs::on_typedescr(TypeDescr /*td*/,
+                               parserstatemachine * /*p_psm*/)
+        {
+            assert(false);
+            return;
+        }
+
+        void
+        paren_xs::on_colon_token(const token_type & tk,
+                                 parserstatemachine * /*p_psm*/)
+        {
+            constexpr const char * c_self_name = "paren_xs::on_colon";
+
+            this->illegal_input_error(c_self_name, tk);
+        }
+
+        void
+        paren_xs::on_semicolon_token(const token_type & tk,
+                                     parserstatemachine * /*p_psm*/)
+        {
+            constexpr const char * c_self_name = "paren_xs::on_semicolon";
+
+            this->illegal_input_error(c_self_name, tk);
+        }
+
+        void
+        paren_xs::on_singleassign_token(const token_type & tk,
+                                        parserstatemachine * /*p_psm*/)
+        {
+            constexpr const char * c_self_name = "paren_xs::on_singleassign";
+
+            this->illegal_input_error(c_self_name, tk);
+        }
+
+        void
+        paren_xs::on_leftparen_token(const token_type & tk,
+                                     parserstatemachine * /*p_psm*/)
+        {
+            constexpr const char * c_self_name = "paren_xs::on_leftparen";
+
+            this->illegal_input_error(c_self_name, tk);
+        }
+
+        void
+        paren_xs::on_rightparen_token(const token_type & tk,
+                                      parserstatemachine * p_psm)
+        {
+            constexpr bool c_debug_flag = true;
+            scope log(XO_DEBUG(c_debug_flag));
+
+            constexpr const char * c_self_name = "paren_xs::on_rightparen";
+
+            if (!this->admits_rightparen())
+            {
+                this->illegal_input_error(c_self_name, tk);
+            }
+
+            if (this->parenxs_type_ == parenexprstatetype::lparen_1) {
+                rp<Expression> expr = this->gen_expr_;
+
+                std::unique_ptr<exprstate> self = p_psm->pop_exprstate();
+
+                p_psm->top_exprstate().on_expr(expr, p_psm);
+            }
+        }
+
+        void
+        paren_xs::on_i64_token(const token_type & tk,
+                               parserstatemachine * /*p_psm*/)
+        {
+            constexpr bool c_debug_flag = true;
+            scope log(XO_DEBUG(c_debug_flag));
+
+            constexpr const char * c_self_name = "paren_xs::on_i64";
+
+            this->illegal_input_error(c_self_name, tk);
+        }
+
+        void
+        paren_xs::on_f64_token(const token_type & tk,
+                               parserstatemachine * /*p_psm*/)
+        {
+            constexpr bool c_debug_flag = true;
+            scope log(XO_DEBUG(c_debug_flag));
+
+            constexpr const char * c_self_name = "paren_xs::on_f64";
+
+            this->illegal_input_error(c_self_name, tk);
+        }
+
+        void
+        paren_xs::on_expr(bp<Expression> expr,
+                          parserstatemachine * p_psm)
+        {
+            constexpr bool c_debug_flag = true;
+            scope log(XO_DEBUG(c_debug_flag));
+
+            log && log(xtag("exstype", this->exs_type_),
+                       xtag("expr", expr));
+
+            switch (this->parenxs_type_) {
+            case parenexprstatetype::lparen_0: {
+                this->parenxs_type_ = parenexprstatetype::lparen_1; /* wants on_rightparen */
+                progress_xs::start(expr.promote(), p_psm);
+
+                return;
+            }
+
+            case parenexprstatetype::lparen_1: {
+                this->gen_expr_ = expr.promote();
+
+                /* expect immediate incoming call, this time to on_rightparen() */
+                return;
+            }
+
+            default:
+                /* unreachable */
+                assert(false);
+                return;
+            }
+        } /*on_expr*/
+
+        void
+        paren_xs::on_symbol(const std::string & /*symbol_name*/,
+                            parserstatemachine * /*p_psm*/)
+        {
+            switch(this->parenxs_type_) {
+            case parenexprstatetype::lparen_0:
+            case parenexprstatetype::lparen_1:
+                /* NOT IMPLEMENTED */
+                assert(false);
+                return;
+
+            default:
+                /* unreachable */
+                assert(false);
+                return;
+            }
+        }
+
+        void
+        paren_xs::print(std::ostream & os) const {
+            os << "<paren_xs"
+               << xtag("this", (void*)this)
+                //<< xtag("type", exs_type_);
+               << xtag("parenxs_type", parenxs_type_);
+
+            if (gen_expr_)
+                os << xtag("gen_expr", gen_expr_);
+
+            os << ">";
+        }
+
+    } /*namespace scm*/
+} /*namespace xo*/
+
+
+/* end paren_xs.cpp */
diff --git a/xo-reader/src/reader/parser.cpp b/xo-reader/src/reader/parser.cpp
new file mode 100644
index 00000000..3c3f7050
--- /dev/null
+++ b/xo-reader/src/reader/parser.cpp
@@ -0,0 +1,102 @@
+/* file parser.cpp
+ *
+ * author: Roland Conybeare
+ */
+
+#include "parser.hpp"
+#include "parserstatemachine.hpp"
+#include "define_xs.hpp"
+#include "exprseq_xs.hpp"
+#include "pretty_expression.hpp"
+#include "xo/expression/DefineExpr.hpp"
+#include "xo/expression/Constant.hpp"
+#include "xo/expression/ConvertExpr.hpp"
+#include "xo/expression/GlobalSymtab.hpp"
+//#include "xo/expression/LocalSymtab.hpp"
+//#include <regex>
+#include <stdexcept>
+
+namespace xo {
+    using xo::scm::Expression;
+    using xo::scm::LocalSymtab;
+    using xo::reflect::TypeDescr;
+
+    namespace scm {
+        // ----- parser -----
+
+        parser::parser(const rp<GlobalSymtab> & toplevel_symtab, bool debug_flag)
+            : psm_{debug_flag}
+        {
+#ifdef OBSOLETE
+            /* top-level environment.  initially empty */
+            rp<SymbolTable> toplevel_env = GlobalSymtab::make_empty();
+#endif
+
+            this->psm_.env_stack_.push_envframe(toplevel_symtab);
+        }
+
+        bool
+        parser::has_incomplete_expr() const {
+            /* (don't count toplevel exprseq) */
+            return psm_.xs_stack_.size() > 1;
+        }
+
+        void
+        parser::begin_interactive_session() {
+            exprseq_xs::start(exprseqtype::toplevel_interactive, &psm_);
+        }
+
+        void
+        parser::begin_translation_unit() {
+            exprseq_xs::start(exprseqtype::toplevel_batch, &psm_);
+        }
+
+        const parser_result &
+        parser::include_token(const token_type & tk)
+        {
+            scope log(XO_DEBUG(psm_.debug_flag()), xtag("tk", tk));
+
+            if (psm_.xs_stack_.empty()) {
+                throw std::runtime_error(tostr("parser::include_token",
+                                                ": parser not expecting input"
+                                               "(call parser.begin_translation_unit()..?)",
+                                               xtag("token", tk)));
+            }
+
+            /* stack_ is non-empty */
+
+            log && log(xrefrtag("top", psm_.xs_stack_.top_exprstate()));
+
+            psm_.xs_stack_.top_exprstate().on_input(tk, &psm_);
+
+            return psm_.result_;
+        } /*include_token*/
+
+        void
+        parser::reset_result()
+        {
+            psm_.result_ = parser_result::none();
+        }
+
+        void
+        parser::reset_to_idle_toplevel()
+        {
+            psm_.xs_stack_.reset_to_toplevel();
+            psm_.env_stack_.reset_to_toplevel();
+            psm_.result_ = parser_result::none();
+        } /*discard_current_state*/
+
+        void
+        parser::print(std::ostream & os) const {
+            os << "<parser"
+               << std::endl;
+
+            psm_.xs_stack_.print(os);
+
+            os << ">" << std::endl;
+        }
+    } /*namespace scm*/
+} /*namespace xo*/
+
+
+/* end parser.cpp */
diff --git a/xo-reader/src/reader/parser_result.cpp b/xo-reader/src/reader/parser_result.cpp
new file mode 100644
index 00000000..bf47f405
--- /dev/null
+++ b/xo-reader/src/reader/parser_result.cpp
@@ -0,0 +1,44 @@
+/* file parser_result.cpp
+ *
+ * author: Roland Conybeare, Jul 2025
+ */
+
+#include "parser_result.hpp"
+
+namespace xo {
+    namespace scm {
+        parser_result::parser_result(parser_result_type type, rp<Expression> expr, const char * src_fn, std::string errmsg)
+            : result_type_{type}, result_expr_{std::move(expr)}, error_src_function_{src_fn}, error_description_{std::move(errmsg)}
+        {}
+
+        parser_result
+        parser_result::none()
+        {
+            return parser_result(parser_result_type::none,
+                                 nullptr,
+                                 nullptr,
+                                 std::string());
+        }
+
+        parser_result
+        parser_result::error(const char * error_src_function,
+                             std::string errmsg)
+        {
+            return parser_result(parser_result_type::error,
+                                 nullptr,
+                                 error_src_function,
+                                 std::move(errmsg));
+        }
+
+        parser_result
+        parser_result::expression(rp<Expression> expr)
+        {
+            return parser_result(parser_result_type::expression,
+                                 std::move(expr),
+                                 nullptr /*src_function*/,
+                                 std::string());
+        }
+    } /*namespace scm*/
+} /*namespace xo*/
+
+/* end parser_result.cpp */
diff --git a/xo-reader/src/reader/parserstatemachine.cpp b/xo-reader/src/reader/parserstatemachine.cpp
new file mode 100644
index 00000000..e27801e0
--- /dev/null
+++ b/xo-reader/src/reader/parserstatemachine.cpp
@@ -0,0 +1,203 @@
+/* file parserstatemachine.cpp
+ *
+ * author: Roland Conybeare
+ */
+
+#include "parserstatemachine.hpp"
+#include "exprstatestack.hpp"
+#include "pretty_parserstatemachine.hpp"
+#include "pretty_envframestack.hpp"
+#include "pretty_localenv.hpp"
+#include "xo/expression/pretty_expression.hpp"
+
+namespace xo {
+    using xo::scm::LocalSymtab;
+    using xo::scm::Variable;
+
+    namespace scm {
+        bp<Variable>
+        parserstatemachine::lookup_var(const std::string & x) const {
+            return Variable::from(env_stack_.lookup(x));
+        }
+
+        void
+        parserstatemachine::upsert_var(bp<Variable> x) {
+            env_stack_.upsert(x);
+        }
+
+        std::unique_ptr<exprstate>
+        parserstatemachine::pop_exprstate() {
+            return xs_stack_.pop_exprstate();
+        }
+
+        exprstate &
+        parserstatemachine::top_exprstate() {
+            return xs_stack_.top_exprstate();
+        }
+
+        const exprstate &
+        parserstatemachine::lookup_exprstate(size_t i) const {
+            return *xs_stack_[i];
+        }
+
+        void
+        parserstatemachine::push_exprstate(std::unique_ptr<exprstate> x) {
+            xs_stack_.push_exprstate(std::move(x));
+        }
+
+        bp<SymbolTable>
+        parserstatemachine::top_envframe() const {
+            return env_stack_.top_envframe();
+        }
+
+        bp<SymbolTable>
+        parserstatemachine::lookup_envframe(std::size_t i) const {
+            return env_stack_[i];
+        }
+
+        void
+        parserstatemachine::push_envframe(const rp<LocalEnv> & x) {
+            scope log(XO_DEBUG(debug_flag_));
+
+            log && log(xtag("frame", x));
+
+            env_stack_.push_envframe(x);
+        }
+
+        rp<SymbolTable>
+        parserstatemachine::pop_envframe() {
+            scope log(XO_DEBUG(debug_flag_));
+
+            return env_stack_.pop_envframe();
+        }
+
+        void
+        parserstatemachine::on_expr(bp<Expression> x)
+        {
+            scope log(XO_DEBUG(debug_flag_));
+
+            log && log(xtag("x", x),
+                       xtag("psm", this));
+
+            this->xs_stack_.top_exprstate().on_expr(x, this);
+        }
+
+        void
+        parserstatemachine::on_expr_with_semicolon(bp<Expression> x)
+        {
+            scope log(XO_DEBUG(debug_flag_));
+
+            log && log(xtag("x", x),
+                       xtag("psm", this));
+
+            assert(!this->xs_stack_.empty());
+
+            this->xs_stack_.top_exprstate().on_expr_with_semicolon(x, this);
+        }
+
+        void
+        parserstatemachine::on_symbol(const std::string & x)
+        {
+            scope log(XO_DEBUG(debug_flag_));
+
+            log && log(xtag("x", x),
+                       xtag("psm", this));
+
+            this->xs_stack_.top_exprstate().on_symbol(x, this);
+        }
+
+        void
+        parserstatemachine::on_semicolon_token(const token_type & tk)
+        {
+            scope log(XO_DEBUG(debug_flag_));
+
+            log && log(xtag("tk", tk),
+                       xtag("psm", this));
+
+            this->xs_stack_.top_exprstate().on_semicolon_token(tk, this);
+        }
+
+        void
+        parserstatemachine::on_operator_token(const token_type & tk)
+        {
+            scope log(XO_DEBUG(debug_flag_));
+
+            log && log(xtag("tk", tk),
+                       xtag("psm", this));
+
+            this->xs_stack_.top_exprstate().on_operator_token(tk, this);
+        }
+
+        void
+        parserstatemachine::on_leftbrace_token(const token_type & tk)
+        {
+            scope log(XO_DEBUG(debug_flag_));
+
+            log && log(xtag("tk", tk),
+                       xtag("psm", this));
+
+            this->xs_stack_.top_exprstate().on_leftbrace_token(tk, this);
+        }
+
+        void
+        parserstatemachine::on_rightbrace_token(const token_type & tk)
+        {
+            scope log(XO_DEBUG(debug_flag_));
+
+            log && log(xtag("tk", tk),
+                       xtag("psm", this));
+
+            this->xs_stack_.top_exprstate().on_rightbrace_token(tk, this);
+        }
+
+        void
+        parserstatemachine::on_then_token(const token_type & tk)
+        {
+            scope log(XO_DEBUG(debug_flag_));
+
+            log && log(xtag("tk", tk),
+                       xtag("psm", this));
+
+            this->xs_stack_.top_exprstate().on_then_token(tk, this);
+        }
+
+        void
+        parserstatemachine::on_else_token(const token_type & tk)
+        {
+            scope log(XO_DEBUG(debug_flag_));
+
+            log && log(xtag("tk", tk),
+                       xtag("psm", this));
+
+            this->xs_stack_.top_exprstate().on_else_token(tk, this);
+        }
+
+        void
+        parserstatemachine::on_f64_token(const token_type & tk)
+        {
+            scope log(XO_DEBUG(debug_flag_));
+
+            log && log(xtag("tk", tk),
+                       xtag("psm", this));
+
+            this->xs_stack_.top_exprstate().on_f64_token(tk, this);
+        }
+
+        void
+        parserstatemachine::on_error(const char * self_name, std::string errmsg)
+        {
+            this->result_ = parser_result::error(self_name, std::move(errmsg));
+        }
+
+        void
+        parserstatemachine::print(std::ostream & os) const {
+            os << "<psm";
+            os << xtag("stack", &xs_stack_);
+            os << xtag("env_stack", &env_stack_);
+            os << ">";
+        }
+    } /*namespace scm*/
+} /*namespace xo*/
+
+
+/* end parserstatemachine.cpp */
diff --git a/xo-reader/src/reader/pretty_parserstatemachine.cpp b/xo-reader/src/reader/pretty_parserstatemachine.cpp
new file mode 100644
index 00000000..3e03b136
--- /dev/null
+++ b/xo-reader/src/reader/pretty_parserstatemachine.cpp
@@ -0,0 +1,54 @@
+/* file pretty_parserstatemachine.cpp
+ *
+ * author: Roland Conybeare, Jul 2025
+ */
+
+#include "pretty_parserstatemachine.hpp"
+#include "pretty_exprstatestack.hpp"
+#include "pretty_envframestack.hpp"
+#include "exprstatestack.hpp"
+
+namespace xo {
+    namespace print {
+        bool
+        ppdetail<xo::scm::parserstatemachine>::print_pretty(const ppindentinfo & ppii, const xo::scm::parserstatemachine & x)
+        {
+            ppstate * pps = ppii.pps();
+
+            if (ppii.upto()) {
+                if (!pps->print_upto("<psm"))
+                    return false;
+
+                if (!pps->print_upto_tag("stack", &x.xs_stack_))
+                    return false;
+
+                if (!pps->print_upto_tag("env_stack", &x.env_stack_))
+                    return false;
+
+                return pps->print_upto(">");
+            } else {
+                pps->write("<psm");
+                pps->newline_pretty_tag(ppii.ci1(), "stack", &x.xs_stack_);
+                pps->newline_pretty_tag(ppii.ci1(), "env_stack", &x.env_stack_);
+                pps->write(">");
+
+                return false;
+            }
+        }
+
+        bool
+        ppdetail<xo::scm::parserstatemachine *>::print_pretty(const ppindentinfo & ppii, const xo::scm::parserstatemachine * x)
+        {
+            if (x) {
+                return ppdetail<xo::scm::parserstatemachine>::print_pretty(ppii, *x);
+            } else {
+                if (ppii.upto()) {
+                    return ppii.pps()->print_upto("<nullptr>");
+                } else {
+                    ppii.pps()->write("<nullptr>");
+                    return false;
+                }
+            }
+        }
+    } /*namespace print*/
+} /*namespace xo*/
diff --git a/xo-reader/src/reader/progress_xs.cpp b/xo-reader/src/reader/progress_xs.cpp
new file mode 100644
index 00000000..01cfff21
--- /dev/null
+++ b/xo-reader/src/reader/progress_xs.cpp
@@ -0,0 +1,845 @@
+/* @file progress_xs.cpp */
+
+#include "progress_xs.hpp"
+#include "apply_xs.hpp"
+#include "exprstatestack.hpp"
+#include "expect_expr_xs.hpp"
+#include "parserstatemachine.hpp"
+#include "pretty_exprstatestack.hpp"
+#include "xo/expression/AssignExpr.hpp"
+#include "xo/expression/Apply.hpp"
+#include "xo/expression/pretty_expression.hpp"
+
+namespace xo {
+    using xo::scm::Expression;
+    using xo::scm::AssignExpr;
+    using xo::scm::Variable;
+    using xo::scm::Apply;
+
+    namespace scm {
+        const char *
+        optype_descr(optype x) {
+            switch (x) {
+            case optype::invalid:
+                return "?optype";
+            case optype::op_assign:
+                return "op:=";
+            case optype::op_less:
+                return "op<";
+            case optype::op_less_equal:
+                return "op<=";
+            case optype::op_equal:
+                return "op==";
+            case optype::op_not_equal:
+                return "op!=";
+            case optype::op_great:
+                return "op>";
+            case optype::op_great_equal:
+                return "op>=";
+            case optype::op_add:
+                return "op+";
+            case optype::op_subtract:
+                return "op-";
+            case optype::op_multiply:
+                return "op*";
+            case optype::op_divide:
+                return "op/";
+            case optype::n_optype:
+                break;
+            }
+            return "???";
+        }
+
+        int
+        precedence(optype x) {
+            switch (x) {
+            case optype::invalid:
+            case optype::n_optype:
+                return 0;
+
+            case optype::op_assign:
+                return 1;
+
+            case optype::op_less:
+            case optype::op_less_equal:
+            case optype::op_equal:
+            case optype::op_not_equal:
+            case optype::op_great:
+            case optype::op_great_equal:
+                return 2;
+
+            case optype::op_add:
+            case optype::op_subtract:
+                return 3;
+
+            case optype::op_multiply:
+            case optype::op_divide:
+                return 4;
+            }
+
+            return 0;
+        }
+
+        std::unique_ptr<progress_xs>
+        progress_xs::make(rp<Expression> valex, optype op) {
+            return std::make_unique<progress_xs>(progress_xs(std::move(valex), op));
+        }
+
+        void
+        progress_xs::start(rp<Expression> valex, optype op, parserstatemachine * p_psm) {
+            p_psm->push_exprstate(progress_xs::make(valex, op));
+        }
+
+        void
+        progress_xs::start(rp<Expression> valex, parserstatemachine * p_psm) {
+            p_psm->push_exprstate(progress_xs::make(valex));
+        }
+
+        progress_xs::progress_xs(rp<Expression> valex, optype op)
+            : exprstate(exprstatetype::expr_progress),
+              lhs_{std::move(valex)},
+              op_type_{op}
+        {}
+
+        bool
+        progress_xs::admits_f64() const { return false; }
+
+        const char *
+        progress_xs::get_expect_str() const {
+            if (op_type_ == optype::invalid) {
+                return "oper|semicolon|rightparen";
+            } else {
+                return "expr|leftparen";
+            }
+        }
+
+        void
+        progress_xs::on_def_token(const token_type & tk,
+                                  parserstatemachine * p_psm)
+        {
+            constexpr const char * c_self_name = "progress_xs::on_def";
+            const char * exp = get_expect_str();
+
+            /* nothing here - admits_definition unconditionally false */
+            this->illegal_input_on_token(c_self_name, tk, exp, p_psm);
+        }
+
+        void
+        progress_xs::apply_type_error(const char * self_name,
+                                      optype op,
+                                      bp<Expression> expr1,
+                                      bp<Expression> expr2,
+                                      parserstatemachine * p_psm) const
+        {
+            std::string errmsg = tostr("incompatible argument types T1,T2 to op",
+                                       xtag("op", op),
+                                       xtag("T1", expr1->valuetype()),
+                                       xtag("T2", expr2->valuetype()));
+
+            p_psm->on_error(self_name, std::move(errmsg));
+        }
+
+        rp<Expression>
+        progress_xs::assemble_expr(parserstatemachine * p_psm) {
+            /* need to defer building Apply incase expr followed by higher-precedence operator:
+             * consider input like
+             *   3.14 + 2.0 * ...
+             */
+
+            constexpr const char * c_self_name = "progress_xs::assemble_expr";
+
+            if ((op_type_ != optype::invalid) && (rhs_.get() == nullptr)) {
+                std::string errmsg = tostr("expected expression on rhs of operator op",
+                                           xtag("lhs", lhs_),
+                                           xtag("op", op_type_));
+
+                p_psm->on_error(c_self_name, errmsg);
+            }
+
+            /* consecutive expressions not legal, e.g:
+             *   3.14 6.28
+             * but expressions surrounding an infix operators is:
+             *   3.14 / 6.28
+             */
+            switch (op_type_) {
+            case optype::invalid:
+                return this->lhs_;
+
+            case optype::op_assign:
+            {
+                bp<Variable> lhs = Variable::from(this->lhs_);
+
+                if (!lhs) {
+                    throw std::runtime_error
+                        (tostr("progress_xs::assemble_expr",
+                               " expect variable on lhs of assignment operator :=",
+                               xtag("lhs", lhs_),
+                               xtag("rhs", rhs_)));
+                }
+
+                return AssignExpr::make(lhs.promote(),
+                                        this->rhs_);
+            }
+
+            case optype::op_equal:
+                if (lhs_->valuetype()->is_i64() && rhs_->valuetype()->is_i64()) {
+                    return Apply::make_cmp_eq_i64(lhs_, rhs_);
+                } else {
+                    this->apply_type_error(c_self_name,
+                                           op_type_, lhs_, rhs_, p_psm);
+                    return nullptr;
+                }
+                break;
+
+            case optype::op_not_equal:
+                if (lhs_->valuetype()->is_i64() && rhs_->valuetype()->is_i64()) {
+                    return Apply::make_cmp_ne_i64(lhs_, rhs_);
+                } else {
+                    this->apply_type_error(c_self_name,
+                                           op_type_, lhs_, rhs_, p_psm);
+                    return nullptr;
+                }
+                break;
+
+            case optype::op_less:
+                // TODO: floating-point less-than
+
+                if (lhs_->valuetype()->is_i64() && rhs_->valuetype()->is_i64()) {
+                    return Apply::make_cmp_lt_i64(lhs_, rhs_);
+                } else {
+                    this->apply_type_error(c_self_name,
+                                           op_type_, lhs_, rhs_, p_psm);
+                    return nullptr;
+                }
+                break;
+
+            case optype::op_less_equal:
+                if (lhs_->valuetype()->is_i64() && rhs_->valuetype()->is_i64()) {
+                    return Apply::make_cmp_le_i64(lhs_, rhs_);
+                } else {
+                    this->apply_type_error(c_self_name,
+                                           op_type_, lhs_, rhs_, p_psm);
+                    return nullptr;
+                }
+                break;
+
+            case optype::op_great:
+                if (lhs_->valuetype()->is_i64() && rhs_->valuetype()->is_i64()) {
+                    return Apply::make_cmp_gt_i64(lhs_, rhs_);
+                } else {
+                    this->apply_type_error(c_self_name,
+                                           op_type_, lhs_, rhs_, p_psm);
+                    return nullptr;
+                }
+                break;
+
+            case optype::op_great_equal:
+                // TODO: upconvert integer->double
+                if (lhs_->valuetype()->is_i64() && rhs_->valuetype()->is_i64()) {
+                    return Apply::make_cmp_ge_i64(lhs_, rhs_);
+                } else {
+                    this->apply_type_error(c_self_name,
+                                           op_type_, lhs_, rhs_, p_psm);
+                    return nullptr;
+                }
+
+                assert(false);
+
+            case optype::op_add:
+                // TODO: upconvert integer->double
+                if (lhs_->valuetype()->is_i64() && rhs_->valuetype()->is_i64()) {
+                    return Apply::make_add2_i64(lhs_, rhs_);
+                } else if (lhs_->valuetype()->is_f64() && rhs_->valuetype()->is_f64()) {
+                    return Apply::make_add2_f64(lhs_, rhs_);
+                } else {
+                    this->apply_type_error(c_self_name,
+                                           op_type_, lhs_, rhs_, p_psm);
+                    return nullptr;
+                }
+                break;
+            case optype::op_subtract:
+                // TODO: upconvert integer->double
+                if (lhs_->valuetype()->is_i64() && rhs_->valuetype()->is_i64()) {
+                    return Apply::make_sub2_i64(lhs_, rhs_);
+                } else if (lhs_->valuetype()->is_f64() && rhs_->valuetype()->is_f64()) {
+                    return Apply::make_sub2_f64(lhs_, rhs_);
+                } else {
+                    this->apply_type_error(c_self_name,
+                                           op_type_, lhs_, rhs_, p_psm);
+                    return nullptr;
+                }
+                break;
+
+            case optype::op_multiply:
+                // TODO: upconvert integer->double
+                if (lhs_->valuetype()->is_i64() && rhs_->valuetype()->is_i64()) {
+                    return Apply::make_mul2_i64(lhs_, rhs_);
+                } else if (lhs_->valuetype()->is_f64() && rhs_->valuetype()->is_f64()) {
+                    return Apply::make_mul2_f64(lhs_, rhs_);
+                } else {
+                    this->apply_type_error(c_self_name,
+                                           op_type_, lhs_, rhs_, p_psm);
+                    return nullptr;
+                }
+
+                break;
+
+            case optype::op_divide:
+                // TODO: upconvert integer->double
+                if (lhs_->valuetype()->is_i64() && rhs_->valuetype()->is_i64()) {
+                    return Apply::make_div2_i64(lhs_, rhs_);
+                } else if (lhs_->valuetype()->is_f64() && rhs_->valuetype()->is_f64()) {
+                    return Apply::make_div2_f64(lhs_, rhs_);
+                } else {
+                    this->apply_type_error(c_self_name,
+                                           op_type_, lhs_, rhs_, p_psm);
+                    return nullptr;
+                }
+                break;
+
+            case optype::n_optype:
+                /* unreachable */
+                assert(false);
+                return nullptr;
+            }
+
+            return nullptr;
+        }
+
+        void
+        progress_xs::on_expr(bp<Expression> expr,
+                             parserstatemachine * p_psm)
+        {
+            scope log(XO_DEBUG(p_psm->debug_flag()), xtag("expr", expr));
+
+            /* note: previous token probably an operator,
+             *       handled from progress_xs::on_operator_token(),
+             *       which pushes expect_expr_xs::expect_rhs_expression()
+             */
+
+            constexpr const char * c_self_name = "progress_xs::on_expr";
+            const char * exp = get_expect_str();
+
+            if (lhs_) {
+                if (op_type_ == optype::invalid) {
+                    /* two consecutive expression without an operator */
+                    this->illegal_input_on_expr(c_self_name, expr, exp, p_psm);
+                }
+
+#ifdef NOT_QUITE
+                assert(result.get());
+
+                /* this expression complete.. */
+                std::unique_ptr<exprstate> self = p_psm->pop_exprstate();
+
+                /* ..but more operators could follow, so don't commit yet */
+                p_stack->push_exprstate(progress_xs::make(result));
+#endif
+
+                this->rhs_ = expr.promote();
+            } else {
+                /* control here on input like
+                 *   add(1,2)...
+                 *
+                 * add(1,2) needs to be handled inside a progress_xs
+                 * instance because may be followed by an operator:
+                 *   add(1,2) + ...
+                 */
+                this->lhs_ = expr.promote();
+            }
+        }
+
+        void
+        progress_xs::on_expr_with_semicolon(bp<Expression> expr,
+                                            parserstatemachine * p_psm)
+        {
+            scope log(XO_DEBUG(p_psm->debug_flag()));
+
+            log && log(xtag("lhs", lhs_), xtag("op", op_type_), xtag("expr", expr));
+
+            constexpr const char * c_self_name = "progress_xs::on_expr_with_semicolon";
+            const char * exp = get_expect_str();
+
+            if (op_type_ == optype::invalid) {
+                this->illegal_input_on_expr(c_self_name, expr, exp, p_psm);
+            }
+
+            this->rhs_ = expr.promote();
+
+            // FORBIDDEN, because .on_semicolon_token() destroys *this before returning
+            //   this->on_semicolon_token(token_type::semicolon(), p_psm);
+            // INSTEAD, spell out the body
+
+            rp<Expression> expr2 = this->assemble_expr(p_psm);
+
+            if (expr2) {
+                std::unique_ptr<exprstate> self = p_psm->pop_exprstate();
+
+                p_psm->on_expr_with_semicolon(expr2);
+            }
+        }
+
+        void
+        progress_xs::on_symbol_token(const token_type & /*tk*/,
+                                     parserstatemachine * /*p_psm*/)
+        {
+            /* illegal input, e.g.
+             *   foo bar
+             */
+            assert(false);
+        }
+
+        void
+        progress_xs::on_comma_token(const token_type & tk,
+                                    parserstatemachine * p_psm)
+        {
+            /* note: implementation parllels .on_semicolon_token(), .on_rightparen_token() */
+
+            scope log(XO_DEBUG(p_psm->debug_flag()));
+
+            constexpr const char * self_name = "progress::xs::on_comma_token";
+
+            auto & xs_stack = p_psm->xs_stack_;
+
+            /* stack may be something like
+             *
+             *   applyexpr
+             *   expect_expr_xs
+             *   progress_xs
+             *                  <-- comma
+             *
+             * 1. comma completes expression-in-progress
+             */
+
+            /* comma confirms stack expression */
+            rp<Expression> expr = this->assemble_expr(p_psm);
+
+            std::unique_ptr<exprstate> self = p_psm->pop_exprstate();
+
+            if (xs_stack.empty()) {
+                throw std::runtime_error(tostr(self_name,
+                                               ": expected non-empty parsing state"));
+            }
+
+            log && log(xtag("stack", &xs_stack));
+
+            p_psm->top_exprstate().on_expr(expr, p_psm);
+
+            /* now deliver comma */
+            p_psm->top_exprstate().on_comma_token(tk, p_psm);
+        }
+
+        void
+        progress_xs::on_typedescr(TypeDescr /*td*/,
+                                  parserstatemachine * /*p_psm*/)
+        {
+            /* unreachable */
+            assert(false);
+        }
+
+        void
+        progress_xs::on_colon_token(const token_type & tk,
+                                    parserstatemachine * p_psm)
+        {
+            constexpr const char * c_self_name = "progress_xs::on_colon";
+            const char * exp = get_expect_str();
+
+            this->illegal_input_on_token(c_self_name, tk, exp, p_psm);
+        }
+
+        void
+        progress_xs::on_semicolon_token(const token_type & /*tk*/,
+                                        parserstatemachine * p_psm)
+        {
+            /* note: implementation parallels .on_rightparen_token() */
+
+            scope log(XO_DEBUG(p_psm->debug_flag()));
+
+            rp<Expression> expr = this->assemble_expr(p_psm);
+
+            log && log(xtag("assembled-expr", expr));
+
+            std::unique_ptr<exprstate> self = p_psm->pop_exprstate();
+
+            p_psm->on_expr_with_semicolon(expr);
+
+            /* control here on input like:
+             *   (1.234;
+             *
+             * a. '(' sets up stack [lparen_0:expect_rhs_expression]
+             *     (see exprstate::on_leftparen())
+             * b. 1.234 pushes (in case operators) [lparen_0:expect_rhs_expression:expr_progress]
+             *     (see exprstate::on_f64())
+             * c. semicolon completes expr_progress [lparen_0:expect_rhs_expression]
+             *     deliver expresssion to expect_rhs_expression.on_expr_with_semicolon()
+             *     (see exprstate::on_expr_with_semicolon())
+             * d. expr_rhs_expression forwards expression to [lparen_0]
+             * e. lparen_0 would advance to [lparen_1],  but rejects semicolon
+             */
+        }
+
+        void
+        progress_xs::on_singleassign_token(const token_type & tk,
+                                           parserstatemachine * p_psm)
+        {
+            constexpr const char * c_self_name = "progress_xs::on_singleassign";
+            const char * exp = get_expect_str();
+
+            this->illegal_input_on_token(c_self_name, tk, exp, p_psm);
+        }
+
+        void
+        progress_xs::on_assign_token(const token_type & tk,
+                                     parserstatemachine * p_psm)
+        {
+            this->on_operator_token(tk, p_psm);
+        }
+
+        /* editor bait: on_lparen */
+        void
+        progress_xs::on_leftparen_token(const token_type & tk,
+                                        parserstatemachine * p_psm)
+        {
+            scope log(XO_DEBUG(p_psm->debug_flag()));
+
+            /* input like:
+             *   'foo(' -> expect function call.  might continue 'foo(a,b,c)'
+             *   'foo+(' -> expect parenthesized expression.  might continue 'foo+(bar/2)'
+             */
+
+            if (op_type_ == optype::invalid) {
+                /* start function call */
+                assert(rhs_.get() == nullptr);
+
+                rp<Expression> fn_expr = lhs_;
+
+                /* reset this progress_xs back to empty state;
+                 * apply_xs will be responsible for lhs_.
+                 */
+                lhs_ = nullptr;
+
+#ifdef OBSOLETE
+                /* don't unwind! want to handle input like
+                 *   f(x,y)+g(z)
+                 */
+                /* unwind this progress_xs + replace with function call */
+                std::unique_ptr<exprstate> self = p_psm->pop_exprstate();
+#endif
+
+                apply_xs::start(fn_expr, p_psm);
+
+                /* control will reenter progress_xs via .on_expr() */
+                return;
+            }
+
+            constexpr const char * c_self_name = "exprstate::on_leftparen";
+            const char * exp = get_expect_str();
+
+            this->illegal_input_on_token(c_self_name, tk, exp, p_psm);
+        }
+
+         void
+         progress_xs::on_rightparen_token(const token_type & tk,
+                                          parserstatemachine * p_psm)
+         {
+             /* note: implementation parallels .on_semicolon_token() */
+
+             scope log(XO_DEBUG(p_psm->debug_flag()));
+
+             constexpr const char * self_name = "progress_xs::on_rightparen";
+
+             auto & xs_stack = p_psm->xs_stack_;
+
+             /* stack may be something like:
+              *
+              *   lparen_0
+              *   expect_expr_xs
+              *   expr_progress
+              *                   <-- rightparen
+              *
+              * 1. rightparen completes expression-in-progress
+              * 2. rightparen must then match innermost waiting lparen_0
+              */
+
+             /* right paren confirms stack expression */
+             rp<Expression> expr = this->assemble_expr(p_psm);
+
+             log && log(xtag("expr", expr),
+                        xtag("do", "pop self + send {expr, rparen} -> parent"));
+
+             std::unique_ptr<exprstate> self = p_psm->pop_exprstate();
+
+             if (xs_stack.empty()) {
+                 throw std::runtime_error(tostr(self_name,
+                                                ": expected non-empty parsing stack"));
+             }
+
+             log && log(xtag("stack", &xs_stack));
+
+             p_psm->top_exprstate().on_expr(expr, p_psm);
+
+             /* now deliver rightparen */
+             p_psm->top_exprstate().on_rightparen_token(tk, p_psm);
+         }
+
+        void
+        progress_xs::on_then_token(const token_type & tk,
+                                   parserstatemachine * p_psm)
+        {
+            scope log(XO_DEBUG(p_psm->debug_flag()));
+
+            rp<Expression> expr = this->assemble_expr(p_psm);
+
+            log && log(xtag("assembled-expr", expr));
+
+            std::unique_ptr<exprstate> self = p_psm->pop_exprstate();
+
+            p_psm->on_expr(expr);
+            p_psm->on_then_token(tk);
+
+            /* control here on input like:
+             *
+             *   if a > b then..
+             *
+             */
+        }
+
+        void
+        progress_xs::on_else_token(const token_type & tk,
+                                   parserstatemachine * p_psm)
+        {
+            scope log(XO_DEBUG(p_psm->debug_flag()));
+
+            rp<Expression> expr = this->assemble_expr(p_psm);
+
+            log && log(xtag("assembled-expr", expr));
+
+            std::unique_ptr<exprstate> self = p_psm->pop_exprstate();
+
+            p_psm->on_expr(expr);
+            p_psm->on_else_token(tk);
+
+            /* control here on input like:
+             *
+             *   if a > b then c else..
+             */
+        }
+
+        void
+        progress_xs::on_rightbrace_token(const token_type & tk,
+                                         parserstatemachine * p_psm)
+        {
+            scope log(XO_DEBUG(p_psm->debug_flag()));
+
+            rp<Expression> expr = this->assemble_expr(p_psm);
+
+            log && log(xtag("assembled-expr", expr));
+
+            std::unique_ptr<exprstate> self = p_psm->pop_exprstate();
+
+            p_psm->on_expr(expr);
+            p_psm->on_rightbrace_token(tk);
+
+            /* control here on input like:
+             *
+             *   { n * n }
+             */
+        }
+
+        namespace {
+            optype
+            tk2op(const tokentype & tktype) {
+                switch (tktype) {
+                case tokentype::tk_assign:
+                    return optype::op_assign;
+                case tokentype::tk_plus:
+                    return optype::op_add;
+                case tokentype::tk_minus:
+                    return optype::op_subtract;
+                case tokentype::tk_star:
+                    return optype::op_multiply;
+                case tokentype::tk_slash:
+                    return optype::op_divide;
+                case tokentype::tk_cmpeq:
+                    return optype::op_equal;
+                case tokentype::tk_cmpne:
+                    return optype::op_not_equal;
+                case tokentype::tk_leftangle:
+                    return optype::op_less;
+                case tokentype::tk_lessequal:
+                    return optype::op_less_equal;
+                case tokentype::tk_rightangle:
+                    return optype::op_great;
+                case tokentype::tk_greatequal:
+                    return optype::op_great_equal;
+                default:
+                    assert(false);
+                    return optype::invalid;
+                }
+                return optype::invalid;
+            }
+        }
+
+        void
+        progress_xs::on_operator_token(const token_type & tk,
+                                       parserstatemachine * p_psm)
+        {
+            scope log(XO_DEBUG(p_psm->debug_flag()));
+
+            constexpr const char * c_self_name = "progress_xs::on_operator_token";
+
+            if (op_type_ == optype::invalid) {
+                this->op_type_ = tk2op(tk.tk_type());
+
+                /* infix operator must be followed by non-empty expression */
+                expect_expr_xs::start(p_psm);
+            } else if (rhs_) {
+                /* already have complete expression stashed.
+                 * behavior depends on operator precedence for tk with stored operator
+                 * this->op_type_
+                 */
+                optype op2 = tk2op(tk.tk_type());
+
+                if (precedence(op2) <= precedence(this->op_type_)) {
+                    /* e.g.
+                     *   6.2 * 4.9 + ...
+                     *
+                     * in stack:
+                     *   1. progress_xs lhs=6.2, op=*, rhs=4.9
+                     *
+                     * out stack
+                     *   1. progress_xs lhs=apply(*,6.2,4.9), op=+
+                     */
+
+                    /* 1. instantiate expression for *this */
+                    auto expr = this->assemble_expr(p_psm);
+
+                    /* 2. remove from stack */
+                    std::unique_ptr<exprstate> self  = p_psm->pop_exprstate();
+
+                    /* 3. replace with new progress_xs: */
+                    progress_xs::start(expr, op2, p_psm);
+
+                    /* infix operator must be followed by non-empty expression */
+                    expect_expr_xs::start(p_psm);
+                } else {
+                    /* e.g.
+                     *   6.2 + 4.9 * ...
+                     *
+                     * in stack:
+                     *   1. progress_xs lhs=6.2, op=+, rhs=4.9
+                     *
+                     * out stack:
+                     *   1. progress_xs lhs=6.2, op=+
+                     *   2. expect_rhs_expression
+                     *   3. progress_xs lhs=4.9, op=*
+                     *   4. expect_rhs_expression
+                     */
+
+                    std::unique_ptr<exprstate> self = p_psm->pop_exprstate();
+
+                    /* 1. replace with nested incomplete infix exprs */
+                    progress_xs::start(lhs_, op_type_, p_psm);
+                    expect_expr_xs::start(p_psm);
+                    progress_xs::start(rhs_, op2, p_psm);
+                    expect_expr_xs::start(p_psm);
+                }
+
+            } else {
+                throw std::runtime_error(tostr(c_self_name,
+                                               ": expected expression following operator",
+                                               xtag("tk", tk)));
+            }
+        }
+
+        void
+        progress_xs::on_bool_token(const token_type & tk,
+                                   parserstatemachine * p_psm)
+        {
+            scope log(XO_DEBUG(p_psm->debug_flag()));
+
+            constexpr const char * c_self_name = "progress_xs::on_bool_token";
+            const char * exp = get_expect_str();
+
+            if (this->op_type_ == optype::invalid) {
+                this->illegal_input_on_token(c_self_name, tk, exp, p_psm);
+            } else {
+                exprstate::on_bool_token(tk, p_psm);
+            }
+        }
+
+        void
+        progress_xs::on_i64_token(const token_type & tk,
+                                  parserstatemachine * p_psm)
+        {
+            constexpr bool c_debug_flag = true;
+            scope log(XO_DEBUG(c_debug_flag));
+
+            constexpr const char * c_self_name = "progress_xs::on_i64_token";
+            const char * exp = get_expect_str();
+
+            if (this->op_type_ == optype::invalid) {
+                this->illegal_input_on_token(c_self_name, tk, exp, p_psm);
+            } else {
+                exprstate::on_i64_token(tk, p_psm);
+            }
+        }
+
+        void
+        progress_xs::on_f64_token(const token_type & tk,
+                                  parserstatemachine * p_psm)
+        {
+            constexpr bool c_debug_flag = true;
+            scope log(XO_DEBUG(c_debug_flag));
+
+            constexpr const char * c_self_name = "progress_xs::on_f64_token";
+            const char * exp = get_expect_str();
+
+            if (this->op_type_ == optype::invalid) {
+                this->illegal_input_on_token(c_self_name, tk, exp, p_psm);
+            } else {
+                exprstate::on_f64_token(tk, p_psm);
+            }
+        }
+
+        void
+        progress_xs::print(std::ostream & os) const {
+            os << "<progress_xs"
+               << xtag("this", (void*)this)
+               << xtag("type", exs_type_);
+            if (lhs_)
+                os << xtag("lhs", lhs_);
+            if (op_type_ != optype::invalid)
+                os << xtag("op", op_type_);
+            if (rhs_)
+                os << xtag("rhs", rhs_);
+            os << ">";
+        }
+
+        bool
+        progress_xs::pretty_print(const xo::print::ppindentinfo & ppii) const
+        {
+            if (ppii.upto()) {
+                return (ppii.pps()->print_upto("<progress_xs")
+                        && (lhs_ ? ppii.pps()->print_upto(refrtag("lhs", lhs_)) : true)
+                        && (op_type_ != optype::invalid ? ppii.pps()->print_upto(refrtag("op", op_type_)) : true)
+                        && (rhs_ ? ppii.pps()->print_upto(refrtag("rhs", rhs_)) : true)
+                        && ppii.pps()->print_upto(">"));
+            } else {
+                ppii.pps()->write("<progress_xs ");
+                if (lhs_)
+                    ppii.pps()->pretty(refrtag("lhs", lhs_));
+                if (op_type_ != optype::invalid)
+                    ppii.pps()->pretty(refrtag("op", op_type_));
+                if (rhs_)
+                    ppii.pps()->pretty(refrtag("rhs", rhs_));
+                ppii.pps()->write(">");
+                return false;
+            }
+        }
+
+    } /*namespace scm*/
+} /*namespace xo*/
+
+
+/* end progress_xs.cpp */
diff --git a/xo-reader/src/reader/reader.cpp b/xo-reader/src/reader/reader.cpp
new file mode 100644
index 00000000..7bac4435
--- /dev/null
+++ b/xo-reader/src/reader/reader.cpp
@@ -0,0 +1,166 @@
+/* @file reader.cpp */
+
+#include "reader.hpp"
+
+namespace xo {
+    namespace scm {
+        reader::reader(const rp<GlobalSymtab> & toplevel_symtab, bool debug_flag) :
+            tokenizer_{debug_flag},
+            parser_{toplevel_symtab, debug_flag}
+        {}
+
+        void
+        reader::begin_interactive_session() {
+            parser_.begin_interactive_session();
+        }
+
+        reader_result
+        reader::end_interactive_session() {
+            return this->read_expr(span_type(nullptr, nullptr), true /*eof*/);
+        }
+
+        void
+        reader::begin_translation_unit() {
+            parser_.begin_translation_unit();
+        }
+
+        reader_result
+        reader::end_translation_unit() {
+            return this->read_expr(span_type(nullptr, nullptr), true /*eof*/);
+        }
+
+        reader_result
+        reader::read_expr(const span_type & input_arg, bool eof_flag)
+        {
+            scope log(XO_DEBUG(this->debug_flag()));
+
+            span_type input = input_arg;
+
+            /* input text-span consumed by this call.
+             * Always comprises some number (possibly 0)
+             * of complete tokens,  along with any leading
+             * whitespace.
+             *
+             * expr_span may also begin and end part way through
+             * distinct input lines
+             */
+            span_type expr_span = input.prefix(0ul);
+
+            while (!input.empty()) {
+                /* each loop iteration reads one token */
+
+                /* read one token from input.
+                 * tokenizer stashes one line at a time, but used_span only
+                 * reports in used_span the portion representing the first token.
+                 */
+                auto [tk, used_span, error1]
+                    = this->tokenizer_.scan(input, eof_flag);
+
+                log && log(xtag("consumed", used_span));
+                log && log(xtag("input.pre", input));
+
+                expr_span += used_span;
+
+                if (tk.is_valid()) {
+                    log && log("input_state.current_line", tokenizer_.input_state().current_line());
+
+                    /* forward just-read token to parser */
+                    auto parser_result = this->parser_.include_token(tk);
+
+                    log && log("after parser.include_token");
+                    log && log("input_state.current_line", tokenizer_.input_state().current_line());
+
+                    if (parser_result.is_expression()) {
+                        log && log(xtag("outcome", "victory!"),
+                                   xtag("expr", parser_result.result_expr()));
+
+                        rp<Expression> result_expr = parser_result.result_expr();
+
+                        this->parser_.reset_result();
+
+                        /* token completes an expression -> victory */
+                        return reader_result(parser_result.result_expr(),
+                                             expr_span, parser_.stack_size(), reader_error());
+                    } else if (parser_result.is_error()) {
+                        /* 1. parser detected error.
+                         * 2. tokenizer_.input_state().current_pos refers to position just after offending token
+                         * 3. error_pos here is 0 because error detected at token boundary
+                         */
+                        reader_error error2(parser_result.error_src_function(),
+                                            parser_result.error_description(),
+                                            tokenizer_.input_state().rewind(tk.text().size()),
+                                            0 /*error_pos*/);
+
+                        std::cout << "parser error pre-report:" << std::endl;
+                        error2.report(std::cout);
+
+                        return reader_result(nullptr, expr_span, parser_.stack_size(), error2);
+                    } else {
+                        /* token did not complete an expression
+                         * (e.g. token for '[')
+                         *
+                         * input span may contain more tokens -> iterate
+                         */
+                    }
+                } else /*invalid token*/ {
+                    if (error1.is_error()) {
+                        /* tokenizer detected an error */
+
+                        std::cout << "tokenizer error pre-report:" << std::endl;
+                        error1.report(std::cout);
+
+                        return reader_result(nullptr, expr_span, parser_.stack_size(),
+                                             reader_error(error1.src_function(),
+                                                          error1.error_description(),
+                                                          error1.input_state(),
+                                                          error1.error_pos()));
+                    } else if (used_span.size() > 0) {
+                        /* control here on reaching the last token in input line;
+                         * used_span will be the entire line
+                         */
+                    } else {
+                        /* control should not come here: invalid token with no error
+                         */
+                        assert(input.empty());
+                        break;
+                    }
+                }
+
+                input = input.after_prefix(used_span);
+            }
+
+            /* control here: either
+             * 1. input.empty (perhaps ate some whitespace,  ok)
+             * 2. missing or incomplete token (ok unless eof)
+             */
+            if (eof_flag) {
+                if (parser_.has_incomplete_expr()) {
+                    throw std::runtime_error
+                        ("reader::read_expr"
+                         ": eof reached with incomplete expression");
+                }
+
+                if (tokenizer_.has_prefix()) {
+                    throw std::runtime_error
+                        ("reader::read_expr"
+                         ": unintelligible input recognized at eof");
+                }
+            }
+
+            log && log(xtag("outcome", "noop"),
+                       xtag("parser.stack_size", parser_.stack_size()));
+
+            return reader_result(nullptr, expr_span, parser_.stack_size(), reader_error());
+        }
+
+        void
+        reader::reset_to_idle_toplevel()
+        {
+            this->tokenizer_.discard_current_line();
+            this->parser_.reset_to_idle_toplevel();
+        }
+
+    } /*namespace scm*/
+} /*namespace xo*/
+
+/* end reader.cpp */
diff --git a/xo-reader/src/reader/sequence_xs.cpp b/xo-reader/src/reader/sequence_xs.cpp
new file mode 100644
index 00000000..a7695673
--- /dev/null
+++ b/xo-reader/src/reader/sequence_xs.cpp
@@ -0,0 +1,133 @@
+/* @file sequence_xs.cpp */
+
+#include "sequence_xs.hpp"
+#include "parserstatemachine.hpp"
+#include "expect_expr_xs.hpp"
+#include "let1_xs.hpp"
+#include "xo/expression/DefineExpr.hpp"
+#include "xo/expression/Sequence.hpp"
+#include "xo/expression/pretty_expression.hpp"
+
+namespace xo {
+    using xo::scm::DefineExpr;
+
+    namespace scm {
+        std::unique_ptr<sequence_xs>
+        sequence_xs::make() {
+            return std::make_unique<sequence_xs>(sequence_xs());
+        }
+
+        void
+        sequence_xs::start(parserstatemachine * p_psm) {
+            p_psm->push_exprstate(sequence_xs::make());
+            /* want to accept anything that starts an expression,
+             * except that } ends it
+             */
+            expect_expr_xs::start(true /*allow_defs*/,
+                                  true /*cxl_on_rightbrace*/,
+                                  p_psm);
+        }
+
+        sequence_xs::sequence_xs()
+            : exprstate(exprstatetype::sequenceexpr)
+        {}
+
+        void
+        sequence_xs::on_expr(bp<Expression> expr,
+                             parserstatemachine * p_psm)
+        {
+             scope log(XO_DEBUG(p_psm->debug_flag()));
+
+             log && log(xtag("expr", expr.promote()));
+
+            /* TODO: if expr is a DefineExpr,
+             *       then need to rewrite...
+             *
+             *   ...prefix
+             *   DefineExpr(lhs_name, rhs)
+             *   rest...
+             *
+             * becomes:
+             *
+             *   /-- .outer_seq_expr_
+             *   v
+             *   Sequence(
+             *     ...prefix,
+             *
+             *           /-- .inner_lm_expr_
+             *           v
+             *     Apply(Lambda(gen999,
+             *                  [Variable(lhs_name, type(rhs))],
+             *                             /-- .expr_v_
+             *                             v
+             *                  sequencify(rest...)),
+             *           rhs))
+             *
+             * so amongst other things,
+             * helpful to have nested seequence_xs that propagates '}'
+             * instead of swallowing it.
+             */
+            bp<DefineExpr> def_expr = DefineExpr::from(expr);
+
+            if (def_expr) {
+                /** nested_start: control returns via
+                 *   .on_expr(x)
+                 *      with x something like:
+                 *    Apply(Lambda(gensym(),
+                 *                 [Variable(def_expr->lhs_name(),
+                 *                           def_expr->valuetype())],
+                 *                 body...))
+                 *  followed immediately by
+                 *   .on_rightbrace_token()
+                 **/
+                let1_xs::start(def_expr->lhs_name(),
+                               def_expr->rhs(),
+                               p_psm);
+            } else {
+                this->expr_v_.push_back(expr.promote());
+
+                expect_expr_xs::start(true /*allow_defs*/,
+                                      true /*cxl_on_rightbrace*/,
+                                      p_psm);
+            }
+        }
+
+        void
+        sequence_xs::on_expr_with_semicolon(bp<Expression> expr,
+                                            parserstatemachine * p_psm)
+        {
+            /* sequence continues until right brace */
+            this->on_expr(expr, p_psm);
+        }
+
+        void
+        sequence_xs::on_rightbrace_token(const token_type & /*tk*/,
+                                         parserstatemachine * p_psm)
+        {
+            auto self = p_psm->pop_exprstate();
+
+            /* make sequence from expressions seen at this level,
+             * and report it to parent
+             */
+            auto expr = Sequence::make(this->expr_v_);
+
+            p_psm->top_exprstate().on_expr(expr, p_psm);
+        }
+
+        void
+        sequence_xs::print(std::ostream & os) const {
+            os << "<sequence_xs" << xtag("expr_v.size", expr_v_.size()) << ">";
+        }
+
+        bool
+        sequence_xs::pretty_print(const xo::print::ppindentinfo & ppii) const
+        {
+            return ppii.pps()->pretty_struct(ppii, "sequence_xs",
+                                             xrefrtag("expr_v.size", expr_v_.size()));
+        }
+
+    } /*namespace scm*/
+} /*namespace xo*/
+
+
+/* end sequence_xs.cpp */
diff --git a/xo-reader/utest/CMakeLists.txt b/xo-reader/utest/CMakeLists.txt
new file mode 100644
index 00000000..1f876ca1
--- /dev/null
+++ b/xo-reader/utest/CMakeLists.txt
@@ -0,0 +1,17 @@
+# xo-reader/utest/CMakeLists.txt
+
+set(UTEST_EXE utest.reader)
+set(UTEST_SRCS
+    reader_utest_main.cpp
+    parser.test.cpp
+    reader.test.cpp)
+
+if (ENABLE_TESTING)
+    xo_add_utest_executable(${UTEST_EXE} ${UTEST_SRCS})
+    xo_self_dependency(${UTEST_EXE} xo_reader)
+    #xo_dependency(${UTEST_EXE} xo_ratio)
+    #xo_dependency(${UTEST_EXE} xo_reflectutil)
+    xo_external_target_dependency(${UTEST_EXE} Catch2 Catch2::Catch2)
+endif()
+
+# end CMakeLists.txt
diff --git a/xo-reader/utest/parser.test.cpp b/xo-reader/utest/parser.test.cpp
new file mode 100644
index 00000000..3d6f3fac
--- /dev/null
+++ b/xo-reader/utest/parser.test.cpp
@@ -0,0 +1,305 @@
+/* file parser.test.cpp
+ *
+ * author: Roland Conybeare
+ */
+
+#include "xo/reader/parser.hpp"
+#include "xo/reader/define_xs.hpp"
+#include <catch2/catch.hpp>
+
+namespace xo {
+    using parser_type = xo::scm::parser;
+    using token_type = parser_type::token_type;
+    using xo::scm::GlobalSymtab;
+    using xo::scm::exprstatetype;
+    using xo::scm::define_xs;
+    using xo::scm::defexprstatetype;
+    using std::cerr;
+    using std::endl;
+
+    //using xo::scm::Expression;
+
+    namespace ut {
+        TEST_CASE("parser", "[parser]") {
+            for (std::size_t i_tc = 0; i_tc < 2; ++i_tc) {
+                constexpr bool c_debug_flag = true;
+
+                rp<GlobalSymtab> toplevel_symtab = GlobalSymtab::make_empty();
+
+                parser_type parser(toplevel_symtab, c_debug_flag);
+
+                scope log(XO_DEBUG(c_debug_flag), xtag("i_tc", i_tc));
+
+                parser.begin_translation_unit();
+
+                REQUIRE(parser.stack_size() == 1);
+                REQUIRE(parser.i_exstype(0)
+                        == exprstatetype::expect_toplevel_expression_sequence);
+
+                /* input:
+                 *   def
+                 */
+                {
+                    auto r1 = parser.include_token(token_type::def());
+
+                    REQUIRE(r1.is_none());
+                    REQUIRE(r1.result_expr().get() == nullptr);
+                    REQUIRE(r1.error_src_function() == nullptr);
+                    REQUIRE(r1.error_description().empty());
+
+                    /* stack should be:
+                     *
+                     *   expect_toplevel_expression_sequence
+                     *   def_1
+                     *   expect_symbol
+                     */
+                    CHECK(parser.stack_size() == 3);
+                    if (parser.stack_size() > 0)
+                        CHECK(parser.i_exstype(0) == exprstatetype::expect_symbol);
+                    if (parser.stack_size() > 1) {
+                        CHECK(parser.i_exstype(1) == exprstatetype::defexpr);
+                        REQUIRE(define_xs::from(parser.i_exstate(1)) != nullptr);
+                        CHECK(define_xs::from(parser.i_exstate(1))->defxs_type() == defexprstatetype::def_1);
+                    }
+                    if (parser.stack_size() > 2)
+                        CHECK(parser.i_exstype(2)
+                              == exprstatetype::expect_toplevel_expression_sequence);
+                }
+
+                /* input:
+                 *   def foo
+                 *      ^   ^
+                 *      0   1
+                 */
+                {
+                    auto r2 = parser.include_token(token_type::symbol_token("foo"));
+
+                    cerr << "parser state after [def foo]" << endl;
+                    cerr << parser << endl;
+
+                    REQUIRE(r2.is_none());
+                    REQUIRE(r2.result_expr().get() == nullptr);
+                    REQUIRE(r2.error_src_function() == nullptr);
+                    REQUIRE(r2.error_description().empty());
+
+                    /* stack should be:
+                     *
+                     *   expect_toplevel_expression_sequence
+                     *   def_1
+                     */
+                    CHECK(parser.stack_size() == 2);
+                    if (parser.stack_size() > 0) {
+                        CHECK(parser.i_exstype(0) == exprstatetype::defexpr);
+                        REQUIRE(define_xs::from(parser.i_exstate(0)) != nullptr);
+                        CHECK(define_xs::from(parser.i_exstate(0))->defxs_type() == defexprstatetype::def_2);
+                    }
+                    if (parser.stack_size() > 1)
+                        CHECK(parser.i_exstype(1)
+                              == exprstatetype::expect_toplevel_expression_sequence);
+
+                }
+
+                if (i_tc == 0) {
+                    ;
+                } else if (i_tc == 1) {
+                    /* input:
+                     *   def foo :
+                     *          ^ ^
+                     *          0 1
+                     */
+                    {
+                        auto r3 = parser.include_token(token_type::colon());
+
+                        cerr << "parser state after [def foo :]" << endl;
+                        cerr << parser << endl;
+
+                        REQUIRE(r3.is_none());
+                        REQUIRE(r3.result_expr().get() == nullptr);
+                        REQUIRE(r3.error_src_function() == nullptr);
+                        REQUIRE(r3.error_description().empty());
+
+                        /* stack should be:
+                         *
+                         *   expect_toplevel_expression_sequence
+                         *   def_3
+                         *   expect_symbol
+                         */
+                        CHECK(parser.stack_size() == 3);
+                        if (parser.stack_size() > 0)
+                            CHECK(parser.i_exstype(0) == exprstatetype::expect_type);
+                        if (parser.stack_size() > 1) {
+                            CHECK(parser.i_exstype(1) == exprstatetype::defexpr);
+                            REQUIRE(define_xs::from(parser.i_exstate(1)) != nullptr);
+                            CHECK(define_xs::from(parser.i_exstate(1))->defxs_type() == defexprstatetype::def_3);
+                        }
+                        if (parser.stack_size() > 2)
+                            CHECK(parser.i_exstype(2)
+                                  == exprstatetype::expect_toplevel_expression_sequence);
+                    }
+
+                    /* input:
+                     *   def foo : f64
+                     *            ^   ^
+                     *            0   1
+                     */
+                    {
+                        auto r4 = parser.include_token(token_type::symbol_token("f64"));
+
+                        cerr << "parser state after [def foo : f64]" << endl;
+                        cerr << parser << endl;
+
+                        REQUIRE(r4.is_none());
+                        REQUIRE(r4.result_expr().get() == nullptr);
+                        REQUIRE(r4.error_src_function() == nullptr);
+                        REQUIRE(r4.error_description().empty());
+
+                        CHECK(parser.stack_size() == 2);
+
+                        /* stack should be:
+                         *
+                         *   expect_toplevel_expression_sequence
+                         *   def_4
+                         */
+                        CHECK(parser.stack_size() == 2);
+                        if (parser.stack_size() > 0) {
+                            CHECK(parser.i_exstype(0) == exprstatetype::defexpr);
+                            REQUIRE(define_xs::from(parser.i_exstate(0)) != nullptr);
+                            CHECK(define_xs::from(parser.i_exstate(0))->defxs_type() == defexprstatetype::def_4);
+                        }
+                        if (parser.stack_size() > 1)
+                            CHECK(parser.i_exstype(1)
+                                  == exprstatetype::expect_toplevel_expression_sequence);
+
+                        /* expecting either:
+                         *   = rhs-expression
+                         *   new-expression
+                         */
+                    }
+                }
+
+                /* input:
+                 *
+                 * i_tc==0:
+                 *   def foo =
+                 *          ^ ^
+                 *          0 1
+                 *
+                 * i_tc==1:
+                 *   def foo : f64 =
+                 *                ^ ^
+                 *                0 1
+                 */
+                {
+                    auto r5 = parser.include_token(token_type::singleassign());
+
+                    cerr << "parser state after [def foo : f64 =]" << endl;
+                    cerr << parser << endl;
+
+                    REQUIRE(r5.is_none());
+                    REQUIRE(r5.result_expr().get() == nullptr);
+                    REQUIRE(r5.error_src_function() == nullptr);
+                    REQUIRE(r5.error_description().empty());
+
+                    CHECK(parser.stack_size() == 3);
+
+                    /* stack should be
+                     *
+                     *   expect_toplevel_expression_sequence
+                     *   def_5
+                     *   expect_expression
+                     */
+                    CHECK(parser.stack_size() == 3);
+                    if (parser.stack_size() > 0)
+                        CHECK(parser.i_exstype(0) == exprstatetype::expect_rhs_expression);
+                    if (parser.stack_size() > 1) {
+                        CHECK(parser.i_exstype(1) == exprstatetype::defexpr);
+                        REQUIRE(define_xs::from(parser.i_exstate(1)) != nullptr);
+                        CHECK(define_xs::from(parser.i_exstate(1))->defxs_type() == defexprstatetype::def_5);
+                    }
+                    if (parser.stack_size() > 2)
+                        CHECK(parser.i_exstype(2)
+                              == exprstatetype::expect_toplevel_expression_sequence);
+                }
+
+                /* input:
+                 *
+                 * i_tc==0:
+                 *   def foo = 3.14159265
+                 *            ^          ^
+                 *            0          1
+                 *
+                 * i_tc==1:
+                 *   def foo : f64 = 3.14159265
+                 *                  ^          ^
+                 *                  0          1
+                 */
+                {
+                    auto r6 = parser.include_token(token_type::f64_token("3.14159265"));
+
+                    cerr << "parser state after [def foo : f64 = 3.14159265]" << endl;
+                    cerr << parser << endl;
+
+                    REQUIRE(r6.is_none());
+                    REQUIRE(r6.result_expr().get() == nullptr);
+                    REQUIRE(r6.error_src_function() == nullptr);
+                    REQUIRE(r6.error_description().empty());
+
+                    /* stack should be
+                     *
+                     *   expect_toplevel_expression_sequence
+                     */
+                    CHECK(parser.stack_size() == 4);
+                    if (parser.stack_size() > 0)
+                        CHECK(parser.i_exstype(0) == exprstatetype::expr_progress);
+                    if (parser.stack_size() > 1)
+                        CHECK(parser.i_exstype(1) == exprstatetype::expect_rhs_expression);
+                    if (parser.stack_size() > 2) {
+                        CHECK(parser.i_exstype(2) == exprstatetype::defexpr);
+                        REQUIRE(define_xs::from(parser.i_exstate(2)) != nullptr);
+                        CHECK(define_xs::from(parser.i_exstate(2))->defxs_type() == defexprstatetype::def_5);
+                    }
+                    if (parser.stack_size() > 3)
+                        CHECK(parser.i_exstype(3)
+                              == exprstatetype::expect_toplevel_expression_sequence);
+                }
+
+                /* input:
+                 *
+                 * i_tc==0:
+                 *   def foo = 3.14159265 ;
+                 *                       ^ ^
+                 *                       0 1
+                 *
+                 * i_tc==1:
+                 *   def foo : f64 = 3.14159265 ;
+                 *                             ^ ^
+                 *                             0 1
+                 */
+                {
+                    auto r7 = parser.include_token(token_type::semicolon());
+
+                    cerr << "parser state after [def foo : f64 = 3.14159265;]" << endl;
+                    cerr << parser << endl;
+
+                    REQUIRE(r7.is_expression());
+                    REQUIRE(r7.result_expr().get() != nullptr);
+                    REQUIRE(r7.error_src_function() == nullptr);
+                    REQUIRE(r7.error_description().empty());
+
+                    CHECK(parser.stack_size() == 1);
+
+                    /* stack should be
+                     *
+                     *   expect_toplevel_expression_sequence
+                     */
+                    CHECK(parser.stack_size() == 1);
+                    if (parser.stack_size() > 0)
+                        CHECK(parser.i_exstype(0)
+                              == exprstatetype::expect_toplevel_expression_sequence);
+                }
+            }
+        } /*TEST_CASE(parser)*/
+    } /*namespace ut*/
+} /*namespace xo*/
+
+/* end parser.test.cpp */
diff --git a/xo-reader/utest/reader.test.cpp b/xo-reader/utest/reader.test.cpp
new file mode 100644
index 00000000..0bccf3b3
--- /dev/null
+++ b/xo-reader/utest/reader.test.cpp
@@ -0,0 +1,73 @@
+/* @file reader.test.cpp */
+
+#include "xo/reader/reader.hpp"
+#include <catch2/catch.hpp>
+
+namespace xo {
+    using xo::scm::reader;
+    using xo::scm::GlobalSymtab;
+
+    namespace ut {
+        namespace {
+            struct test_case {
+                const char * text_;
+            };
+
+            std::vector<test_case> s_testcase_v = {
+                {"def foo : f64 = 3.14159265;"},
+                {"def foo : f64 = (3.14159265);"},
+                {"def foo = 2.0 * 3.141569265;"},
+                {"def foo = lambda (x : f64) 3.1415965;"},
+                {"def foo = lambda (x : f64, y : f64) 3.1415965;"},
+                {"def foo = lambda (x : f64) x;"},
+                {"def foo = lambda (x : f64) { def y = x * x; y; };"},
+                {"add(1,2);"},
+            };
+        }
+
+        TEST_CASE("reader", "[reader]") {
+            constexpr bool c_debug_flag = true;
+            scope log(XO_DEBUG(c_debug_flag), xtag("utest", "reader"));
+
+            for (std::size_t i_tc = 0; i_tc < s_testcase_v.size(); ++i_tc) {
+                const test_case & tc = s_testcase_v[i_tc];
+
+                rp<GlobalSymtab> toplevel_symtab = GlobalSymtab::make_empty();
+
+                reader rdr(toplevel_symtab, c_debug_flag);
+
+                scope log(XO_ENTER2(always, c_debug_flag, "reader.testcase"),
+                           xtag("i_tc", i_tc));
+
+                rdr.begin_translation_unit();
+
+                try {
+                    auto input
+                        = reader::span_type::from_cstr(tc.text_);
+                    auto rr
+                        = rdr.read_expr(input, true /*eof*/);
+
+                    REQUIRE(rr.expr_.get());
+
+                    log && log(xtag("expr", rr.expr_));
+
+#ifdef OBSOLETE // input not consumed until next line presented
+                    input = input.after_prefix(rr.rem_);
+
+                    log && log(xtag("post.input", input));
+#endif
+
+                    //REQUIRE(input.empty());
+                } catch (std::exception & ex) {
+                    log && log(ex.what());
+
+                    INFO(ex.what());
+
+                    REQUIRE(false);
+                }
+            }
+        }
+    } /*namespace ut*/
+} /*namespace xo*/
+
+/* end reader.test.cpp */
diff --git a/xo-reader/utest/reader_utest_main.cpp b/xo-reader/utest/reader_utest_main.cpp
new file mode 100644
index 00000000..d1013151
--- /dev/null
+++ b/xo-reader/utest/reader_utest_main.cpp
@@ -0,0 +1,6 @@
+/* file parser_utest_main.cpp */
+
+#define CATCH_CONFIG_MAIN
+#include <catch2/catch.hpp>
+
+/* end parser_utest_main.cpp */