#pragma once
#include <string>
#include <vector>
/**
* @file Types.h
* @brief Shared enum types and core data types used by the runtime.
*/
/** @brief Runtime object categories known by the object manager. */
enum OBJECT_TYPE {
/** A database snapshot grouping relations and tuples. */
MULTIGROUP,
/** A relation object backed by physical storage. */
RELATION,
/** An attribute object (schema metadata). */
ATTRIBUTE,
/** A transaction object. */
TRANSACTION,
/**
* A relation whose tuples are produced on demand by a generator function
* 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 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 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 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>`.
*
* 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.
*/
BRANCH_TREE
};
/** @brief Operations that may be supported by an object type. */
enum METHOD {
/** Opens an object and creates an authorized handle. */
OPEN,
/** Closes a previously opened handle. */
CLOSE,
/** Parses through a secondary namespace. */
PARSE,
/** Performs security checks. */
SECURITY
};
/** @brief Claims granted to an authenticated connection. */
enum AUTH_CLAIM {
/** Permission to read object state. */
READ,
/** Permission to mutate object state. */
WRITE
};
/** @brief Authentication strategies supported by the permissions layer. */
enum AUTH_METHOD {
/** Certificate-based authentication. */
CERTIFICATE,
/** Plain-text authentication. */
PLAIN_TEXT
};
namespace nt {
/** @brief A single named value in a tuple, produced by the cursor layer. */
struct Attribute {
std::string name;
std::string value;
};
/**
* @brief A single row of data streamed lazily from the cursor layer.
*
* Follows the Volcano pull model: callers repeatedly call Next() to consume
* one attribute at a time. Returns nullptr when all attributes are exhausted.
*/
class Tuple {
public:
explicit Tuple(std::vector<Attribute> attributes) : attributes_(std::move(attributes)) {
}
/** @brief Returns the next attribute, or nullptr when exhausted. */
const Attribute* Next() {
if (position_ < attributes_.size())
return &attributes_[position_++];
return nullptr;
}
void Reset() {
position_ = 0;
}
/** @brief Direct read-only access to all attributes without affecting position. */
const std::vector<Attribute>& attrs() const {
return attributes_;
}
private:
std::vector<Attribute> attributes_;
size_t position_ = 0;
};
} // namespace nt
