@lv-agent/logdb-client 0.1.0

package/README.md

@@ -0,0 +1,67 @@
+# @lv-agent/logdb-client — TypeScript SDK for logdbd
+
+## Install
+
+```bash
+npm install @lv-agent/logdb-client
+```
+
+## Quick Start
+
+```typescript
+import { Client } from '@lv-agent/logdb-client';
+
+const client = new Client('127.0.0.1:50051');
+
+// Append
+const { seq } = await client.append('my-app', 'main', 'test.event', Buffer.from('hello'));
+console.log('appended at seq', seq);
+
+// Read
+const rec = await client.read('my-app', 'main', 1);
+console.log(rec?.eventType);
+
+// Scan all
+const records = await client.scanAll('my-app', 'main', 0);
+for (const r of records) {
+  console.log(`[${r.seq}] ${r.eventType}`);
+}
+
+// Tail (live subscription)
+const stream = client.tail('my-app', 'main', { fromSeq: 0, consumerGroup: 'workers', consumerId: 'w1' });
+for await (const rec of stream) {
+  console.log(`[${rec.seq}] ${rec.eventType}`);
+  // Commit progress
+  await client.commitOffset('my-app', 'main', 'workers', 'w1', rec.seq);
+}
+```
+
+## API
+
+| Method | Description |
+|--------|-------------|
+| `append(ns, stream, eventType, content)` | Write a record |
+| `read(ns, stream, seq)` | Point read |
+| `scanAll(ns, stream, fromSeq)` | Scan all records |
+| `tail(ns, stream, opts)` | Live subscription (async iterable) |
+| `listNamespaces()` | List all namespaces |
+| `listStreams(ns)` | List streams in a namespace |
+| `status()` | Node status |
+| `verifyChain(ns, stream)` | Verify hash chain |
+| `commitOffset(...)` / `committedOffset(...)` | Consumer group offset management |
+
+## TLS / mTLS
+
+```typescript
+import * as fs from 'fs';
+
+const client = new Client('logdbd.example.com:50051', {
+  tlsCa: fs.readFileSync('/etc/certs/ca.crt'),
+  tlsCert: fs.readFileSync('/etc/certs/client.crt'),  // mTLS
+  tlsKey: fs.readFileSync('/etc/certs/client.key'),   // mTLS
+});
+```
+
+## License
+
+Apache-2.0

package/dist/client.d.ts

@@ -0,0 +1,64 @@
+import { TailStream } from './tail-stream';
+import type { AppendResult, BatchAppendResult, NamespaceInfo, LogRecord, StreamInfo, StatusResult, Watermark, VerifyResult, TailOptions } from './types';
+export interface ClientOptions {
+    /** TLS certificate authority (PEM). */
+    tlsCa?: Buffer;
+    /** TLS client cert (PEM) for mTLS. */
+    tlsCert?: Buffer;
+    /** TLS client key (PEM) for mTLS. */
+    tlsKey?: Buffer;
+    /** Bearer auth token. */
+    authToken?: string;
+}
+export declare class Client {
+    private client;
+    private closed;
+    /**
+     * Create a new logdbd client.
+     *
+     * @param addr — host:port, e.g. "127.0.0.1:50051"
+     * @param opts — optional TLS and auth settings
+     */
+    constructor(addr: string, opts?: ClientOptions);
+    /** Append a record. Returns the assigned seq. */
+    append(namespace: string, stream: string, eventType: string, content: Buffer): Promise<AppendResult>;
+    /** Append with full options. */
+    appendFull(opts: {
+        namespace: string;
+        stream: string;
+        eventType: string;
+        contentType?: string;
+        metadata?: Record<string, string>;
+        timestampNs?: number;
+        content: Buffer;
+    }): Promise<AppendResult>;
+    /** Batch append — all in same namespace+stream. */
+    appendBatch(requests: Array<{
+        namespace: string;
+        stream: string;
+        eventType: string;
+        content: Buffer;
+    }>): Promise<BatchAppendResult>;
+    /** Read a record by seq. Returns null if not found. */
+    read(namespace: string, stream: string, seq: number): Promise<LogRecord | null>;
+    /** Scan records in range. Returns array of records. */
+    scanAll(namespace: string, stream: string, fromSeq: number, limit?: number): Promise<LogRecord[]>;
+    /** Subscribe to new records via Tail. */
+    tail(namespace: string, stream: string, opts?: TailOptions): TailStream;
+    /** Get the watermark for a namespace/stream. */
+    watermark(namespace: string, stream: string): Promise<Watermark>;
+    /** List all namespaces. */
+    listNamespaces(): Promise<NamespaceInfo[]>;
+    /** List streams in a namespace. */
+    listStreams(namespace: string): Promise<StreamInfo[]>;
+    /** Get node status. */
+    status(): Promise<StatusResult>;
+    /** Verify hash chain for a stream. */
+    verifyChain(namespace: string, stream: string, fromSeq?: number, toSeq?: number): Promise<VerifyResult>;
+    /** Commit consumer offset. */
+    commitOffset(namespace: string, stream: string, consumerGroup: string, consumerId: string, seq: number): Promise<void>;
+    /** Get committed offset for a consumer. */
+    committedOffset(namespace: string, stream: string, consumerGroup: string, consumerId: string): Promise<number>;
+    /** Close the client connection. */
+    close(): void;
+}

package/dist/client.js

@@ -0,0 +1,289 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Client = void 0;
+const grpc = __importStar(require("@grpc/grpc-js"));
+const protoLoader = __importStar(require("@grpc/proto-loader"));
+const path = __importStar(require("path"));
+const tail_stream_1 = require("./tail-stream");
+let protoDef = null;
+function loadProto() {
+    if (protoDef)
+        return protoDef;
+    const protoPath = path.join(__dirname, '..', 'proto', 'logdbd.proto');
+    const pkgDef = protoLoader.loadSync(protoPath, {
+        keepCase: true,
+        longs: String,
+        enums: String,
+        defaults: true,
+        oneofs: true,
+    });
+    protoDef = grpc.loadPackageDefinition(pkgDef).logdbd;
+    return protoDef;
+}
+class Client {
+    client;
+    closed = false;
+    /**
+     * Create a new logdbd client.
+     *
+     * @param addr — host:port, e.g. "127.0.0.1:50051"
+     * @param opts — optional TLS and auth settings
+     */
+    constructor(addr, opts) {
+        const proto = loadProto();
+        const isTls = opts?.tlsCa || addr.startsWith('https://');
+        let creds;
+        if (isTls && opts?.tlsCert) {
+            creds = grpc.credentials.createSsl(opts.tlsCa, opts.tlsKey, opts.tlsCert);
+        }
+        else if (isTls) {
+            creds = grpc.credentials.createSsl(opts?.tlsCa);
+        }
+        else {
+            creds = grpc.credentials.createInsecure();
+        }
+        const target = addr.startsWith('http') ? addr : (isTls ? `https://${addr}` : `http://${addr}`);
+        // Strip protocol for grpc-js
+        const grpcTarget = target.replace(/^https?:\/\//, '');
+        this.client = new proto.LogDbService(grpcTarget, creds, {
+            'grpc.keepalive_time_ms': 30000,
+            'grpc.keepalive_timeout_ms': 10000,
+        });
+    }
+    // ── Write ──────────────────────────────────────────────────────────
+    /** Append a record. Returns the assigned seq. */
+    append(namespace, stream, eventType, content) {
+        return this.appendFull({
+            namespace, stream, eventType,
+            content, contentType: 'application/json',
+            metadata: {}, timestampNs: 0,
+        });
+    }
+    /** Append with full options. */
+    appendFull(opts) {
+        return new Promise((resolve, reject) => {
+            this.client.Append({
+                namespace: opts.namespace,
+                stream: opts.stream,
+                eventType: opts.eventType,
+                content: opts.content,
+                contentType: opts.contentType || 'application/json',
+                metadata: (opts.metadata || {}),
+                timestampNs: opts.timestampNs || 0,
+            }, (err, resp) => {
+                if (err)
+                    return reject(err);
+                resolve({
+                    namespaceId: resp.namespaceId,
+                    streamId: resp.streamId,
+                    seq: resp.seq,
+                    gid: resp.gid,
+                });
+            });
+        });
+    }
+    /** Batch append — all in same namespace+stream. */
+    appendBatch(requests) {
+        return new Promise((resolve, reject) => {
+            this.client.BatchAppend({ requests }, (err, resp) => {
+                if (err)
+                    return reject(err);
+                resolve({
+                    records: (resp.records || []).map((r) => ({
+                        namespaceId: r.namespaceId,
+                        streamId: r.streamId,
+                        seq: r.seq,
+                        gid: r.gid,
+                    })),
+                    error: resp.error ? { code: resp.error.code, message: resp.error.message } : undefined,
+                });
+            });
+        });
+    }
+    // ── Read ───────────────────────────────────────────────────────────
+    /** Read a record by seq. Returns null if not found. */
+    read(namespace, stream, seq) {
+        return new Promise((resolve, reject) => {
+            this.client.Read({ namespace, stream, seq }, (err, resp) => {
+                if (err)
+                    return reject(err);
+                if (!resp.found || !resp.record)
+                    return resolve(null);
+                resolve(convertRecord(resp.record));
+            });
+        });
+    }
+    /** Scan records in range. Returns array of records. */
+    scanAll(namespace, stream, fromSeq, limit = 10000) {
+        return new Promise((resolve, reject) => {
+            const call = this.client.Scan({ namespace, stream, fromSeq, toSeq: 0, limit });
+            const records = [];
+            call.on('data', (resp) => {
+                for (const r of resp.records || [])
+                    records.push(convertRecord(r));
+            });
+            call.on('end', () => resolve(records));
+            call.on('error', (err) => reject(err));
+        });
+    }
+    /** Subscribe to new records via Tail. */
+    tail(namespace, stream, opts) {
+        const call = this.client.Tail({
+            namespace, stream,
+            fromSeq: opts?.fromSeq ?? 0,
+            batchSize: opts?.batchSize ?? 100,
+            consumerGroup: opts?.consumerGroup ?? '',
+            consumerId: opts?.consumerId ?? '',
+        });
+        return new tail_stream_1.TailStream(call, convertRecord);
+    }
+    // ── Watermark ──────────────────────────────────────────────────────
+    /** Get the watermark for a namespace/stream. */
+    watermark(namespace, stream) {
+        return new Promise((resolve, reject) => {
+            this.client.GetWatermark({ namespace, stream }, (err, resp) => {
+                if (err)
+                    return reject(err);
+                resolve({
+                    namespace: resp.namespace,
+                    stream: resp.stream,
+                    oldestSeq: Number(resp.oldestSeq),
+                    durableSeq: Number(resp.durableSeq),
+                    replicatedSeq: Number(resp.replicatedSeq),
+                    nodeId: resp.nodeId,
+                    role: resp.role,
+                });
+            });
+        });
+    }
+    // ── Admin ──────────────────────────────────────────────────────────
+    /** List all namespaces. */
+    listNamespaces() {
+        return new Promise((resolve, reject) => {
+            this.client.ListNamespaces({}, (err, resp) => {
+                if (err)
+                    return reject(err);
+                resolve((resp.namespaces || []).map((n) => ({
+                    name: n.name, id: n.id, streamCount: Number(n.streamCount),
+                })));
+            });
+        });
+    }
+    /** List streams in a namespace. */
+    listStreams(namespace) {
+        return new Promise((resolve, reject) => {
+            this.client.ListStreams({ namespace }, (err, resp) => {
+                if (err)
+                    return reject(err);
+                resolve((resp.streams || []).map((s) => ({
+                    name: s.name, id: Number(s.id),
+                    firstSeq: Number(s.firstSeq), durableSeq: Number(s.durableSeq),
+                    recordCount: Number(s.recordCount),
+                })));
+            });
+        });
+    }
+    /** Get node status. */
+    status() {
+        return new Promise((resolve, reject) => {
+            this.client.Status({}, (err, resp) => {
+                if (err)
+                    return reject(err);
+                resolve({
+                    nodeId: resp.nodeId,
+                    role: resp.role || '',
+                    durableSequence: Number(resp.durableSequence),
+                    checkpoint: Number(resp.checkpoint),
+                    walBytesUsed: Number(resp.walBytesUsed),
+                    walBytesTotal: Number(resp.walBytesTotal),
+                });
+            });
+        });
+    }
+    /** Verify hash chain for a stream. */
+    verifyChain(namespace, stream, fromSeq = 0, toSeq = 0) {
+        return new Promise((resolve, reject) => {
+            this.client.VerifyChain({ namespace, stream, fromSeq, toSeq }, (err, resp) => {
+                if (err)
+                    return reject(err);
+                resolve({
+                    ok: resp.ok,
+                    verifiedFrom: Number(resp.verifiedFrom),
+                    verifiedTo: Number(resp.verifiedTo),
+                    errorAtSeq: Number(resp.errorAtSeq),
+                    errorMessage: resp.errorMessage,
+                });
+            });
+        });
+    }
+    /** Commit consumer offset. */
+    commitOffset(namespace, stream, consumerGroup, consumerId, seq) {
+        return new Promise((resolve, reject) => {
+            this.client.CommitOffset({ namespace, stream, consumerGroup, consumerId, committedSeq: seq }, (err) => { if (err)
+                return reject(err); resolve(); });
+        });
+    }
+    /** Get committed offset for a consumer. */
+    committedOffset(namespace, stream, consumerGroup, consumerId) {
+        return new Promise((resolve, reject) => {
+            this.client.GetCommittedOffset({ namespace, stream, consumerGroup, consumerId }, (err, resp) => {
+                if (err)
+                    return reject(err);
+                resolve(Number(resp.committedSeq));
+            });
+        });
+    }
+    /** Close the client connection. */
+    close() {
+        if (!this.closed) {
+            this.closed = true;
+            grpc.closeClient(this.client);
+        }
+    }
+}
+exports.Client = Client;
+function convertRecord(r) {
+    return {
+        namespaceId: r.namespaceId,
+        streamId: Number(r.streamId),
+        seq: Number(r.seq),
+        eventType: r.eventType,
+        timestampNs: Number(r.timestampNs),
+        contentType: r.contentType,
+        metadata: r.metadata || {},
+        content: Buffer.isBuffer(r.content) ? r.content : Buffer.from(r.content || ''),
+    };
+}

package/dist/index.d.ts

@@ -0,0 +1,23 @@
+/**
+ * logdb-client — TypeScript SDK for logdbd
+ *
+ * ```typescript
+ * import { Client } from 'logdb-client';
+ *
+ * const client = new Client('127.0.0.1:50051');
+ *
+ * // Append
+ * const { seq } = await client.append('my-app', 'main', 'test.event', Buffer.from('hello'));
+ *
+ * // Read
+ * const rec = await client.read('my-app', 'main', 1);
+ *
+ * // Tail (live subscription)
+ * for await (const rec of client.tail('my-app', 'main', { fromSeq: 0 })) {
+ *   console.log(rec.seq, rec.eventType);
+ * }
+ * ```
+ */
+export { Client, ClientOptions } from './client';
+export { TailStream } from './tail-stream';
+export { LogRecord, AppendResult, Watermark, VerifyResult, TailOptions } from './types';

package/dist/index.js

@@ -0,0 +1,27 @@
+"use strict";
+/**
+ * logdb-client — TypeScript SDK for logdbd
+ *
+ * ```typescript
+ * import { Client } from 'logdb-client';
+ *
+ * const client = new Client('127.0.0.1:50051');
+ *
+ * // Append
+ * const { seq } = await client.append('my-app', 'main', 'test.event', Buffer.from('hello'));
+ *
+ * // Read
+ * const rec = await client.read('my-app', 'main', 1);
+ *
+ * // Tail (live subscription)
+ * for await (const rec of client.tail('my-app', 'main', { fromSeq: 0 })) {
+ *   console.log(rec.seq, rec.eventType);
+ * }
+ * ```
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.TailStream = exports.Client = void 0;
+var client_1 = require("./client");
+Object.defineProperty(exports, "Client", { enumerable: true, get: function () { return client_1.Client; } });
+var tail_stream_1 = require("./tail-stream");
+Object.defineProperty(exports, "TailStream", { enumerable: true, get: function () { return tail_stream_1.TailStream; } });

package/dist/tail-stream.d.ts

@@ -0,0 +1,14 @@
+import type { LogRecord } from './types';
+/** Async iterable stream of records from a Tail subscription. */
+export declare class TailStream implements AsyncIterable<LogRecord> {
+    private readonly convert;
+    private call;
+    private buffer;
+    private done;
+    constructor(call: any, convert: (r: any) => LogRecord);
+    /** Get the next record (waits for new data). */
+    next(): Promise<LogRecord | null>;
+    /** Cancel the subscription. */
+    cancel(): void;
+    [Symbol.asyncIterator](): AsyncIterator<LogRecord>;
+}

package/dist/tail-stream.js

@@ -0,0 +1,50 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.TailStream = void 0;
+/** Async iterable stream of records from a Tail subscription. */
+class TailStream {
+    convert;
+    call = null;
+    buffer = [];
+    done = false;
+    constructor(call, convert) {
+        this.convert = convert;
+        this.call = call;
+        call.on('data', (resp) => {
+            if (resp.heartbeat)
+                return;
+            for (const r of resp.records || []) {
+                this.buffer.push(convert(r));
+            }
+        });
+        call.on('end', () => { this.done = true; });
+        call.on('error', () => { this.done = true; });
+    }
+    /** Get the next record (waits for new data). */
+    async next() {
+        while (this.buffer.length === 0 && !this.done) {
+            await new Promise(resolve => setTimeout(resolve, 10));
+        }
+        if (this.buffer.length > 0) {
+            return this.buffer.shift();
+        }
+        return null;
+    }
+    /** Cancel the subscription. */
+    cancel() {
+        if (this.call) {
+            this.call.cancel();
+            this.call = null;
+        }
+        this.done = true;
+    }
+    [Symbol.asyncIterator]() {
+        return {
+            next: async () => {
+                const rec = await this.next();
+                return rec ? { value: rec, done: false } : { value: undefined, done: true };
+            }
+        };
+    }
+}
+exports.TailStream = TailStream;

package/dist/types.d.ts

@@ -0,0 +1,74 @@
+/** A logdbd record. */
+export interface LogRecord {
+    namespaceId: number;
+    streamId: number;
+    seq: number;
+    eventType: string;
+    timestampNs: number;
+    contentType: string;
+    metadata: Record<string, string>;
+    content: Buffer;
+}
+/** Response from append(). */
+export interface AppendResult {
+    namespaceId: number;
+    streamId: number;
+    seq: number;
+    gid: number;
+}
+/** Batch append response. */
+export interface BatchAppendResult {
+    records: AppendResult[];
+    error?: {
+        code: string;
+        message: string;
+    };
+}
+/** Namespace info. */
+export interface NamespaceInfo {
+    name: string;
+    id: number;
+    streamCount: number;
+}
+/** Stream info. */
+export interface StreamInfo {
+    name: string;
+    id: number;
+    firstSeq: number;
+    durableSeq: number;
+    recordCount: number;
+}
+/** Watermark. */
+export interface Watermark {
+    namespace: string;
+    stream: string;
+    oldestSeq: number;
+    durableSeq: number;
+    replicatedSeq: number;
+    nodeId: string;
+    role: string;
+}
+/** Node status. */
+export interface StatusResult {
+    nodeId: string;
+    role: string;
+    durableSequence: number;
+    checkpoint: number;
+    walBytesUsed: number;
+    walBytesTotal: number;
+}
+/** Hash chain verification result. */
+export interface VerifyResult {
+    ok: boolean;
+    verifiedFrom: number;
+    verifiedTo: number;
+    errorAtSeq: number;
+    errorMessage: string;
+}
+/** Tail options. */
+export interface TailOptions {
+    fromSeq?: number;
+    batchSize?: number;
+    consumerGroup?: string;
+    consumerId?: string;
+}

package/dist/types.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/package.json

@@ -0,0 +1,20 @@
+{
+  "name": "@lv-agent/logdb-client",
+  "version": "0.1.0",
+  "description": "TypeScript SDK for logdbd — append-only audit log database",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "files": ["dist", "proto"],
+  "scripts": {
+    "build": "tsc",
+    "prepublishOnly": "npm run build"
+  },
+  "dependencies": {
+    "@grpc/grpc-js": "^1.12.0",
+    "@grpc/proto-loader": "^0.7.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "typescript": "^5.6.0"
+  }
+}

package/proto/logdbd.proto

@@ -0,0 +1,262 @@
+syntax = "proto3";
+package logdbd;
+
+service LogDbService {
+  rpc Append(AppendRequest) returns (AppendResponse);
+  rpc BatchAppend(BatchAppendRequest) returns (AppendBatchResponse);
+  rpc Read(ReadRequest) returns (ReadResponse);
+  rpc Scan(ScanRequest) returns (stream ScanResponse);
+  rpc Tail(TailRequest) returns (stream TailResponse);
+  rpc Checkpoint(CheckpointRequest) returns (CheckpointResponse);
+  rpc Status(StatusRequest) returns (StatusResponse);
+  rpc GetWatermark(GetWatermarkRequest) returns (Watermark);
+  rpc VerifyChain(VerifyChainRequest) returns (VerifyChainResponse);
+
+  // Consumer group — server-side offset tracking
+  rpc CommitOffset(CommitOffsetRequest) returns (CommitOffsetResponse);
+  rpc GetCommittedOffset(GetCommittedOffsetRequest) returns (GetCommittedOffsetResponse);
+
+  // Catalog — namespace & stream management
+  rpc ListNamespaces(ListNamespacesRequest) returns (ListNamespacesResponse);
+  rpc ListStreams(ListStreamsRequest) returns (ListStreamsResponse);
+}
+
+// ─── Record (full logdbd record) ─────────────────────────────────────────
+
+message Record {
+  uint32 namespace_id      = 1;
+  uint64 stream_id         = 2;
+  uint64 seq               = 3;
+  string event_type        = 4;
+  uint64 timestamp_ns      = 5;
+  string content_type      = 6;
+  map<string, string> metadata = 7;
+  bytes  content           = 8;
+}
+
+// ─── Write ───────────────────────────────────────────────────────────────
+
+message AppendRequest {
+  string namespace    = 1;
+  string stream       = 2;
+  string event_type   = 3;
+  uint64 timestamp_ns = 4;
+  string content_type = 5;
+  map<string, string> metadata = 6;
+  bytes  content      = 7;
+}
+
+message AppendResponse {
+  uint32 namespace_id  = 1;
+  uint64 stream_id     = 2;
+  uint64 seq           = 3;
+  uint64 gid           = 4;  // logdb internal gid (opaque to caller)
+}
+
+message BatchAppendRequest {
+  repeated AppendRequest requests = 1;
+}
+
+message AppendBatchResponse {
+  repeated AppendResponse records = 1;
+  Error error = 2;
+}
+
+message Error {
+  string code    = 1;
+  string message = 2;
+  bool   retryable = 3;
+}
+
+// ─── Read ────────────────────────────────────────────────────────────────
+
+message ReadRequest {
+  string namespace = 1;
+  string stream    = 2;
+  uint64 seq       = 3;
+}
+
+message ReadResponse {
+  Record record = 1;
+  bool   found  = 2;
+}
+
+message ScanRequest {
+  string namespace = 1;
+  string stream    = 2;
+  uint64 from_seq  = 3;
+  uint64 to_seq    = 4;  // 0 = durable tail
+  uint32 limit     = 5;
+}
+
+message ScanResponse {
+  repeated Record records = 1;
+  uint64 next_seq         = 2;
+  bool   has_more         = 3;
+}
+
+message TailRequest {
+  string namespace       = 1;
+  string stream          = 2;
+  uint64 from_seq        = 3;
+  uint32 batch_size      = 4;
+  string consumer_group  = 5;  // consumer group name (for shared offset tracking)
+  string consumer_id     = 6;  // unique consumer ID within the group
+}
+
+message TailResponse {
+  repeated Record records  = 1;
+  uint64 durable_seq       = 2;
+  bool   heartbeat         = 3;
+}
+
+// ─── Watermark ───────────────────────────────────────────────────────────
+
+message GetWatermarkRequest {
+  string namespace = 1;  // required
+  string stream    = 2;  // optional
+}
+
+message Watermark {
+  string namespace       = 1;
+  string stream          = 2;
+  uint64 oldest_seq      = 3;
+  uint64 durable_seq     = 4;
+  uint64 replicated_seq  = 5;
+  string node_id         = 6;
+  string role            = 7;
+}
+
+// ─── Admin ───────────────────────────────────────────────────────────────
+
+message CheckpointRequest {
+  uint64 sequence = 1;
+}
+
+message CheckpointResponse {}
+
+message StatusRequest {}
+
+message StatusResponse {
+  uint64 durable_sequence = 1;
+  uint64 checkpoint = 2;
+  uint64 wal_bytes_used = 3;
+  uint64 wal_bytes_total = 4;
+  string node_id = 5;
+  string role = 6;
+}
+
+// ─── VerifyChain ─────────────────────────────────────────────────────────
+
+message VerifyChainRequest {
+  string namespace = 1;
+  string stream    = 2;
+  uint64 from_seq  = 3;
+  uint64 to_seq    = 4;  // 0 = durable tail
+}
+
+message VerifyChainResponse {
+  bool   ok              = 1;
+  uint64 verified_from   = 2;
+  uint64 verified_to     = 3;
+  uint64 error_at_seq    = 4;
+  string error_message   = 5;
+}
+
+// ─── Consumer offset tracking ────────────────────────────────────────────
+
+message CommitOffsetRequest {
+  string namespace       = 1;
+  string stream          = 2;
+  string consumer_group  = 3;
+  string consumer_id     = 4;
+  uint64 committed_seq   = 5;  // last successfully processed seq
+}
+
+message CommitOffsetResponse {
+  bool   ok      = 1;
+  string message = 2;
+}
+
+// Resolve the committed offset for a consumer
+message GetCommittedOffsetRequest {
+  string namespace       = 1;
+  string stream          = 2;
+  string consumer_group  = 3;
+  string consumer_id     = 4;
+}
+
+message GetCommittedOffsetResponse {
+  uint64 committed_seq = 1;  // 0 = no offset committed yet
+}
+
+// Internal replication service (primary → standby).
+// Transfers raw encoded bytes — independent of the public Record schema.
+service ReplicationService {
+  rpc Sync(ReplicationRequest) returns (ReplicationResponse);
+}
+
+message ReplicationRecord {
+  uint64 gid          = 1;  // logdb global id (preserved on standby)
+  uint64 timestamp_ns = 2;
+  bytes  content      = 3;  // raw encoded logdbd record (header + user_content)
+}
+
+message ReplicationRequest {
+  string cluster_id     = 1;
+  uint64 epoch          = 2;
+  repeated ReplicationRecord records = 3;
+}
+
+message ReplicationResponse {
+  uint64 last_gid = 1;  // highest gid applied
+}
+
+// ─── Snapshot service (primary → standby full sync) ──────────────────────────
+
+service SnapshotService {
+  // Standby requests a snapshot; primary streams segment files.
+  rpc PullSnapshot(SnapshotRequest) returns (stream SnapshotChunk);
+}
+
+message SnapshotRequest {
+  string cluster_id = 1;
+  uint64 epoch      = 2;
+}
+
+message SnapshotChunk {
+  string file_name = 1;   // e.g. "segment-00000001.log"
+  uint64 offset    = 2;   // byte offset within file
+  bytes  data      = 3;   // chunk payload
+  bool   last      = 4;   // true if this is the last chunk of the snapshot
+}
+
+// ─── Catalog messages ───────────────────────────────────────────────────────
+
+message ListNamespacesRequest {}
+
+message NamespaceInfo {
+  string name = 1;
+  uint32 id   = 2;
+  uint64 stream_count = 3;
+}
+
+message ListNamespacesResponse {
+  repeated NamespaceInfo namespaces = 1;
+}
+
+message ListStreamsRequest {
+  string namespace = 1;
+}
+
+message StreamInfo {
+  string name         = 1;
+  uint64 id           = 2;
+  uint64 first_seq    = 3;
+  uint64 durable_seq  = 4;
+  uint64 record_count = 5;
+}
+
+message ListStreamsResponse {
+  repeated StreamInfo streams = 1;
+}