# 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`.