diff options
Diffstat (limited to 'CLAUDE.md')
| -rw-r--r-- | CLAUDE.md | 79 |
1 files changed, 0 insertions, 79 deletions
diff --git a/CLAUDE.md b/CLAUDE.md deleted file mode 100644 index 077be25..0000000 --- a/CLAUDE.md +++ /dev/null @@ -1,79 +0,0 @@ -# CLAUDE.md - -This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository. - -## Project Overview - -Relational NT is an experimental database kernel inspired by the Windows NT kernel's object-management model. It applies explicit object management principles to database internals — relations, tuples, transactions, namespaces, permissions, cursors, and handles are first-class runtime-managed objects rather than isolated subsystems. - -The project is early-stage and intentionally skeletal: headers define the architecture and document design constraints; implementations are stubs filling out as the runtime shape solidifies. - -## Build Commands - -**Windows (NMake):** -``` -nmake /f Makefile windows -nmake /f Makefile clean -``` - -**Unix/Linux/macOS:** -``` -make unix -make macos -make clean -``` - -Requires C++17. Output binary: `RNT.exe` (Windows) or `RNT` (Unix). No external dependencies beyond the standard library. - -**Generate documentation:** -``` -doxygen Doxyfile -``` -Output lands in `docs/generated/html`. Docs are auto-published to GitHub Pages on pushes to `master`. - -## Architecture - -### Manager Pipeline - -The system is organized as a set of single-responsibility managers. The canonical **open-handle workflow** chains them in this order: - -``` -HandlerManager::Open() - → ObjectManager::Find() — locate object by logical path - → PermissionsManager::Access() — capability check (READ/WRITE vs security descriptor) - → IdentityManager::CanOpen() — verify object supports OPEN method - → LifecycleManager::Contention() — detect mutability conflicts - → LifecycleManager::Monitor() — pin the object for the handle's lifetime -``` - -`HandlerManager::Close()` reverses monitoring and deallocates the handle. This explicit separation means permissions policy can evolve without touching object lookup or lifecycle code. - -### Manager Responsibilities - -| Manager | Role | -|---|---| -| `ObjectManager` | Central registry — stores and finds all objects (Multigroup, Relation, Tuple, Attribute, Transaction) by logical path; tracks ref counts, handle counts, security descriptors | -| `PermissionsManager` | Capability-based auth — `Firewall()` validates connection auth method; `Access()` checks object-level claims (READ/WRITE) | -| `IdentityManager` | Lifecycle eligibility — `CanOpen()` / `CanClose()` confirm an object's method set supports the requested operation | -| `LifecycleManager` | Monitoring, pinning, and contention — `Monitor()` / `Unmonitor()` track open handles; `Contention()` prevents conflicting concurrent writes; blocks history pruning when cursors hold snapshots | -| `HandlerManager` | Orchestrates the full open/close workflow above; owns handle allocation | -| `CursorManager` | Volcano-style pull iterator over storage — abstracts pagination, snapshot pinning, prefetch, buffering, and scan boundary enforcement (commit boundaries, logical branches) | -| `NamespaceReferenceManager` | Logical path mapping and namespace isolation — supports private branch shadowing (`/user_a/refs/branch/abc`); enforces all-or-nothing batching for multi-reference atomic updates | -| `VM` | Logic execution boundary — hosts two cores: **Tarski** (FOL relational calculus via Volcano iterators, guaranteed termination) and **Karuta** (SOL WAM-based higher-order logic, may not terminate); pull-based and lazy | - -### Shared Types (`include/Types.h`) - -- `OBJECT_TYPE`: `MULTIGROUP`, `RELATION`, `TUPLE`, `ATTRIBUTE`, `TRANSACTION` -- `METHOD`: `OPEN`, `CLOSE`, `PARSE`, `SECURITY` -- `AUTH_CLAIM`: `READ`, `WRITE` -- `AUTH_METHOD`: `CERTIFICATE`, `PLAIN_TEXT` - -### Entry Points - -- `include/NT.h` — main public API include -- `include/Runtime.h` — top-level `NT` facade (`IsRunning()`, `SimulateEntryCall()`) -- `src/NT.cpp` — console harness used for manual testing - -### Headers as Design Record - -Because implementations are intentionally minimal, the **header files are the authoritative design record**. Doxygen comments in headers explain invariants, constraints, and design rationale. Read the header before touching any `.cpp`. |