@lv-agent/logdb-client 0.3.0 → 0.4.0

package/README.md

@@ -34,11 +34,6 @@ for await (const rec of stream) {
   await client.commitOffset('my-app', 'main', 'workers', 'w1', rec.seq);
 }
 
-// SQL query against cache
-const rows = await client.query('my-app', 'main',
-  "SELECT seq, event_type FROM records WHERE event_type = 'llm.call' ORDER BY seq DESC LIMIT 10");
-for (const row of rows) console.log(JSON.parse(row));
-
 // Subscribe to event types in real-time
 const sub = client.subscribe('my-app', 'main',
   ['tool.call', 'llm.call'], 'sandbox-processors', 'worker-1');
@@ -55,8 +50,8 @@ sub.on('data', (rec) => {
 | `append(ns, stream, eventType, content)` | Write a record |
 | `read(ns, stream, seq)` | Point read |
 | `scanAll(ns, stream, fromSeq)` | Scan all records |
+| `query(req)` | Structured query → discriminated `QueryResponse` (see Query) |
 | `tail(ns, stream, opts)` | Live subscription (async iterable) |
-| `query(ns, stream, sql)` | SQL SELECT against query cache |
 | `subscribe(ns, stream, eventTypes, group, id)` | Event-type push subscription |
 | `listNamespaces()` | List all namespaces |
 | `listStreams(ns)` | List streams in a namespace |
@@ -66,6 +61,54 @@ sub.on('data', (rec) => {
 | `deleteStream(ns, stream)` | Delete all records in a stream (admin) |
 | `commitOffset(...)` / `committedOffset(...)` | Consumer group offset management |
 
+## Query
+
+logdbd's `Query` RPC is a native structured-filter engine that reads the log
+segment directly at the committed cursor (no SQL, no SQLite cache, no Indexer).
+Build a `QueryRequest` with predicates + a result shape; the response is a
+discriminated union keyed on `kind`.
+
+```typescript
+// Count records of a given type
+const { count } = await client.query({
+  namespace: 'my-app', stream: 'main',
+  eventTypes: ['tool.call'],
+  result: 'COUNT',
+});
+
+// Filter by metadata + seq range, return records (newest first, top 10)
+const { records } = await client.query({
+  namespace: 'my-app', stream: 'main',
+  fromSeq: 100, toSeq: 200,
+  metadata: [{ key: 'turn_id', value: '7' }],
+  result: 'RECORDS',
+  descending: true, limit: 10,
+});
+
+// Max of a metadata field (numeric; the engine parses string values as u64)
+const { max } = await client.query({
+  namespace: 'my-app', stream: 'main',
+  eventTypes: ['turn_started'],
+  aggregateField: 'turn_id',
+  result: 'MAX',
+});
+
+// Anti-join: turn_started with no matching turn terminal
+const { records: incomplete } = await client.query({
+  namespace: 'my-app', stream: 'main',
+  eventTypes: ['turn_started'],
+  absent: {
+    peerEventTypes: ['turn_completed', 'turn_failed', 'turn_canceled', 'turn_blocked'],
+    joinKey: 'turn_id',
+  },
+  result: 'RECORDS',
+});
+```
+
+Predicates (all AND-combined): `eventTypes`, `fromSeq`/`toSeq` (inclusive),
+`metadata` (`key` = `value`), `absent` (anti-join). Result shapes: `RECORDS`,
+`COUNT`, `EXISTS`, `COUNT_DISTINCT`, `MIN`, `MAX`, `DISTINCT_VALUES`.
+
 ## TLS / mTLS
 
 ```typescript

package/dist/client.d.ts

@@ -1,6 +1,6 @@
 import * as grpc from '@grpc/grpc-js';
 import { TailStream } from './tail-stream';
-import type { AppendResult, BatchAppendResult, NamespaceInfo, LogRecord, StreamInfo, StatusResult, Watermark, VerifyResult, TailOptions } from './types';
+import type { AppendResult, BatchAppendResult, NamespaceInfo, LogRecord, QueryRequest, QueryResponse, StreamInfo, StatusResult, Watermark, VerifyResult, TailOptions } from './types';
 export interface ClientOptions {
     /** TLS certificate authority (PEM). */
     tlsCa?: Buffer;
@@ -57,12 +57,18 @@ export declare class Client {
     subscribe(namespace: string, stream: string, eventTypes: string[], consumerGroup: string, consumerId: string): grpc.ClientReadableStream<any>;
     /** Subscribe to new records via Tail. */
     tail(namespace: string, stream: string, opts?: TailOptions): TailStream;
-    /** Execute a read-only SQL query against a stream's query cache.
+    /** Execute a structured query against a stream.
      *
-     * Only SELECT is allowed — enforced at the SQLite kernel level.
-     * Each row is returned as a JSON string.
+     * Reads the log segment directly at the committed cursor (no SQL, no
+     * SQLite cache — cr-027). Build a `QueryRequest` with predicates + a result
+     * shape; the returned `QueryResponse` is a discriminated union keyed on
+     * `kind` (e.g. `{ kind: 'count', count: 3 }`).
+     *
+     * `fromSeq`/`toSeq` are an inclusive closed interval; `result` defaults to
+     * RECORDS; `limit = 0` means unlimited; aggregations skip records lacking
+     * `aggregateField`.
      */
-    query(namespace: string, stream: string, sql: string): Promise<string[]>;
+    query(req: QueryRequest): Promise<QueryResponse>;
     /** Get the watermark for a namespace/stream. */
     watermark(namespace: string, stream: string): Promise<Watermark>;
     /** List all namespaces. */

package/dist/client.js

@@ -43,8 +43,12 @@ function loadProto() {
     if (protoDef)
         return protoDef;
     const protoPath = path.join(__dirname, '..', 'proto', 'logdbd.proto');
+    // keepCase: false — field names are camelCased (eventType, fromSeq, …) to
+    // match the rest of this SDK. With true they'd be snake_case and every
+    // multi-word request field would be silently dropped / response field read
+    // as undefined (empirically confirmed against a live server).
     const pkgDef = protoLoader.loadSync(protoPath, {
-        keepCase: true,
+        keepCase: false,
         longs: String,
         enums: String,
         defaults: true,
@@ -191,17 +195,23 @@ class Client {
         return new tail_stream_1.TailStream(call, convertRecord);
     }
     // ── Query ──────────────────────────────────────────────────────────
-    /** Execute a read-only SQL query against a stream's query cache.
+    /** Execute a structured query against a stream.
      *
-     * Only SELECT is allowed — enforced at the SQLite kernel level.
-     * Each row is returned as a JSON string.
+     * Reads the log segment directly at the committed cursor (no SQL, no
+     * SQLite cache — cr-027). Build a `QueryRequest` with predicates + a result
+     * shape; the returned `QueryResponse` is a discriminated union keyed on
+     * `kind` (e.g. `{ kind: 'count', count: 3 }`).
+     *
+     * `fromSeq`/`toSeq` are an inclusive closed interval; `result` defaults to
+     * RECORDS; `limit = 0` means unlimited; aggregations skip records lacking
+     * `aggregateField`.
      */
-    query(namespace, stream, sql) {
+    query(req) {
         return new Promise((resolve, reject) => {
-            this.client.Query({ namespace, stream, sql }, (err, resp) => {
+            this.client.Query(req, (err, resp) => {
                 if (err)
                     return reject(err);
-                resolve(resp.rows || []);
+                resolve(parseQueryResponse(resp));
             });
         });
     }
@@ -342,3 +352,27 @@ function convertRecord(r) {
         content: Buffer.isBuffer(r.content) ? r.content : Buffer.from(r.content || ''),
     };
 }
+/** Resolve the QueryResponse `result` oneof (set by proto-loader because
+ * `oneofs: true`) into the typed discriminated union. */
+function parseQueryResponse(resp) {
+    switch (resp.result) {
+        case 'count':
+            return { kind: 'count', count: Number(resp.count) };
+        case 'exists':
+            return { kind: 'exists', exists: !!resp.exists };
+        case 'countDistinct':
+            return { kind: 'countDistinct', countDistinct: Number(resp.countDistinct) };
+        case 'min':
+            return { kind: 'min', min: Number(resp.min) };
+        case 'max':
+            return { kind: 'max', max: Number(resp.max) };
+        case 'distinctValues':
+            return { kind: 'distinctValues', values: resp.distinctValues?.values || [] };
+        case 'records':
+        default:
+            return {
+                kind: 'records',
+                records: (resp.records?.records || []).map(convertRecord),
+            };
+    }
+}

package/dist/index.d.ts

@@ -20,4 +20,4 @@
  */
 export { Client, ClientOptions } from './client';
 export { TailStream } from './tail-stream';
-export { LogRecord, AppendResult, Watermark, VerifyResult, TailOptions } from './types';
+export { LogRecord, AppendResult, Watermark, VerifyResult, TailOptions, QueryRequest, QueryResponse, QueryResultKind, MetadataFilter, AbsentMatch, } from './types';

package/dist/types.d.ts

@@ -72,3 +72,64 @@ export interface TailOptions {
     consumerGroup?: string;
     consumerId?: string;
 }
+/** Result-shape selector for a structured query. */
+export type QueryResultKind = 'RECORDS' | 'COUNT' | 'COUNT_DISTINCT' | 'MIN' | 'MAX' | 'EXISTS' | 'DISTINCT_VALUES';
+/** A metadata equality predicate (key = value). */
+export interface MetadataFilter {
+    key: string;
+    value: string;
+}
+/** Anti-join (NOT EXISTS): drop records whose `joinKey` value also appears on a
+ * record matching `peerEventTypes`. */
+export interface AbsentMatch {
+    peerEventTypes: string[];
+    joinKey: string;
+}
+/** Structured query request — predicates (all AND-combined) + result shape.
+ * The server reads the log segment directly at the committed cursor. */
+export interface QueryRequest {
+    namespace: string;
+    stream: string;
+    /** IN filter on event_type (empty/absent = all). */
+    eventTypes?: string[];
+    /** seq >= (inclusive). */
+    fromSeq?: number;
+    /** seq <= (inclusive). */
+    toSeq?: number;
+    /** Equality on metadata fields. */
+    metadata?: MetadataFilter[];
+    /** Result shape (defaults to RECORDS). */
+    result?: QueryResultKind;
+    /** COUNT_DISTINCT/MIN/MAX/DISTINCT_VALUES target (empty = seq). */
+    aggregateField?: string;
+    /** Anti-join. */
+    absent?: AbsentMatch;
+    /** 0 = unlimited. Ignored for aggregations. */
+    limit?: number;
+    /** Order records/values by seq descending. */
+    descending?: boolean;
+}
+/** Typed query response — the server's `result` oneof, resolved to a
+ * discriminated union keyed on `kind`. */
+export type QueryResponse = {
+    kind: 'records';
+    records: LogRecord[];
+} | {
+    kind: 'count';
+    count: number;
+} | {
+    kind: 'exists';
+    exists: boolean;
+} | {
+    kind: 'countDistinct';
+    countDistinct: number;
+} | {
+    kind: 'min';
+    min: number;
+} | {
+    kind: 'max';
+    max: number;
+} | {
+    kind: 'distinctValues';
+    values: string[];
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lv-agent/logdb-client",
-  "version": "0.3.0",
+  "version": "0.4.0",
   "description": "TypeScript SDK for logdbd — append-only audit log database",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",

package/proto/logdbd.proto

@@ -19,6 +19,16 @@ service LogDbService {
   // Catalog — namespace & stream management
   rpc ListNamespaces(ListNamespacesRequest) returns (ListNamespacesResponse);
   rpc ListStreams(ListStreamsRequest) returns (ListStreamsResponse);
+
+  // Management API — stream lifecycle + quota
+  rpc CreateStream(CreateStreamRequest) returns (CreateStreamResponse);
+  rpc DeleteStream(DeleteStreamRequest) returns (DeleteStreamResponse);
+
+  // Query — native structured filter against the log segment
+  rpc Query(QueryRequest) returns (QueryResponse);
+
+  // Subscribe — real-time event-type push with consumer-group offset tracking
+  rpc Subscribe(SubscribeRequest) returns (stream Record);
 }
 
 // ─── Record (full logdbd record) ─────────────────────────────────────────
@@ -260,3 +270,95 @@ message StreamInfo {
 message ListStreamsResponse {
   repeated StreamInfo streams = 1;
 }
+
+// ─── Query (native structured filter engine) ──────────────────────────────
+// Reads the log segment directly at the committed cursor (no SQLite cache).
+// See veps/cr-027-native-query-engine.md ("读边界").
+message QueryRequest {
+  string namespace = 1;
+  string stream    = 2;
+  // Predicates (all AND-combined).
+  repeated string event_types    = 3;   // IN filter on event_type (empty = all).
+  optional uint64 from_seq       = 4;   // seq >= (inclusive). Absent = no lower bound.
+  optional uint64 to_seq         = 5;   // seq <= (inclusive). Absent = no upper bound.
+  repeated MetadataFilter metadata = 6; // Equality on metadata fields.
+  // Result shape.
+  QueryResult result          = 7;      // Defaults to RECORDS (=0).
+  string aggregate_field      = 8;      // COUNT_DISTINCT/MIN/MAX/DISTINCT_VALUES target. "" = use seq.
+  // Anti-join (NOT EXISTS): drop filtered records whose join_key value also
+  // appears on a record matching peer_event_types.
+  AbsentMatch absent          = 9;
+  // Paging / order.
+  int32 limit                  = 10;    // 0 = unlimited. Ignored for aggregations.
+  bool   descending            = 11;    // Order records/values by seq descending.
+}
+message MetadataFilter {
+  string key   = 1;
+  string value = 2;
+}
+message AbsentMatch {
+  repeated string peer_event_types = 1;  // Event types that "complete" a group (e.g. turn_completed).
+  string join_key                  = 2;  // Metadata field joining candidates to peers (e.g. turn_id).
+}
+enum QueryResult {
+  RECORDS         = 0;
+  COUNT           = 1;
+  COUNT_DISTINCT  = 2;
+  MIN             = 3;
+  MAX             = 4;
+  EXISTS          = 5;
+  DISTINCT_VALUES = 6;
+}
+message QueryResponse {
+  oneof result {
+    RecordsResult        records         = 1;
+    uint64               count           = 2;
+    bool                 exists          = 3;
+    uint64               count_distinct  = 4;
+    uint64               min             = 5;
+    uint64               max             = 6;
+    DistinctValuesResult distinct_values = 7;
+  }
+}
+message RecordsResult {
+  repeated Record records = 1;
+}
+message DistinctValuesResult {
+  repeated string values = 1;
+}
+
+// ─── Subscribe (event-type push) ──────────────────────────────────────────
+
+message SubscribeRequest {
+  string namespace       = 1;
+  string stream          = 2;
+  repeated string event_types = 3;  // subscribe to these event types
+  string consumer_group  = 4;       // for offset tracking
+  string consumer_id     = 5;       // unique consumer within group
+}
+
+// ─── Management API ──────────────────────────────────────────────────────
+
+message CreateStreamRequest {
+  string namespace = 1;
+  string stream    = 2;
+  // Optional quota settings
+  uint64 max_records = 3;  // 0 = unlimited
+  uint64 max_bytes   = 4;  // 0 = unlimited
+}
+
+message CreateStreamResponse {
+  uint32 namespace_id = 1;
+  uint64 stream_id    = 2;
+  bool   created      = 3;  // false if already existed
+}
+
+message DeleteStreamRequest {
+  string namespace = 1;
+  string stream    = 2;
+}
+
+message DeleteStreamResponse {
+  bool   deleted = 1;
+  uint64 deleted_count = 2;  // number of records marked deleted
+}