Branching and object registry rework (#11)

1 files changed, 55 insertions, 18 deletions

diff --git a/include/Types.h b/include/Types.h
index f7eadff..edf4297 100644
--- a/include/Types.h
+++ b/include/Types.h
@@ -20,37 +20,74 @@ enum OBJECT_TYPE {
     TRANSACTION,
     /**
      * A relation whose tuples are produced on demand by a generator function
-     * rather than read from physical storage. Cardinality may be finite (e.g.
-     * a projected stored relation) or AlephZero (e.g. the eq builtin). The
-     * object_type for this label must be an ephemeral_object_type.
+     * rather than read from physical storage. Behaves like a RELATION in every
+     * other respect: owns a `merkle_root`, has mutable schema, composes into its
+     * multigroup's hash, and may be opened, scanned, and pinned through the
+     * same handle pipeline.
+     *
+     * The generator receives unsigned-int paginators (offset, limit) plus any
+     * bound argument values written by an upstream JOIN, and yields tuples.
+     * Cardinality may be finite (e.g. a projection over a stored relation) or
+     * AlephZero (e.g. the eq builtin). The object_type for this label must be
+     * an ephemeral_object_type.
+     *
+     * Tracked as a distinct label — rather than collapsed into RELATION —
+     * for three reasons:
+     *   1. Sakura distinguishes generated relations as a separate subclass at
+     *      the wire layer, even though the runtime treats them uniformly.
+     *   2. They have no physical tuple-storage backend; reads always go
+     *      through the generator.
+     *   3. They carry a dependency list of base relation paths they are
+     *      defined atop of. This drives structural reference counting (a
+     *      base relation cannot be GC'd while an ephemeral relation depends
+     *      on it) and is the foundation for attribute-level provenance
+     *      tracking added later.
      */
     EPHEMERAL_RELATION,
     /**
-     * A named mutable reference to a multigroup state, analogous to a git
-     * branch. A BRANCH object carries an opaque payload (serialized multigroup
-     * bytes) that the caller — in practice Sakura — deserializes on open.
+     * A named mutable reference to a multigroup snapshot, analogous to a git
+     * branch. A BRANCH object carries a `target_hash` — the merkle_root of
+     * the snapshot it currently points at — and nothing else.
      *
      * Branch objects are the entry point for database connections: a client
-     * opens a handle to /system/branches/<name>, reads the payload bytes to
-     * reconstruct the multigroup in memory, and holds the handle for the
-     * duration of the session.
+     * opens a handle to /system/branches/<name>, reads target_hash, and uses
+     * that hash to open the snapshot at /system/snapshots/<hash>. Multigroup
+     * state is reconstructed by walking the content-addressed graph from
+     * that snapshot, not by deserializing bytes attached to the branch.
      *
      * The `exclusive` flag on the object_type should be set to true so that
      * LifecycleManager::Contention serializes concurrent writers.
      */
     BRANCH,
     /**
-     * A named query plan stored in the object registry. A VIEW object carries
-     * the serialized plan definition and the multigroup hash at definition time.
-     * No handles to physical storage are kept open in the VIEW object itself.
-     * Each time the view is opened, fresh relation handles and cursors are
-     * created for the duration of that execution, then released on close.
+     * A per-connection runtime context. SESSION objects own the
+     * connection_context pointer (auth metadata, etc.) and a map of per-session
+     * branch overrides: `branch_name -> target_hash`. Overrides let one
+     * connection observe a different snapshot for a branch than the global
+     * HEAD without affecting other sessions.
+     *
+     * Sessions are identified by random 256-bit hex hashes minted at
+     * rnt_session_open. The hash is opaque to the caller and is the only
+     * handle for subsequent rnt_session_* calls. SESSION objects live at
+     * /system/sessions/<hash>; the resolver consults
+     * /system/sessions/<hash>/branches/<n> first and falls back to the global
+     * /system/branches/<n> when there is no override.
+     */
+    SESSION,
+    /**
+     * The content-addressed Merkle<string> root of a branch's multigroup map.
+     * A BRANCH points at a BRANCH_TREE via target_hash; the tree maps
+     * `mg_name -> mg_hash` and is paged at resolve time to translate
+     * `/system/branches/<n>/<mg>/<rel>` into `/system/snapshots/<mg_hash>/<rel>`.
      *
-     * @todo Implement ObjectManager::View, rnt_register_view, and the
-     *       open-view path in HandlerManager. Views are reserved in the type
-     *       system but have no runtime support yet.
+     * BRANCH_TREE objects live at `/system/branch_trees/<hash>`. They are
+     * immutable (disposable=false, exclusive=false) and pinned by the BRANCH
+     * objects that reference them; the mgs they reference are in turn pinned
+     * by the BRANCH_TREE via LifecycleManager::CascadeBranchTree at GC time.
+     * The same blob is reused across all branches and session overrides
+     * that share a tip.
      */
-    VIEW
+    BRANCH_TREE
 };
 
 /** @brief Operations that may be supported by an object type. */