Got most of the new memory architecture roughed out.

src/c/payloads/cons.h

@@ -0,0 +1,32 @@
+/**
+ *  payloads/cons.h
+ *
+ *  A cons cell.
+ *
+ *  (c) 2026 Simon Brooke <simon@journeyman.cc>
+ *  Licensed under GPL version 2.0, or, at your option, any later version.
+ */
+
+#ifndef __psse_payloads_cons_h
+#define __psse_payloads_cons_h
+
+#include "memory/pointer.h"
+
+/**
+ * An ordinary cons cell:
+ */
+#define CONSTAG     "CNS"
+
+/**
+ * @brief A cons cell.
+ * 
+ */
+struct cons_payload {
+  /** Contents of the Address Register, naturally. */
+    struct pso_pointer car;
+  /** Contents of the Decrement Register, naturally. */
+    struct pso_pointer cdr;
+};
+
+
+#endif

src/c/payloads/exception.h

@@ -0,0 +1,28 @@
+/**
+ *  payloads/exception.h
+ *
+ *  An exception; required three pointers, so use object of size class 3.
+ *
+ *  (c) 2026 Simon Brooke <simon@journeyman.cc>
+ *  Licensed under GPL version 2.0, or, at your option, any later version.
+ */
+
+#ifndef __psse_payloads_exception_h
+#define __psse_payloads_exception_h
+
+#include "memory/pointer.h"
+
+/**
+ * @brief An exception; required three pointers, so use object of size class 3.
+ */
+struct exception_payload {
+  /** @brief the exception message. Expected to be a string, but may be anything printable. */
+    struct pso_pointer message;
+  /** @brief the stack frame at which the exception was thrown. */
+    struct pso_pointer stack;
+    /** @brief the cause; expected to be another exception, or (usually) `nil`. */
+    struct cons_pointer cause;
+};
+
+
+#endif

src/c/payloads/free.h

@@ -0,0 +1,30 @@
+/**
+ *  payloads/free.h
+ *
+ *  An unassigned object, on a freelist; may be of any size class.
+ *
+ *  (c) 2026 Simon Brooke <simon@journeyman.cc>
+ *  Licensed under GPL version 2.0, or, at your option, any later version.
+ */
+
+#ifndef __psse_payloads_free_h
+#define __psse_payloads_free_h
+
+#include "memory/pointer.h"
+
+/**
+ * @brief Tag for an unassigned object; may be of any size class.
+ */
+#define FREETAG     "FRE"
+
+/**
+ * @brief An unassigned object, on a freelist; may be of any size class.
+ * 
+ */
+struct free_payload {
+  /** the next object on the free list for my size class */
+    struct pso_pointer next;
+};
+
+
+#endif

src/c/payloads/function.h

@@ -0,0 +1,47 @@
+/**
+ *  payloads/function.h
+ *
+ *  an ordinary Lisp function - one whose arguments are pre-evaluated.
+ *
+ *  (c) 2026 Simon Brooke <simon@journeyman.cc>
+ *  Licensed under GPL version 2.0, or, at your option, any later version.
+ */
+
+#ifndef __psse_payloads_function_h
+#define __psse_payloads_function_h
+
+#include "memory/pointer.h"
+
+/**
+ * @brief Tag for an ordinary Lisp function - one whose arguments are pre-evaluated.
+ * \see LAMBDATAG for interpretable functions.
+ * \see SPECIALTAG for functions whose arguments are not pre-evaluated.
+ */
+#define FUNCTIONTAG "FUN"
+
+/**
+ * @brief Payload of a function cell.
+ * `source` points to the source from which the function was compiled, or NIL
+ * if it is a primitive.
+ * `executable` points to a function which takes a pointer to a stack frame
+ * (representing its stack frame) and a cons pointer (representing its
+ * environment) as arguments and returns a cons pointer (representing its
+ * result).
+ */
+struct function_payload {
+    /**
+     * pointer to metadata (e.g. the source from which the function was compiled).
+     */
+    struct cons_pointer meta;
+    /**  pointer to a function which takes a cons pointer (representing
+     * its argument list) and a cons pointer (representing its environment) and a
+     * stack frame (representing the previous stack frame) as arguments and returns
+     * a cons pointer (representing its result).
+     * \todo check this documentation is current!
+     */
+    struct cons_pointer ( *executable ) ( struct stack_frame *,
+                                          struct cons_pointer,
+                                          struct cons_pointer );
+};
+
+#endif

src/c/payloads/integer.h

@@ -0,0 +1,27 @@
+/**
+ *  payloads/integer.h
+ *
+ *  An integer.
+ *
+ *  (c) 2026 Simon Brooke <simon@journeyman.cc>
+ *  Licensed under GPL version 2.0, or, at your option, any later version.
+ */
+
+#ifndef __psse_payloads_integer_h
+#define __psse_payloads_integer_h
+
+#include <stdint.h>
+
+/**
+ * @brief An integer .
+ *
+ * Integers can in principal store a 128 bit value, but in practice we'll start
+ * promoting them to bignums when they pass the 64 bit barrier. However, that's
+ * in the Lisp layer, not the substrate.
+ */
+struct integer_payload {
+    int128_t value;
+};
+
+
+#endif

src/c/payloads/keyword.h

@@ -0,0 +1,24 @@
+/**
+ *  payloads/keyword.h
+ *
+ *  A keyword cell.
+ *
+ *  (c) 2026 Simon Brooke <simon@journeyman.cc>
+ *  Licensed under GPL version 2.0, or, at your option, any later version.
+ */
+
+#ifndef __psse_payloads_keyword_h
+#define __psse_payloads_keyword_h
+
+#include "memory/pointer.h"
+
+/**
+ * Tag for a keyword - an interned, self-evaluating string.
+ */
+#define KEYTAG	    "KEY"
+
+/* TODO: for now, Keyword shares a payload with String, but this may change.
+ * Strings are of indefinite length, but keywords are really not, and might
+ * fit into any size class. */
+
+#endif

src/c/payloads/lambda.h

@@ -0,0 +1,32 @@
+/**
+ *  payloads/lambda.h
+ *
+ *  A lambda cell.
+ *
+ *  (c) 2026 Simon Brooke <simon@journeyman.cc>
+ *  Licensed under GPL version 2.0, or, at your option, any later version.
+ */
+
+#ifndef __psse_payloads_lambda_h
+#define __psse_payloads_lambda_h
+
+#include "memory/pointer.h"
+
+/**
+ * @brief Tag for lambda cell. Lambdas are the interpretable (source) versions of functions.
+ * \see FUNCTIONTAG.
+ */
+#define LAMBDATAG  "LMD"
+
+/**
+ * @brief payload for lambda and nlambda cells.
+ */
+struct lambda_payload {
+    /** the arument list */
+    struct pso_pointer args;
+    /** the body of the function to be applied to the arguments. */
+    struct pso_pointer body;
+};
+
+
+#endif

src/c/payloads/nlambda.h

@@ -0,0 +1,22 @@
+/**
+ *  payloads/nlambda.h
+ *
+ *  A nlambda cell.
+ *
+ *  (c) 2026 Simon Brooke <simon@journeyman.cc>
+ *  Licensed under GPL version 2.0, or, at your option, any later version.
+ */
+
+#ifndef __psse_payloads_nlambda_h
+#define __psse_payloads_nlambda_h
+
+#include "memory/pointer.h"
+
+/**
+ * An ordinary nlambda cell:
+ */
+#define CONSTAG     "CNS"
+
+/* nlambda shares a payload with lambda */
+
+#endif

src/c/payloads/read_stream.h

@@ -0,0 +1,34 @@
+/**
+ *  payloads/read_stream.h
+ *
+ *  A read stream.
+ *
+ *  (c) 2026 Simon Brooke <simon@journeyman.cc>
+ *  Licensed under GPL version 2.0, or, at your option, any later version.
+ */
+
+#ifndef __psse_payloads_read_stream_h
+#define __psse_payloads_read_stream_h
+
+#include <stdio.h>
+
+#include "memory/pointer.h"
+
+/**
+ * An open read stream.
+ */
+#define READTAG     "REA"
+
+/**
+ * payload of a read or write stream cell.
+ */
+struct stream_payload {
+    /** the stream to read from or write to. */
+    URL_FILE *stream;
+    /** metadata on the stream (e.g. its file attributes if a file, its HTTP
+     * headers if a URL, etc). Expected to be an association, or nil. Not yet
+     * implemented. */
+    struct cons_pointer meta;
+};
+
+#endif

src/c/payloads/special.h

@@ -0,0 +1,43 @@
+/**
+ *  payloads/special.h
+ *
+ *  A special form.
+ *
+ *  (c) 2026 Simon Brooke <simon@journeyman.cc>
+ *  Licensed under GPL version 2.0, or, at your option, any later version.
+ */
+
+#ifndef __psse_payloads_special_h
+#define __psse_payloads_special_h
+
+#include "memory/pointer.h"
+
+/**
+ * A special form - one whose arguments are not pre-evaluated but passed as
+ * provided.
+ * \see NLAMBDATAG.
+ */
+#define SPECIALTAG  "SFM"
+
+/**
+ * @brief Payload of a special form cell. 
+ *
+ * Currently identical to the payload of a function cell.
+ * \see function_payload
+ */
+struct special_payload {
+    /**
+     * pointer to the source from which the special form was compiled, or NIL
+     * if it is a primitive.
+     */
+    struct cons_pointer meta;
+    /**  pointer to a function which takes a cons pointer (representing
+     * its argument list) and a cons pointer (representing its environment) and a
+     * stack frame (representing the previous stack frame) as arguments and returns
+     * a cons pointer (representing its result). */
+    struct cons_pointer ( *executable ) ( struct stack_frame *,
+                                          struct cons_pointer,
+                                          struct cons_pointer );
+};
+
+#endif

src/c/payloads/stack_frame.h

@@ -0,0 +1,38 @@
+/**
+ *  payloads/stack_frame.h
+ *
+ *  A stack frame.
+ *
+ *  (c) 2026 Simon Brooke <simon@journeyman.cc>
+ *  Licensed under GPL version 2.0, or, at your option, any later version.
+ */
+
+#ifndef __psse_payloads_stack_frame_h
+#define __psse_payloads_stack_frame_h
+#include <stdint.h>
+
+#include "memory/pointer.h"
+/*
+ * number of arguments stored in a stack frame
+ */
+#define args_in_frame 8
+
+/**
+ * A stack frame.
+ */
+struct stack_frame_payload {
+    /** the previous frame. */
+    struct cons_pointer previous;
+    /** first 8 arument bindings. */
+    struct cons_pointer arg[args_in_frame];
+    /** list of any further argument bindings. */
+    struct cons_pointer more;
+    /** the function to be called. */
+    struct cons_pointer function;
+    /** the number of arguments provided. */
+    int args;
+    /** the depth of the stack below this frame */
+    int depth;
+};
+
+#endif

src/c/payloads/string.h

@@ -0,0 +1,42 @@
+/**
+ *  payloads/string.h
+ *
+ *  A string cell.
+ *
+ *  (c) 2026 Simon Brooke <simon@journeyman.cc>
+ *  Licensed under GPL version 2.0, or, at your option, any later version.
+ */
+
+#ifndef __psse_payloads_string_h
+#define __psse_payloads_string_h
+/*
+ * wide characters
+ */
+#include <wchar.h>
+#include <wctype.h>
+
+#include "memory/pointer.h"
+
+
+/**
+ * @brief Tag for string of characters, organised as a linked list.
+ */
+#define STRINGTAG   "STR"
+
+/**
+ * @brief payload of a string cell. 
+ *
+ * At least at first, only one UTF character will be stored in each cell. At 
+ * present the payload of a symbol or keyword cell is identical
+ * to the payload of a string cell.
+ */
+struct string_payload {
+    /** the actual character stored in this cell */
+    wint_t character;
+    /** a hash of the string value, computed at store time. */
+    uint32_t hash;
+    /** the remainder of the string following this character. */
+    struct cons_pointer cdr;
+};
+
+#endif

src/c/payloads/symbol.h

@@ -0,0 +1,25 @@
+/**
+ *  payloads/symbol.h
+ *
+ *  A symbol cell.
+ *
+ *  (c) 2026 Simon Brooke <simon@journeyman.cc>
+ *  Licensed under GPL version 2.0, or, at your option, any later version.
+ */
+
+#ifndef __psse_payloads_symbol_h
+#define __psse_payloads_symbol_h
+
+#include "memory/pointer.h"
+
+
+/**
+ * Tag for a symbol: just like a keyword except not self-evaluating.
+ */
+#define SYMBOLTAG   "SYM"
+
+/* TODO: for now, Symbol shares a payload with String, but this may change.
+ * Strings are of indefinite length, but symbols are really not, and might
+ * fit into any size class. */
+
+#endif

src/c/payloads/time.h

@@ -0,0 +1,29 @@
+/**
+ *  payloads/cons.h
+ *
+ *  A cons cell.
+ *
+ *  (c) 2026 Simon Brooke <simon@journeyman.cc>
+ *  Licensed under GPL version 2.0, or, at your option, any later version.
+ */
+
+#ifndef __psse_payloads_cons_h
+#define __psse_payloads_cons_h
+
+#include "memory/pointer.h"
+
+/**
+ * @brief Tag for a time stamp.
+ */
+#define TIMETAG     "TIME"
+
+/**
+ * The payload of a time cell: an unsigned 128 bit value representing micro-
+ * seconds since the estimated date of the Big Bang (actually, for
+ * convenience, 14Bn years before 1st Jan 1970 (the UNIX epoch))
+ */
+struct time_payload {
+    unsigned __int128 value;
+};
+
+#endif

src/c/payloads/vector_pointer.h

@@ -0,0 +1,39 @@
+/**
+ *  payloads/vector_pointer.h
+ *
+ *  A pointer to an object in vector space.
+ *
+ *  (c) 2026 Simon Brooke <simon@journeyman.cc>
+ *  Licensed under GPL version 2.0, or, at your option, any later version.
+ */
+
+#ifndef __psse_payloads_vector_pointer_h
+#define __psse_payloads_vector_pointer_h
+
+#include "memory/pointer.h"
+
+/**
+ * A pointer to an object in vector space.
+ */
+#define VECTORPOINTTAG  "VSP"
+
+/**
+ * @brief payload of a vector pointer cell.
+ */
+struct vectorp_payload {
+    /** the tag of the vector-space object. NOTE that the vector space object
+     * should itself have the identical tag. */
+    union {
+        /** the tag (type) of the vector-space object this cell
+         * points to, considered as bytes. */
+        char bytes[TAGLENGTH];
+        /** the tag considered as a number */
+        uint32_t value;
+    } tag;
+    /** unused padding to word-align the address */
+    uint32_t padding;
+    /** the address of the actual vector space object */
+    void *address;
+};
+
+#endif

src/c/payloads/write_stream.h

@@ -0,0 +1,21 @@
+/**
+ *  payloads/write_stream.h
+ *
+ *  A write_stream cell.
+ *
+ *  (c) 2026 Simon Brooke <simon@journeyman.cc>
+ *  Licensed under GPL version 2.0, or, at your option, any later version.
+ */
+
+#ifndef __psse_payloads_write_stream_h
+#define __psse_payloads_write_stream_h
+
+#include "memory/pointer.h"
+
+/**
+ * @brief Tag for an open write stream.
+ */
+#define WRITETAG    "WRT"
+
+/* write stream shares a payload with /see read_streem.h */
+#endif