### Run foldb Server

Source: https://github.com/jeremytregunna/foldb/blob/master/README.md

Command to start the foldb server. Requires a configuration file path as an argument.

```bash
foldb serve --config config.json
```

--------------------------------

### Start FoldDB Development Server

Source: https://github.com/jeremytregunna/foldb/blob/master/CONTRIBUTING.md

Command to set up and run a single-node FoldDB development server, specifying a storage directory.

```bash
mkdir -p /tmp/foldb-dev
./zig-out/bin/foldb serve --storage-dir /tmp/foldb-dev

```

--------------------------------

### foldb Server Configuration Example

Source: https://context7.com/jeremytregunna/foldb/llms.txt

Example JSON configuration for the foldb server. Covers storage, networking, clustering, Raft timing, S3 integration, and authentication settings. Note that S3 and auth fields are optional.

```jsonc
{
  "storage_dir": "/var/lib/foldb",      // required for production
  "node_id": 1,                         // unique integer per node in the cluster
  "partition_count": 1,                 // data partitions; fixed at startup
  "listen_addr": "0.0.0.0",
  "listen_port": 7432,

  // Cluster peers (empty = single-node mode)
  "peers": [
    {"id": 2, "addr": "10.0.0.2:7432"},
    {"id": 3, "addr": "10.0.0.3:7432"}
  ],

  // Raft timing
  "max_epoch_size": 10000,
  "election_timeout_min_ms": 150,
  "election_timeout_max_ms": 300,
  "heartbeat_interval_ms": 50,

  // S3 — all five fields required together or omitted entirely.
  // Without S3: snapshots disabled, log grows unbounded (dev only).
  "s3_endpoint": "http://127.0.0.1:9000",
  "s3_bucket": "foldb",
  "s3_access_key": "minio",
  "s3_secret_key": "minioadmin",
  "s3_region": "us-east-1",

  // Auth — omit to run in open mode (no credentials required)
  "auth_secret": "<base64 from foldb gen-secret>",
  "users": [
    {"name": "alice", "token": "<token from foldb add-user>"}
  ]
}
```

--------------------------------

### Observability Metrics Queries

Source: https://context7.com/jeremytregunna/foldb/llms.txt

Examples of how to query histogram percentiles and increment counters for observability metrics within the system.

```zig
// Histogram percentile query (exponential buckets, 1µs to ∞)
const p99_ns = raft_metrics.replication_latency.percentile(99);

// Counter example (saturation semantics — never overflows)
gateway_metrics.queries_registered.increment();
gateway_metrics.recon_retries.incrementBy(retry_count);
```

--------------------------------

### Full Connection Lifecycle Example

Source: https://github.com/jeremytregunna/foldb/blob/master/docs/wire-protocol.md

Illustrates a complete client-server interaction sequence using the FoldDB wire protocol, from TLS negotiation to connection closure, including query registration, execution, and subscription.

```protobuf
C→S  FDBT              (TLS request)
S→C  Y
     [TLS handshake]

S→C  Hello  stream=0
C→S  Auth   stream=0  Token
S→C  AuthOk stream=0

C→S  RegisterQuery  stream=1
S→C  Registered     stream=1  FINAL

C→S  Execute   stream=2
S→C  RowsBegin stream=2  MORE
S→C  RowsBatch stream=2  MORE
S→C  ExecOk    stream=2  FINAL

C→S  Subscribe   stream=3  scope=filtered  filter=[by_name "accounts"]
S→C  SubscribeAck stream=3  MORE           (resolved: "accounts"→42)
S→C  CdcEvent     stream=3
S→C  CdcEvent     stream=3
C→S  AckCdc       stream=3
C→S  Unsubscribe  stream=3  FINAL
S→C  ExecOk       stream=3  FINAL

C→S  Goodbye  stream=0
S→C  Goodbye  stream=0
```

--------------------------------

### Full CDC Subscription Example

Source: https://context7.com/jeremytregunna/foldb/llms.txt

Illustrates a complete CDC subscription flow, including initial subscription, event handling, credit replenishment, and graceful teardown. Demonstrates the interaction between client and server for CDC data.

```protobuf
// Subscribe to "accounts" table starting from seq 0, with 100-event credit window.
Subscribe payload:
  from_seq=0  initial_credits=100  scope=0x01 (filtered)
  filter_count=1
  filter: kind=0x01 (by_name)  name="accounts"

S→C: SubscribeAck  resolved_count=1  [("accounts", table_id=42)]

// Insert event:
S→C: CdcEvent  seq=9143  epoch=2  effect_count=1
  effect[0]:
    table_id=42  key=<encoded PK>  op=0x00 (insert)
    before_col_count=0
    after_col_count=3
    after=[Int64(1003), String("Carol"), Int64(1000)]

// Credit replenishment and clean teardown:
C→S: AckCdc  acked_seq=9143  add_credits=1
C→S: Unsubscribe  FINAL
S→C: ExecOk  FINAL  committed_seq=0xFFFFFFFFFFFFFFFF
```

--------------------------------

### Connection Lifecycle Example

Source: https://context7.com/jeremytregunna/foldb/llms.txt

Illustrates a typical sequence of messages exchanged between client and server during a connection, including TLS, authentication, query execution, and subscription.

```text
C→S  FDBT                     (TLS request)
S→C  Y
     [TLS handshake]

S→C  Hello  stream=0           (server sends first)
C→S  Auth   stream=0  Token    (client authenticates)
S→C  AuthOk stream=0

C→S  RegisterQuery  stream=1   (register SQL)
S→C  Registered     stream=1  FINAL

C→S  Execute   stream=2        (run registered query)
S→C  RowsBegin stream=2  MORE
S→C  RowsBatch stream=2  MORE
S→C  ExecOk    stream=2  FINAL

C→S  Subscribe    stream=3  scope=filtered  filter=[by_name "accounts"]
S→C  SubscribeAck stream=3  MORE           (resolved: "accounts"→42)
S→C  CdcEvent     stream=3
S→C  CdcEvent     stream=3
C→S  AckCdc       stream=3
C→S  Unsubscribe  stream=3  FINAL
S→C  ExecOk       stream=3  FINAL

C→S  Goodbye  stream=0
S→C  Goodbye  stream=0
```

--------------------------------

### Execute Transaction (Example Payload)

Source: https://context7.com/jeremytregunna/foldb/llms.txt

Execute a previously registered transaction using its query_hash and bound parameters. This example shows the Execute frame payload for a funds transfer, including TypedValue encoding for parameters.

```text
Execute frame payload:
  query_hash:   [32 bytes from RegisterQuery response]
  param_count:  3
  params:
    TypedValue(Int64, sender_id=1001)      → 0x05  E9 03 00 00 00 00 00 00
    TypedValue(Int64, receiver_id=1002)    → 0x05  EA 03 00 00 00 00 00 00
    TypedValue(Int64, amount=500)          → 0x05  F4 01 00 00 00 00 00 00
```

--------------------------------

### Obtain an Io Instance

Source: https://github.com/jeremytregunna/foldb/blob/master/docs/zig-0.16.0-migration-guide.md

Use `Io.Threaded` to get an `io` instance when one is not readily available. This is a workaround; prefer threading `Io` through your API.

```zig
var threaded: Io.Threaded = .init_single_threaded;
const io = threaded.io();
```

--------------------------------

### Decimal Encoding Example

Source: https://context7.com/jeremytregunna/foldb/llms.txt

Demonstrates the on-wire representation of a Decimal TypedValue, including its scale and coefficient.

```text
0x0C            -- type tag: Decimal
0x02            -- scale: 2  (value = 12345 × 10^-2 = 123.45)
39 30 00 00 00 00 00 00 00 00 00 00 00 00 00 00  -- i128 LE: 12345
```

--------------------------------

### foldb Server Configuration

Source: https://github.com/jeremytregunna/foldb/blob/master/README.md

Example JSON configuration for the foldb server. Includes settings for storage, networking, replication, S3 integration, and authentication. Defaults are shown as comments.

```jsonc
{
  "storage_dir": "/var/lib/foldb",   // required — where data is stored
  "node_id": 1,                      // unique integer per node in the cluster
  "partition_count": 1,              // number of partitions
  "listen_addr": "0.0.0.0",          // optional, default: 0.0.0.0
  "listen_port": 7432,               // optional, default: 7432
  "peers": [],                       // optional — list of peer objects, e.g. [{"id": 2, "addr": "10.0.0.2:7432"}]
  "max_epoch_size": 10000,           // optional — max transactions per Raft epoch
  "election_timeout_min_ms": 150,    // optional — Raft election timeout range
  "election_timeout_max_ms": 300,
  "heartbeat_interval_ms": 50,       // optional — Raft heartbeat interval

  // S3 — optional, but all five fields are required together or not at all.
  // Without S3, snapshots and log truncation are disabled; recovery replays
  // the full log from the beginning. Fine for development, not for production.
  "s3_endpoint": "http://127.0.0.1:9000",
  "s3_bucket": "foldb",
  "s3_access_key": "...",
  "s3_secret_key": "...",
  "s3_region": "us-east-1",          // required when S3 is configured

  // Auth — optional. Omitting auth_secret leaves the server open to all connections.
  // Generate auth_secret with: foldb gen-secret
  // Add users with: foldb add-user --config config.json --name alice --password hunter2
  "auth_secret": "...",
  "users": [
    { "name": "alice", "token": "..." }
  ]
}
```

--------------------------------

### Conventional Commit Message Examples

Source: https://github.com/jeremytregunna/foldb/blob/master/AGENTS.md

Examples of commit messages adhering to the Conventional Commits specification, including type, scope, and description.

```text
feat: add query builder for folded data
fix: resolve memory leak in arena allocator
refactor: simplify fold operation logic
```

--------------------------------

### foldb DDL for database management

Source: https://context7.com/jeremytregunna/foldb/llms.txt

Examples of cluster-level DDL statements for managing databases. These are applied immediately by the server.

```sql
-- Database management (cluster-level DDL)
CREATE DATABASE myapp;
USE DATABASE myapp;
DROP DATABASE myapp;
```

--------------------------------

### Dynamic Cluster Membership Management

Source: https://context7.com/jeremytregunna/foldb/llms.txt

Code examples for adding and removing nodes from a Raft cluster. Note that only one configuration change can be in flight at a time.

```zig
// Add a new Raft voter (only on leader; returns NotLeader otherwise)
try sequencer.addNode(node_id, "10.0.0.4:7432");

// Remove a voter (returns ConfigChangeInProgress if another change is in flight)
try sequencer.removeNode(node_id);
// Only one config change may be in flight at a time (joint consensus).
```

--------------------------------

### foldb TRANSACTION with ASSERT for preconditions

Source: https://context7.com/jeremytregunna/foldb/llms.txt

Use ASSERT clauses to enforce preconditions before mutations are applied. This example checks if the source account has sufficient balance before a transfer.

```sql
-- ASSERT reads pre-mutation state. Use to enforce preconditions.
TRANSACTION (src INT64, dst INT64, amount INT64) {
    UPDATE accounts SET balance = balance - $amount WHERE id = $src;
    UPDATE accounts SET balance = balance + $amount WHERE id = $dst;
    -- Reads balance BEFORE the UPDATE above — i.e., the original value.
    ASSERT (SELECT balance FROM accounts WHERE id = $src) >= $amount;
}
```

--------------------------------

### Sign Off Commit

Source: https://github.com/jeremytregunna/foldb/blob/master/CONTRIBUTING.md

Example of the required 'Signed-Off-By' line for every commit, attesting to the contributor's review and understanding of the changes.

```git
Signed-Off-By: Your Name <you@example.com>

```

--------------------------------

### Generate Server Secret - foldb gen-secret

Source: https://github.com/jeremytregunna/foldb/blob/master/docs/internal/auth.md

Run this command once during new node setup to generate a secure, base64-encoded 32-byte secret. This secret is crucial for deriving user tokens and must be kept confidential.

```bash
foldb gen-secret
```

--------------------------------

### Get Database ID

Source: https://context7.com/jeremytregunna/foldb/llms.txt

Resolves a database name to its corresponding numeric ID.

```APIDOC
## getDatabaseId(name)

### Description
Resolves a given database name to its numeric ID.

### Method
APIDOC

### Endpoint
APIDOC

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
- **name** (string) - Required - The name of the database.
```

--------------------------------

### Build foldb from Source

Source: https://context7.com/jeremytregunna/foldb/llms.txt

Build the foldb binary and run tests using Zig 0.16.0. Includes commands for unit, integration, and deterministic simulation tests.

```bash
zig build                              # build binary
zig build test                         # unit + integration tests
zig build dst-test                     # deterministic simulation (200 seeds)
zig build dst-test -Ddst-seeds=10000   # deeper simulation sweep
```

--------------------------------

### Process Execution: `run` and `replace` API Changes

Source: https://github.com/jeremytregunna/foldb/blob/master/docs/zig-0.16.0-migration-guide.md

Demonstrates the updated APIs for running and replacing processes. `std.process.Child.run` is now `std.process.run`, and `std.process.execv` is replaced by `std.process.replace`.

```zig
// OLD
const result = std.process.Child.run(allocator, io, .{
    // ...
});
// NEW
const result = std.process.run(allocator, io, .{
    // ...
});
```

```zig
// OLD
const err = std.process.execv(arena, argv);
// NEW
const err = std.process.replace(io, .{ .argv = argv });
```

--------------------------------

### New Zig Main Function Signature

Source: https://github.com/jeremytregunna/foldb/blob/master/docs/zig-0.16.0-migration-guide.md

The `main` function can now accept `std.process.Init` for pre-initialized resources like arena, gpa, io, and environment. Alternatively, it can take `std.process.Init.Minimal` for just args and environment, or no parameters.

```zig
pub fn main(init: std.process.Init) !void {
    const gpa = init.gpa;
    const io = init.io;
    const args = try init.minimal.args.toSlice(init.arena.allocator());
    // ...
}
```

--------------------------------

### Priority Queue Initialization and Methods

Source: https://github.com/jeremytregunna/foldb/blob/master/docs/zig-0.16.0-migration-guide.md

Details the changes in `PriorityQueue` and `PriorityDequeue`, including the removal of the `Allocator` field, renaming of methods like `add` to `push` and `remove` to `pop`, and initialization using `.empty`.

```zig
const MinHeap = std.PriorityQueue(u32, void, lessThan);
var queue: MinHeap = .empty;
```

--------------------------------

### Co-Authored By AI Tool

Source: https://github.com/jeremytregunna/foldb/blob/master/CONTRIBUTING.md

Example of the 'Co-Authored-By' line to be added if AI assisted in writing code or commit messages, ensuring transparency.

```git
Co-Authored-By: Claude Sonnet <noreply@anthropic.com>

```

--------------------------------

### Process Spawning: Old vs. New API

Source: https://github.com/jeremytregunna/foldb/blob/master/docs/zig-0.16.0-migration-guide.md

Compares the old `std.process.Child.init` and `spawn` API with the new, more concise `std.process.spawn` function for creating child processes. The new API uses a struct literal for configuration.

```zig
// OLD — child process
var child = std.process.Child.init(argv, gpa);
child.stdin_behavior = .Pipe;
child.stdout_behavior = .Pipe;
child.stderr_behavior = .Pipe;
try child.spawn(io);

// NEW
var child = try std.process.spawn(io, .{
    .argv = argv,
    .stdin = .pipe,
    .stdout = .pipe,
    .stderr = .pipe,
});
```

--------------------------------

### Subscribe Payload Structure

Source: https://github.com/jeremytregunna/foldb/blob/master/docs/wire-protocol.md

Defines the payload for subscribing to CDC events, including the starting sequence, initial credits, and scope (all tables or filtered).

```protobuf
Subscribe payload:
  from_seq:        u64
  initial_credits: u32
  scope:           u8   (0x00 = all_tables, 0x01 = filtered)

  // if filtered:
  filter_count:    u16   (≥ 1; 0 with filtered scope → ProtocolError)
  filters:         filter_count × TableFilter
```

--------------------------------

### foldb DDL for table management

Source: https://context7.com/jeremytregunna/foldb/llms.txt

Examples of DDL statements for managing tables within the active database. These are applied immediately and affect registered queries.

```sql
-- Table DDL (scoped to active database)
CREATE TABLE accounts (
    id      INT64   PRIMARY KEY,
    name    VARCHAR NOT NULL,
    balance INT64   NOT NULL DEFAULT 0
);

CREATE INDEX idx_name ON accounts (name);

DROP TABLE accounts;   -- silently evicts all registered queries on this table
```

--------------------------------

### Migrating @cImport to Build System

Source: https://github.com/jeremytregunna/foldb/blob/master/docs/zig-0.16.0-migration-guide.md

Demonstrates replacing deprecated `@cImport` with `translate-c` in `build.zig` for C header inclusion. This involves creating a `.h` file and configuring the build system.

```zig
pub const c = @cImport({
    @cInclude("stdio.h");
    @cInclude("GLFW/glfw3.h");
});
```

```c
#include <stdio.h>
#include <GLFW/glfw3.h>
```

```zig
const translate_c = b.addTranslateC(.{
    .root_source_file = b.path("src/c.h"),
    .target = target,
    .optimize = optimize,
});
translate_c.linkSystemLibrary("glfw", .{});

const exe = b.addExecutable(.{
    .name = "prog",
    .root_module = b.createModule(.{
        .root_source_file = b.path("src/main.zig"),
        .optimize = optimize,
        .target = target,
        .imports = &[{
            .{ .name = "c", .module = translate_c.createModule() },
        }],
    }),
});
```

```zig
const c = @import("c");
```

--------------------------------

### Migrate File reading patterns

Source: https://github.com/jeremytregunna/foldb/blob/master/docs/zig-0.16.0-migration-guide.md

The `readToEndAlloc` method has been replaced by using a `file_reader` and its `allocRemaining` method. Note the reordered arguments and new limit type.

```zig
const contents = try file.readToEndAlloc(allocator, 1234);

```

```zig
var file_reader = file.reader(&.{});
const contents = try file_reader.interface.allocRemaining(allocator, .limited(1234));

```

--------------------------------

### Selective Directory Walking with `walkSelectively`

Source: https://github.com/jeremytregunna/foldb/blob/master/docs/zig-0.16.0-migration-guide.md

Demonstrates how to use `Dir.walkSelectively` for filtering directories during traversal, which is more efficient than `Dir.walk` as it avoids unnecessary syscalls for skipped directories. The `Walker.Entry` now includes a `depth` function, and both `Walker` and `SelectiveWalker` have `leave` functions.

```zig
var walker = try dir.walkSelectively(gpa);
defer walker.deinit();
while (try walker.next(io)) |entry| {
    if (failsFilter(entry)) continue;
    if (entry.kind == .directory) {
        try walker.enter(io, entry);
    }
    // ...
}
```

--------------------------------

### Database Scoping Entry Points

Source: https://github.com/jeremytregunna/foldb/blob/master/docs/internal/sql.md

Provides the primary entry points for interacting with the SQL registry, including registering, validating, and evicting queries for a specific database.

```java
registerForDb(sql, db_id, target_schema)
validateQueryForDb(sql, db_id, target_schema)
evictQueriesForDb(db_id)
```

--------------------------------

### Build foldb Project

Source: https://github.com/jeremytregunna/foldb/blob/master/README.md

Commands to build the foldb project and run tests. Includes options for unit, integration, and deterministic simulation tests with configurable seed counts.

```bash
zig build                              # build
```

```bash
zig build test                         # unit + integration tests
```

```bash
zig build dst-test                     # deterministic simulation (200 seeds)
```

```bash
zig build dst-test -Ddst-seeds=10000   # deeper simulation sweep
```

--------------------------------

### Gateway Execute Operation Flow

Source: https://context7.com/jeremytregunna/foldb/llms.txt

Illustrates the steps involved in executing a DML mutation through the gateway, including nondeterminism resolution and reconnaissance.

```pseudocode
gateway.execute(hash, params):
  1. Resolve NOW()   → from injected ClockSource
  2. Resolve UUID_V7() → from injected ClockSource
  3. Resolve RANDOM() → 16 bytes from injected RandSource
  4. Bundle resolved values into TxnIntent payload
  5. Run reconnaissance: walk plan → determine which storage partitions are touched
  6. Submit to Sequencer.submitBytes() → Raft replication → seq assignment
  7. Await FoldExecutors to advance past committed seq
  8. Return ExecResult
```

--------------------------------

### Subscribe to CDC Events (Wire Format)

Source: https://context7.com/jeremytregunna/foldb/llms.txt

Subscribe to a real-time stream of row-level mutation events. The Subscribe message specifies the starting sequence, initial flow-control credits, and the scope (all tables or filtered).

```text
Subscribe  → C→S:
  from_seq:        u64    -- start from this sequence (0 = from beginning)
  initial_credits: u32    -- flow-control window size
  scope:           u8     -- 0x00=all_tables, 0x01=filtered

  // if scope=filtered:
  filter_count:    u16
  filters:         filter_count × TableFilter

TableFilter:
  kind: u8
    0x00 = by_id   → u32 table_id
    0x01 = by_name → u8 name_len + name bytes
```

--------------------------------

### CDC Subscriptions - Subscribe

Source: https://context7.com/jeremytregunna/foldb/llms.txt

Subscribes to a real-time stream of row-level mutation events. Clients can specify a starting sequence number and a scope (all tables or filtered). Flow control is managed via initial credits.

```APIDOC
## CDC Subscriptions

Subscribe to a real-time stream of row-level mutation events. Events carry before and after column values for each affected row.

### Subscribe

```
Subscribe  → C→S:
  from_seq:        u64    -- start from this sequence (0 = from beginning)
  initial_credits: u32    -- flow-control window size
  scope:           u8     -- 0x00=all_tables, 0x01=filtered

  // if scope=filtered:
  filter_count:    u16
  filters:         filter_count × TableFilter

TableFilter:
  kind: u8
    0x00 = by_id   → u32 table_id
    0x01 = by_name → u8 name_len + name bytes
```
```

--------------------------------

### Atomic File Operations: Old vs. New API

Source: https://github.com/jeremytregunna/foldb/blob/master/docs/zig-0.16.0-migration-guide.md

Illustrates the migration from the old `atomicFile` API to the new `createFileAtomic` API for atomic file operations. The new API offers more control with options like `make_path` and `replace`.

```zig
// OLD
var buffer: [1024]u8 = undefined;
var atomic_file = try dest_dir.atomicFile(io, dest_path, .{
    .permissions = actual_permissions,
    .write_buffer = &buffer,
});
defer atomic_file.deinit();
// ... use atomic_file.file_writer ...
try atomic_file.flush();
try atomic_file.renameIntoPlace();

// NEW
var atomic_file = try dest_dir.createFileAtomic(io, dest_path, .{
    .permissions = actual_permissions,
    .make_path = true,
    .replace = true,
});
defer atomic_file.deinit(io);

var buffer: [1024]u8 = undefined;
var file_writer = atomic_file.file.writer(io, &buffer);
// ... use file_writer ...
try file_writer.flush();
try atomic_file.replace(io); // or .link(io) if .replace = false
```

--------------------------------

### Enable Incremental Compilation with Watch

Source: https://github.com/jeremytregunna/foldb/blob/master/docs/zig-0.16.0-migration-guide.md

Enable experimental incremental compilation combined with the watch mode for faster rebuilds. This feature is still disabled by default and requires explicit activation.

```zig
zig build -fincremental --watch
```

--------------------------------

### Enroll foldb User

Source: https://context7.com/jeremytregunna/foldb/llms.txt

Enrolls a new user with foldb by providing the configuration file, username, and password. The output includes a base64 token to be added to the user's configuration.

```bash
foldb add-user --config /etc/foldb/config.json --name alice --password hunter2
# Output:
# Token for 'alice': <base64 token>
# Add this entry to your config's "users" array:
#   {"name": "alice", "token": "<base64 token>"
# Give the token to the client. It will not be shown again.
```

--------------------------------

### Add User - foldb add-user

Source: https://github.com/jeremytregunna/foldb/blob/master/docs/internal/auth.md

Use this command to add a new user by providing the configuration file path, user name, and password. It outputs the derived token and the JSON snippet to add to your config.

```bash
foldb add-user --config /path/to/config.json --name alice --password hunter2
```

--------------------------------

### Packed Union Field Size Requirement in Zig 0.16.0

Source: https://github.com/jeremytregunna/foldb/blob/master/docs/zig-0.16.0-migration-guide.md

In Zig 0.16.0, all fields within a packed union must have the same `@bitSizeOf` as the backing integer. The example shows the old, erroneous syntax and the new, corrected syntax.

```zig
// OLD (error in 0.16)
const U = packed union { x: u8, y: u16 };

// NEW
const U = packed union(u16) {
    x: packed struct(u16) { data: u8, padding: u8 = 0 },
    y: u16,
};
```

--------------------------------

### Read Data at Specific Sequence (Example Payload)

Source: https://context7.com/jeremytregunna/foldb/llms.txt

Perform a historical read of a registered SELECT query at a specific past sequence number. The ReadAt frame payload includes the query_hash, at_seq, and parameters. Response follows the SELECT flow.

```text
ReadAt frame payload:
  query_hash:  [hash of "SELECT id, balance FROM accounts WHERE id = $user_id"]
  at_seq:      9142          -- the committed_seq from a prior ExecOk
  param_count: 1
  params:
    TypedValue(Int64, user_id=1001)  → 0x05  E9 03 00 00 00 00 00 00
```

--------------------------------

### Build and Test FoldDB

Source: https://github.com/jeremytregunna/foldb/blob/master/CONTRIBUTING.md

Commands to build the project and run various test suites, including unit, integration, and deterministic simulation tests.

```bash
zig build

```

```bash
zig build test

```

```bash
zig build dst-test

```

```bash
zig build dst-test -Ddst-seeds=N

```

--------------------------------

### Extern Enum Declaration with Explicit Backing Int in Zig 0.16.0

Source: https://github.com/jeremytregunna/foldb/blob/master/docs/zig-0.16.0-migration-guide.md

Extern contexts (e.g., `export var`) now require explicit backing integers for enums, packed structs, and packed unions. Implicit backing integers are no longer valid. The example demonstrates the old, erroneous syntax and the new, required syntax.

```zig
// OLD → error
const Enum = enum { a, b, c, d };
export var x: Enum = .a;

// NEW
const Enum = enum(u8) { a, b, c, d };
export var x: Enum = .a;
```

--------------------------------

### SQL Layer Pipeline Stages

Source: https://github.com/jeremytregunna/foldb/blob/master/docs/internal/sql.md

Illustrates the deterministic pipeline stages for processing SQL text into a QueryHash. Each stage validates the output of the previous one.

```text
SQL text → Lexer → Parser → Type Checker → Planner → Canonicalization → QueryHash
```

--------------------------------

### Foldb Project Structure

Source: https://github.com/jeremytregunna/foldb/blob/master/AGENTS.md

Illustrates the directory layout for the Foldb project, including build configuration, source files, tests, documentation, and convention files.

```text
foldb/
├── build.zig          # Build config (Zig 0.16.0+)
├── src/
│   ├── lib.zig        # Core library - public API
│   └── main.zig       # CLI entry point
├── tests/             # Integration tests
├── docs/              # Documentation
└── AGENTS.md          # This file
```

--------------------------------

### Standard Task Spawning Pattern

Source: https://github.com/jeremytregunna/foldb/blob/master/docs/zig-0.16.0-migration-guide.md

This pattern handles cancelation and resource cleanup for asynchronous tasks. Ensure proper defer statements for `cancel` and resource deinitialization.

```zig
var foo_future = io.async(foo, .{args});
defer if (foo_future.cancel(io)) |resource| resource.deinit() else |_| {}

const foo_result = try foo_future.await(io);
```

--------------------------------

### Enable New ELF Linker

Source: https://github.com/jeremytregunna/foldb/blob/master/docs/zig-0.16.0-migration-guide.md

Activate the new ELF linker for potentially faster incremental linking. Note that executables produced with this linker currently lack DWARF debug info.

```zig
exe.use_new_linker = true
```

--------------------------------

### Handle optional File.Stat.atime

Source: https://github.com/jeremytregunna/foldb/blob/master/docs/zig-0.16.0-migration-guide.md

Filesystems may not report atime, so it is now an optional type (`?i128`). Use `orelse` to provide a default or handle the absence of a value.

```zig
stat.atime

```

```zig
stat.atime orelse return error.FileAccessTimeUnavailable

```

--------------------------------

### Migrate fs.* to std.Io.Dir/File

Source: https://github.com/jeremytregunna/foldb/blob/master/docs/zig-0.16.0-migration-guide.md

General rule: add an `io` parameter to functions that previously used `std.fs.*`. Many top-level functions and methods have been moved or renamed.

```zig
const contents = try std.fs.cwd().readFileAlloc(allocator, file_name, 1234);

```

```zig
const contents = try std.Io.Dir.cwd().readFileAlloc(io, file_name, allocator, .limited(1234));

```

--------------------------------

### SubmitBytes and SubmitHandle in Sequencer

Source: https://github.com/jeremytregunna/foldb/blob/master/docs/internal/sequencer.md

Illustrates the submission process via `submitBytes()` which enqueues a `PendingSubmit` and returns a `SubmitHandle`. The owner thread processes submissions, and `SubmitHandle.awaitCommit()` provides two modes for waiting on commit: fiber path (yielding) and spin path (CPU-bound).

```go
// Callers submit via submitBytes(), which enqueues a PendingSubmit onto an MPSC queue and returns a SubmitHandle.
// The owner thread drains the queue, calls commitInner, and signals completion by writing the result and setting pending.done = true.
// SubmitHandle.awaitCommit() has two modes:
// - Fiber path (io non-null): suspends via io.sleep(1 ms) between checks, yielding to other connection fibers during the Raft round-trip.
// - Spin path (io null): spins with sched_yield. Safe only for dedicated threads with no fiber scheduler.
// Both paths return CommitTimeout after a fixed bound (30 s / 100M spins respectively).
```

--------------------------------

### Arena Allocator Usage in Zig

Source: https://github.com/jeremytregunna/foldb/blob/master/AGENTS.md

Shows the recommended pattern for using ArenaAllocator for scoped memory allocations in Zig, including deferring cleanup.

```zig
defer arena.deinit()
```

--------------------------------

### SimScheduler for seeded randomness

Source: https://context7.com/jeremytregunna/foldb/llms.txt

Initialize SimScheduler with a seed to drive all randomness in the simulation. Use its methods to introduce probabilities for events like message drops or to generate random ranges for delays.

```zig
// SimScheduler — seeded PRNG driving all randomness
const scheduler = SimScheduler.init(seed);
const drop_this_message = scheduler.chance(0.05); // 5% drop probability
const delay_ns = scheduler.rangeU64(100_000, 5_000_000); // 100µs–5ms
```

--------------------------------

### Update File.setTimestamps usage

Source: https://github.com/jeremytregunna/foldb/blob/master/docs/zig-0.16.0-migration-guide.md

The `setTimestamps` function now takes an options struct for individual timestamp fields, allowing for more granular control.

```zig
try file.setTimestamps(io, src.atime, src.mtime);

```

```zig
try file.setTimestamps(io, .{
    .access_timestamp = .init(src.atime),
    .modify_timestamp = .init(src.mtime),
});

```

--------------------------------

### Sequencer Await Modes

Source: https://context7.com/jeremytregunna/foldb/llms.txt

Shows two different modes for awaiting commit confirmations: the Fiber path for network handlers and the Spin path for dedicated executor threads.

```zig
// Fiber path — used from network connection handlers
const result = try handle.awaitCommit(io);  // suspends via io.sleep(1ms) between checks

// Spin path — used from dedicated executor threads
const result = try handle.awaitCommit(null); // sched_yield; CommitTimeout after 100M spins
```

--------------------------------

### SchemaPayloadKind Values

Source: https://github.com/jeremytregunna/foldb/blob/master/docs/internal/executor.md

Lists the possible values for SchemaPayloadKind: ddl, query, and cluster, along with their scope and database_id usage.

```text
ddl (0x01) — DDL SQL (CREATE TABLE, DROP TABLE, etc.) scoped to database_id
query (0x02) — query registration SQL scoped to database_id
cluster (0x03) — cluster-level DDL (CREATE DATABASE, DROP DATABASE); database_id field is unused
```

--------------------------------

### Register SQL Query (SQL)

Source: https://context7.com/jeremytregunna/foldb/llms.txt

Register a parameterized transaction using the TRANSACTION keyword. Parameters are declared at the top, and the body executes atomically. The server returns a stable 32-byte query_hash upon successful registration.

```sql
-- Register a funds transfer as a compiled transaction block.
-- Parameters are declared at the top; body runs atomically.
TRANSACTION (sender_id INT64, receiver_id INT64, amount INT64) {
    UPDATE accounts SET balance = balance - $amount WHERE id = $sender_id;
    UPDATE accounts SET balance = balance + $amount WHERE id = $receiver_id;
    ASSERT (SELECT balance FROM accounts WHERE id = $sender_id) >= 0;
}
```