Add native RND and ASC functions

Implement bounded random integers with lazy clock seeding and add ASC as the inverse of CHR. Cover dispatch, validation, deterministic LCG output, UTF-8 round trips, function reference, and the breakout tutorial.

Closes #16.

Co-authored-by: andrew <andrew@aklabs.net>

.gitea/workflows/ci.yaml

@@ -26,14 +26,42 @@ jobs:
           # skipped for the same reason: our CMakeLists declares akerror::akerror
           # first and libakstdlib guards on if(NOT TARGET ...).
           submodules: true
+      # moreutils is load-bearing, not incidental: it supplies errno(1), which
+      # deps/libakerror/scripts/generrno.sh shells out to at build time to
+      # generate its errno name table and to stamp AKERR_LAST_ERRNO_VALUE into
+      # the generated akerror.h.
+      #
+      # Its absence does not fail the build, which is what made this expensive to
+      # find. The script prints "errno: command not found" twice, emits an empty
+      # akerr_init_errno() so no errno ever gets a name, and substitutes an empty
+      # AKERR_LAST_ERRNO_VALUE -- so every code in libakerror's reserved band
+      # collapses from (134 + n) to ( + n), i.e. to n. AKERR_OUTOFBOUNDS is
+      # (AKERR_LAST_ERRNO_VALUE + 2), so it becomes literally 2, and ERR(2)
+      # answers "Out Of Bounds Error" where ENOENT's "No such file or directory"
+      # belongs. That is the docs_examples failure at docs/15-error-codes.md:105
+      # that this job carried on every run since #2.
       - name: dependencies
         run: |
           sudo apt-get update -y
-          sudo apt-get install -y cmake gcc
+          sudo apt-get install -y cmake gcc moreutils
+      # --parallel 2 rather than a bare --parallel, and that bound is measured
+      # rather than cautious. All five jobs in this file say runs-on:
+      # ubuntu-latest and land on the same runner, so a bare --parallel asks for
+      # nproc compilers *per job* and the runner is handed five times that at
+      # once. Run #30 never showed it because akgl_build and coverage were still
+      # dying early; run #31 was the first push on which all five did real work
+      # simultaneously, and the sanitizers job went from a 55-second link phase
+      # to a 14-minute one -- individual `Linking C executable` steps taking two
+      # minutes each, starting at the exact second akgl_build began its SDL tree
+      # -- before the runner's Docker daemon fell over outright and took the job
+      # with it. That is memory exhaustion, and the only lever on it is the
+      # number of concurrent compiler and linker processes. Applied at all four
+      # build sites for the same reason; mutation_test drives its own builds
+      # through the harness and is not bounded here.
       - name: build
         run: |
           cmake -S . -B build
-          cmake --build build --parallel
+          cmake --build build --parallel 2
       # The suite is 78 cases: 41 golden files byte-compared against the Go
       # reference's own corpus (checked in at tests/reference/, see its README),
       # 9 local golden cases for verbs the reference never implemented, 25 unit
@@ -74,7 +102,7 @@ jobs:
       - name: dependencies
         run: |
           sudo apt-get update -y
-          sudo apt-get install -y cmake gcc
+          sudo apt-get install -y cmake gcc moreutils
       # The whole suite under ASan and UBSan, golden files included. This is the
       # gate libakstdlib's TODO.md section 1 calls its highest-value missing item
       # -- worth having here from the start, because this library is all fixed
@@ -84,7 +112,7 @@ jobs:
           cmake -S . -B build-asan \
             -DAKBASIC_SANITIZE=ON \
             -DCMAKE_BUILD_TYPE=Debug
-          cmake --build build-asan --parallel
+          cmake --build build-asan --parallel 2
           ctest --test-dir build-asan --output-on-failure
       - run: echo "🍏 This job's status is ${{ job.status }}."
 
@@ -98,7 +126,7 @@ jobs:
       - name: dependencies
         run: |
           sudo apt-get update -y
-          sudo apt-get install -y cmake gcc gcovr
+          sudo apt-get install -y cmake gcc gcovr moreutils
       # The gate is a ratchet, not a target: src/ sits at 94.6% of lines and
       # 98.6% of functions, so 90 fails on a real regression (a test deleted, or
       # new untested code added) without tripping over rounding.
@@ -124,7 +152,7 @@ jobs:
           cmake -S . -B build-coverage \
             -DAKBASIC_COVERAGE=ON \
             -DCMAKE_BUILD_TYPE=Debug
-          cmake --build build-coverage --parallel
+          cmake --build build-coverage --parallel 2
           ctest --test-dir build-coverage --output-on-failure
           mkdir -p build-coverage/coverage
           gcovr --root . --filter 'src/.*' \
@@ -134,9 +162,21 @@ jobs:
             --fail-under-line 90
       # Publish even when the threshold gate fails, so the uncovered lines are
       # visible -- each one is a missing test.
+      #
+      # @v3, not @v4, and that is Gitea rather than preference. @v4 bundles
+      # @actions/artifact v2, whose isGhes() treats any GITHUB_SERVER_URL that is
+      # not github.com as GitHub Enterprise Server and refuses outright:
+      # "GHESNotSupportedError: @actions/artifact v2.0.0+, upload-artifact@v4+
+      # and download-artifact@v4+ are not currently supported on GHES". @v3 uses
+      # the older artifact API, which this forge does implement.
+      #
+      # This never showed before because the step had nothing to upload: gcovr
+      # was never reached, so the step warned "No files were found" and passed.
+      # Fixing the suite is what first gave it a real file to refuse. Same class
+      # of accommodation as the annotate_only flag on the junit reporter above.
       - name: upload coverage reports
         if: always()
-        uses: actions/upload-artifact@v4
+        uses: actions/upload-artifact@v3
         with:
           name: code-coverage
           path: build-coverage/coverage/
@@ -161,22 +201,56 @@ jobs:
       # embedded it takes a find_package path instead, so our CMakeLists declares
       # those targets first and needs the submodules present. Six of them, none
       # recursive. Filed upstream as libakgl API-gap item 5.
+      #
+      # Eight, not six: deps/libccd and deps/clay were missing and are not
+      # optional. libakgl does not add_subdirectory either of them -- their own
+      # CMakeLists are unusable as subprojects -- it compiles them into itself,
+      # so nothing declares them and configuration dies late with "File
+      # deps/libccd/src/ccd/config.h.cmake.in does not exist" at
+      # deps/libakgl/CMakeLists.txt:282. clay is the same shape one step later:
+      # deps/clay/clay.h is on the include path and installed.
+      #
+      # deps/tg is a real submodule of libakgl and is deliberately not here --
+      # nothing in its CMakeLists references it. libakerror and libakstdlib are
+      # skipped for the reason the checkout note above gives.
       - name: libakgl dependencies
         run: |
           git -C deps/libakgl submodule update --init \
             deps/SDL deps/SDL_image deps/SDL_mixer deps/SDL_ttf \
-            deps/jansson deps/semver
+            deps/jansson deps/semver deps/libccd deps/clay
       # libfreetype-dev and libharfbuzz-dev are load-bearing, not incidental.
       # SDL_ttf prefers the system copies -- it reports "Using system freetype
       # library" and links libfreetype.so.6 -- and without them it would reach
       # for deps/SDL_ttf/external/freetype, which the checkout above
       # deliberately does not clone. Installing two dev packages is much cheaper
       # than cloning freetype and harfbuzz.
+      #
+      # The X11 dev packages are the other half, and they are what this job has
+      # been dying on since run #2 -- it has never once been green. SDL_X11 and
+      # its nine sub-options default ON on Linux, and CheckX11() in
+      # deps/SDL/cmake/sdlchecks.cmake calls SDL_missing_dependency() -- a hard
+      # CMake error, not a downgrade -- for any one of them whose header is
+      # absent. The runner image carries libx11-dev (X11/XKBlib.h resolved) but
+      # none of the extension packages, so configuration stopped at the first of
+      # the nine: "Couldn't find dependency package for XCURSOR".
+      #
+      # Turning the missing ones OFF would also configure, and is the wrong
+      # answer: the point of this job is that an AKGL build is a real SDL
+      # program, and a real SDL program on Linux builds the X11 backend. The
+      # tests still run headless under SDL_VIDEODRIVER=dummy -- see the env block
+      # below -- so this buys a faithful build, not a display.
+      #
+      # The list is SDL's own, from deps/SDL/docs/README-linux.md, reduced to the
+      # X11 entries: the audio, Wayland, KMSDRM and Vulkan backends all degrade
+      # to "not found" and skip themselves rather than erroring, so they cost
+      # nothing to leave out. Nine packages, all in noble.
       - name: dependencies
         run: |
           sudo apt-get update -y
-          sudo apt-get install -y cmake gcc g++ pkg-config \
-            libfreetype-dev libharfbuzz-dev
+          sudo apt-get install -y cmake gcc g++ pkg-config moreutils \
+            libfreetype-dev libharfbuzz-dev \
+            libx11-dev libxext-dev libxcursor-dev libxi-dev libxfixes-dev \
+            libxrandr-dev libxss-dev libxtst-dev libxkbcommon-dev
       # The akgl-backed half: the text sink and the graphics, audio and input
       # backends, the standalone SDL frontend, and the two suites that drive
       # them against a real software renderer and read the pixels back.
@@ -194,7 +268,7 @@ jobs: