Ensifer/README.md

ENSIFER 0.1.20
============

A small Model-T-style enfilade in C with an S7 Scheme FFI.

The point of this package is to make the core mechanism usable without making
the reader learn the whole Xanadu/Green vocabulary first.

Start with [`doc/USAGE`](doc/USAGE) if you are new to the code. Read
[`doc/ensifer.7`](doc/ensifer.7) for the conceptual overview,
[`doc/enfilade.3`](doc/enfilade.3) for the C API, and
[`doc/enfilade-s7.7`](doc/enfilade-s7.7) for Scheme. The tumbler primitive is
documented separately in [`doc/tumbler.3`](doc/tumbler.3) and
[`doc/tumbler-s7.7`](doc/tumbler-s7.7).

THE IDEA
--------

An enfilade is a tree indexed by tumbler fields.

A tumbler is written as a dotted sequence of unsigned integers:

    1.2.3

Putting:

    1.2.3 -> datum

creates the path automatically:

    root
      |
      +-- 1
           |
           +-- 2
                |
                +-- 3 -> datum

A key may have both a datum and a child enfilade.  Lookup returns the datum at
that key first, then the contents of the child.

That is the whole basic mechanism.

QUICK START
-----------

Configure and build the library, S7 module, and bundled REPL:

    ./configure
    make

Start the REPL; the enfilade functions are initialized automatically:

    ./build/bin/logan

Install under `/usr/local` (or set another prefix with
`./configure --prefix=/path`):

    make install

Stage an install for packaging or inspection with `DESTDIR`:

    make install DESTDIR=/tmp/ensifer-stage

Run the regression suite with `make check`. `make clean` removes generated
build files; `make distclean` also removes configure output.

To load the shared module into another S7 host:

    (load "./build/lib/enfilade.so" (inlet 'init_func 'init_enfilade_s7))
RANGE
-----
-----

`enfilade-get-range` is deliberately unchanged from the existing interface.
It ranges over the numeric keys at the current enfilade level:

    (enfilade-get-range e 1 3)

The bounds are inclusive.  A negative end means "through the end".

This is not a dotted-tumbler interval expression.

TUMBLERS
--------

The C layer now has a small standalone tumbler module.

The public primitive is:

    #include "tumbler.h"

It supplies:

    tumbler_parse()
    tumbler_free()
    tumbler_to_string()
    tumbler_compare()
    tumbler_add()
    tumbler_subtract_strong()
    tumbler_subtract_weak()
    tumbler_subtract()

The implementation uses `uint64_t` fields.  It therefore has finite field
width even though the historical Xanadu representation used arbitrary-precision
Humbers.  This is a deliberate boundary for the small reference build.

Whole-tumbler comparison follows the infinitesimal-style ordering used by the
small tumbler implementations derived from Udanax work.  Missing fields are
compared as zero, giving the familiar ordering:

    1 < 1.1 < 1.1.1 < 1.2 < 2

Arithmetic implements Xanadu's non-commutative tumbler addition and the strong,
weak, and generalized difference operations.  See `doc/tumbler.3` for the
rules and examples.

C DATA LIFETIME
---------------

`enfilade_t` never owns the datum pointer supplied to `put_enfilade()`.

For ordinary C code:

    int value = 42;
    enfilade_t *e = create_enfilade();

    put_enfilade(e, "1.2.3", &value);
    /* use e while value remains alive */

    destroy_enfilade(e);

    /* value may now go out of scope */

The enfilade frees its own index nodes, never the datum pointed to by an entry.
The caller therefore controls datum lifetime.

For S7, the datum is an S7 object.  The c-object mark function walks every
stored datum and marks it, so Scheme objects remain reachable through the
enfilade and are reclaimed normally after the enfilade itself is released.

C API
-----

Create and destroy:

    enfilade_t *create_enfilade(void);
    void destroy_enfilade(enfilade_t *enf);

Store and remove:

    enf_result_t put_enfilade(enfilade_t *enf,
                              const char *tumbler,
                              void *datum);

    enf_result_t remove_enfilade(enfilade_t *enf,
                                 const char *tumbler);

Lookup:

    void *getXtumbler_enfilade(enfilade_t *enf, const char *tumbler);

    enf_result_t getXtumbler_values_enfilade(enfilade_t *enf,
                                             const char *tumbler,
                                             void ***items,
                                             size_t *count);

Range:

    enf_result_t getXrange_values_enfilade(enfilade_t *enf,
                                           int64_t start,
                                           int64_t end,
                                           void ***items,
                                           size_t *count);

Traversal:

    void enfilade_visit_data(enfilade_t *enf,
                             enfilade_datum_visitor visitor,
                             void *context);

The two array-returning functions allocate the array of datum pointers.  The
caller frees that array with `free()`.  The datum pointers are not transferred
or freed.

`remove_enfilade()` removes only the datum at the exact final key.  If that key
also names a child enfilade, the child remains.  Empty intermediate children
are pruned.

S7 FFI
------

The module defines the c-object type `<enfilade>` and these Scheme functions:

    make-enfilade
    enfilade-put-data
    enfilade-remove
    enfilade-get-by-tumbler
    enfilade-get-range
    tumbler-compare
    tumbler-add
    tumbler-subtract

Load the shared object with:

    (load "./build/lib/enfilade.so" (inlet 'init_func 'init_enfilade_s7))

The module does not depend on S7's `s7_repl()` startup path or on `cload.scm`.
`build/bin/logan` is a direct small REPL with the module initialized at startup.

ERRORS
------

Malformed tumbler text and a missing intermediate child are reported by the
S7 binding as `TumblerAddressException`.

A valid tumbler whose final key has no datum or child returns `()`.

`enfilade-remove` returns `#t` when a datum was removed and `#f` when the exact
final datum was not present.  Malformed addresses and allocation failures are
errors.

REFERENCE IMPLEMENTATION
-------------------------

The immediate behavioral reference for the tree is:

    https://raw.githubusercontent.com/enkiv2/ds-lib/refs/heads/master/Enfilade.py

The corresponding core operations are its `putValue`, `getByTumbler`, `get`,
and `getRange` behavior.

The C implementation deliberately keeps `range` as the existing numeric-key
range operation.  Its ordered merge visits a key shared by a datum and child
once; the Python reference can visit that key twice because it combines the two
key lists before sorting.

WHAT THIS IS
------------

This is a small reference enfilade: a useful, inspectable building block for
other structures that need a tumbler-addressed index.

It is not the complete Udanax Green backend.  The larger literature adds
specialized enfilades and machinery for WIDs, DISPs, rearrangement, versioning,
spans, virtual copies, persistent structures, and the Green storage model.
Those are layers to build on top of this primitive, not requirements for using
this one.

For a ZigZag cell catalogue, the natural simple pattern is:

    cell ID (tumbler)
          |
          v
       enfilade
          |
          v
       cell pointer

New cells can therefore be catalogued under newly allocated tumbler IDs without
making the catalogue itself understand the cell's internal representation.

FILES
-----

inc/              public C and S7 headers
src/              C implementation, bundled S7, and REPL sources
test/             C regression tests and S7 smoke test
scheme/           Scheme reference implementation and S7 support scripts
doc/              usage guide and groff manual pages
configure          compiler and shared-library capability checks
Makefile           build, check, install, uninstall, and clean targets

TESTS
-----

Run all regression checks with:

    make check

This builds and runs the pure C tests and the bundled S7 smoke test.

HISTORICAL REFERENCES
---------------------

* Xanadu Hypertext Documents, especially "Enfilade Theory" and "Tumblers and
  Humbers":
  https://sentido-labs.com/en/library/201904240732/Xanadu%20Hypertext%20Documents.html

* Udanax Green / Xanalogical Structure overview:
  https://www.mprove.de/visionreality/media/xuDation.html

* Ted Nelson and Udanax developer archive:
  https://www.xanadu.com.au/mail/udanax/

* Jeff Rush's `xanalogica.tumbler`, a Python implementation explicitly derived
  from Udanax Green's C source:
  https://pypi.org/project/xanalogica.tumbler/