From af8759a9c1d965a3220024d1857aea219d62d898 Mon Sep 17 00:00:00 2001 From: Marcos Magueta Date: Mon, 18 May 2026 12:50:25 -0300 Subject: Branching and object registry rework (#11) --- include/Types.h | 73 +++++++++++++++++++++++++++++++++++++++++++-------------- 1 file changed, 55 insertions(+), 18 deletions(-) (limited to 'include/Types.h') 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/, 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/, reads target_hash, and uses + * that hash to open the snapshot at /system/snapshots/. 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/; the resolver consults + * /system/sessions//branches/ first and falls back to the global + * /system/branches/ when there is no override. + */ + SESSION, + /** + * The content-addressed Merkle 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///` into `/system/snapshots//`. * - * @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/`. 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. */ -- cgit v1.2.3