@substrio/sdk 0.0.0-stage → 0.1.0

package/substrio.mjs

@@ -0,0 +1,3928 @@
+/**
+ * Substrio JavaScript SDK: v0.1.0
+ *
+ * Zero dependencies. Single file. AI-friendly API.
+ *
+ * Usage:
+ *   import Substrio from '@substrio/sdk'
+ *   const db = new Substrio({ url: 'http://localhost:9000', key: 'master-key' })
+ *   const docs = await db.col('users').find({ age: { $gt: 25 } })
+ */
+
+import { QueryBuilder, bytesToBase64 } from './substrio-qx.mjs';
+import { KvTcp as KvWireTcp } from './substrio_kv_tcp.mjs';
+import { bindOperations, attachOperations } from './substrio_operation_client.mjs';
+
+// Error codes: generated from src/substrio/api/substrio_error.h and ERROR_TABLE in
+// src/substrio/api/substrio_error_strings.cpp (scripts/gen_errors.mjs); never edit by hand.
+export { SUBSTRIO_ERRORS } from './substrio_errors.mjs';
+
+// ─────────────────────────────────────────────────────────────────────────────
+// SubstrioError: structured error from server responses
+// ─────────────────────────────────────────────────────────────────────────────
+
+const _RETRYABLE = new Set(['RETRY', 'TRANSACTION_CONFLICT', 'RATE_LIMIT_EXCEEDED', 'CONCURRENT_LIMIT', 'TIMEOUT', 'QUERY_TIMEOUT']);
+const _AUTH      = new Set(['TOKEN_EXPIRED', 'TOKEN_INVALID', 'TOKEN_REVOKED', 'SESSION_EXPIRED', 'CREDENTIAL_REQUIRED', 'OAUTH_INVALID', 'INSUFFICIENT_PERMISSIONS']);
+const _QUOTA     = new Set(['STORAGE_QUOTA_EXCEEDED', 'DOCUMENT_QUOTA_EXCEEDED', 'BANDWIDTH_QUOTA_EXCEEDED', 'RATE_LIMIT_EXCEEDED', 'REQUEST_TOO_LARGE', 'CONCURRENT_LIMIT', 'COLLECTION_LIMIT', 'INDEX_LIMIT', 'FUNCTION_LIMIT']);
+const _NOT_FOUND = new Set(['KEY_NOT_FOUND', 'FILE_NOT_FOUND', 'TENANT_NOT_FOUND', 'COLLECTION_NOT_FOUND', 'FUNCTION_NOT_FOUND', 'THREAD_NOT_FOUND', 'MESSAGE_NOT_FOUND', 'ENDPOINT_NOT_FOUND']);
+
+export class SubstrioError extends Error {
+    constructor(status, code, message, body) {
+        super(message);
+        this.name = 'SubstrioError';
+        this.status = status;
+        this.code = code;
+        this.body = body;
+    }
+
+    /**
+     * The error for a failed response: `parsed` is the body (the substrio error
+     * envelope when it parses as one). The message is the error followed by
+     * its detail, the specific text the server gave ("Invalid argument:
+     * Invalid mode. Use: ...").
+     */
+    static fromResponse(status, parsed) {
+        if (!parsed || typeof parsed !== 'object') {
+            return new SubstrioError(status, '', parsed || `HTTP ${status}`, parsed);
+        }
+        const head = parsed.error || parsed.message || '';
+        const msg = head && parsed.detail && parsed.detail !== head
+            ? `${head}: ${parsed.detail}`
+            : (head || parsed.detail || JSON.stringify(parsed));
+        return new SubstrioError(status, parsed.code || '', msg, parsed);
+    }
+
+    /** True if this error is transient and the operation should be retried */
+    get isRetryable() { return _RETRYABLE.has(this.code); }
+
+    /** True if this is an authentication or authorization error */
+    get isAuth() { return _AUTH.has(this.code); }
+
+    /** True if this is a quota or rate-limiting error */
+    get isQuota() { return _QUOTA.has(this.code); }
+
+    /** True if the requested resource was not found */
+    get isNotFound() { return _NOT_FOUND.has(this.code); }
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Internal helpers
+// ─────────────────────────────────────────────────────────────────────────────
+
+const JSON_TYPE = 'application/json';
+
+function qs(params) {
+    if (!params) return '';
+    const parts = [];
+    for (const [k, v] of Object.entries(params)) {
+        if (v !== undefined && v !== null) parts.push(`${encodeURIComponent(k)}=${encodeURIComponent(v)}`);
+    }
+    return parts.length ? '?' + parts.join('&') : '';
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Detect runtime: Node.js gets low-level HTTP, browsers get fetch()
+// ─────────────────────────────────────────────────────────────────────────────
+
+const _isNode = typeof globalThis.process !== 'undefined'
+    && globalThis.process.versions?.node != null;
+
+// Lazy-loaded Node.js modules (only imported once, on first use)
+let _http = null, _https = null;
+if (_isNode) {
+    // Top-level await not needed: createRequire works synchronously in ESM
+    const { createRequire } = await import('node:module');
+    const _require = createRequire(import.meta.url);
+    _https = _require('node:https');
+    _http  = _require('node:http');
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// HTTP engine: shared by all classes
+//
+// Node.js: raw https.request() with persistent keep-alive agent.
+// Zero abstraction overhead: no fetch(), no Response object, no Headers.
+// Measured: 0.12ms p50 per request vs ~0.5ms with fetch() under burst.
+//
+// Browser: falls back to fetch() (browsers already optimize connections).
+// ─────────────────────────────────────────────────────────────────────────────
+
+class Http {
+    constructor(baseUrl, headers, url, tenant, key) {
+        // Strip trailing slash
+        this.base = baseUrl.replace(/\/+$/, '');
+        this.headers = headers;
+        // WS connection info for onSnapshot()
+        this._url = url || baseUrl;
+        this._tenant = tenant || 'default';
+        this._key = key || null;
+        // RYOW: session consistency, tracks highest write timestamp
+        this._sessionTs = '0';
+        // Lifecycle
+        this._closed = false;
+
+        // ── Parse base URL once ──────────────────────────────────────────
+        const parsed = new URL(this.base);
+        this._hostname = parsed.hostname;
+        this._port = parseInt(parsed.port || (parsed.protocol === 'https:' ? '443' : '80'), 10);
+        this._isHttps = parsed.protocol === 'https:';
+        this._basePath = parsed.pathname === '/' ? '' : parsed.pathname;
+
+        // ── Persistent keep-alive agent (Node.js only) ───────────────────
+        // One TLS session, reused across all requests. No handshake per request.
+        if (_isNode) {
+            const Mod = this._isHttps ? _https : _http;
+            this._agent = new Mod.Agent({
+                keepAlive: true,             // Reuse TCP+TLS connections
+                keepAliveMsecs: 30_000,      // 30s idle before close
+                maxSockets: 64,              // Max concurrent connections
+                maxFreeSockets: 16,          // Idle connections ready for reuse
+                scheduling: 'fifo',          // Fair distribution
+                ...(this._isHttps ? { rejectUnauthorized: false } : {}),
+            });
+        } else {
+            this._agent = null;
+        }
+    }
+
+    /** Abort all in-flight requests and mark this instance as closed. */
+    close() {
+        if (!this._closed) {
+            this._closed = true;
+            if (this._agent) {
+                this._agent.destroy();
+                this._agent = null;
+            }
+        }
+    }
+
+    // ── Node.js low-level request ────────────────────────────────────────
+    // Absolute minimum: send bytes → receive bytes → resolve.
+    // No abstraction layers. No parsing. No header scanning.
+
+    /** @internal Node.js raw request: returns { status, headers, body } */
+    _nodeReq(method, path, body, extraHeaders, _retry) {
+        return new Promise((resolve, reject) => {
+            const headers = extraHeaders
+                ? { ...this.headers, ...extraHeaders }
+                : { ...this.headers };
+
+            // RYOW: session consistency
+            if (this._sessionTs !== '0') {
+                headers['X-Substrio-After'] = this._sessionTs;
+            }
+
+            let payload;
+            if (body !== undefined) {
+                if (typeof body === 'string') {
+                    payload = body;
+                } else if (body instanceof Uint8Array) {
+                    // A view over the same memory: no copy.
+                    payload = Buffer.from(body.buffer, body.byteOffset, body.byteLength);
+                } else if (body instanceof ArrayBuffer) {
+                    payload = Buffer.from(body);
+                } else {
+                    payload = JSON.stringify(body);
+                }
+                headers['Content-Length'] = Buffer.byteLength(payload);
+            }
+
+            let settled = false;
+            const Mod = this._isHttps ? _https : _http;
+            const req = Mod.request({
+                hostname: this._hostname,
+                port: this._port,
+                path: this._basePath + path,
+                method,
+                headers,
+                agent: this._agent,
+            }, (res) => {
+                // Fast body accumulation
+                const chunks = [];
+                res.on('data', (chunk) => chunks.push(chunk));
+                res.on('end', () => {
+                    if (settled) return;
+                    settled = true;
+                    const raw = chunks.length === 1
+                        ? chunks[0].toString()
+                        : Buffer.concat(chunks).toString();
+
+                    // RYOW: direct header access (no iteration)
+                    const ts = res.headers['x-substrio-ts'];
+                    if (ts && ts > this._sessionTs) {
+                        this._sessionTs = ts;
+                    }
+
+                    // Store raw headers ref for lazy profiling access
+                    this._rawHeaders = res.headers;
+
+                    resolve({ status: res.statusCode, body: raw });
+                });
+            });
+
+            req.on('error', (err) => {
+                if (settled) return;
+                settled = true;
+                // Destroy the socket so the keep-alive agent doesn't reuse a dead connection
+                if (req.socket) req.socket.destroy();
+                // Auto-retry once on stale keep-alive socket (EPIPE/ECONNRESET/parse errors)
+                if (!_retry && (err.code === 'EPIPE' || err.code === 'ECONNRESET' || err.code === 'HPE_INVALID_CONSTANT')) {
+                    resolve(this._nodeReq(method, path, body, extraHeaders, true));
+                    return;
+                }
+                if (err.code === 'ECONNREFUSED') {
+                    reject(new SubstrioError(0, 'ECONNREFUSED',
+                        `Cannot connect to ${this.base}: is the server running?`));
+                } else {
+                    reject(err);
+                }
+            });
+
+            if (payload !== undefined) {
+                try { req.write(payload); } catch (_) { /* write-after-end */ }
+            }
+            req.end();
+        });
+    }
+
+    /** Profiling headers: lazy getter, only computed when accessed (never on hot path) */
+    get _lastHeaders() {
+        if (!this._rawHeaders) return {};
+        const prof = {};
+        for (const key in this._rawHeaders) {
+            if (key.startsWith('x-substrio-')) {
+                prof[key] = this._rawHeaders[key];
+            }
+        }
+        return prof;
+    }
+
+    async req(method, path, body, extra) {
+        // ── Node.js fast path ────────────────────────────────────────────
+        // TOTAL HOT PATH: _nodeReq → JSON.parse → return. Nothing else.
+        if (_isNode) {
+            const r = await this._nodeReq(method, path, body, extra);
+            if (r.status >= 200 && r.status < 300) {
+                try { return JSON.parse(r.body); } catch { return r.body; }
+            }
+            // Error path (cold: doesn't need to be fast)
+            let parsed;
+            try { parsed = JSON.parse(r.body); } catch { parsed = r.body; }
+            throw SubstrioError.fromResponse(r.status, parsed);
+        }
+
+        // ── Browser fallback (fetch) ─────────────────────────────────────
+        const url = this.base + path;
+        const headers = extra ? { ...this.headers, ...extra } : { ...this.headers };
+        if (this._sessionTs !== '0') headers['X-Substrio-After'] = this._sessionTs;
+        const opts = { method, headers };
+        if (body !== undefined) {
+            opts.body = (typeof body === 'string' || body instanceof Uint8Array || body instanceof ArrayBuffer)
+                ? body : JSON.stringify(body);
+        }
+        const res = await fetch(url, opts);
+        const text = await res.text();
+        const writeTs = res.headers.get('x-substrio-ts');
+        if (writeTs && writeTs > this._sessionTs) this._sessionTs = writeTs;
+
+        if (res.ok || res.status === 202) {
+            try { return JSON.parse(text); } catch { return text; }
+        }
+        let parsed;
+        try { parsed = JSON.parse(text); } catch { parsed = null; }
+        throw SubstrioError.fromResponse(res.status, parsed);
+    }
+
+    // Raw request: returns the response object (for streaming)
+    async raw(method, path, body, extra) {
+        if (_isNode) {
+            const r = await this._nodeReq(method, path, body, extra);
+            if (r.status >= 200 && r.status < 300) return r;
+            let parsed;
+            try { parsed = JSON.parse(r.body); } catch { parsed = r.body; }
+            throw SubstrioError.fromResponse(r.status, parsed);
+        }
+        // Browser fallback
+        const url = this.base + path;
+        const headers = extra ? { ...this.headers, ...extra } : { ...this.headers };
+        const opts = { method, headers };
+        if (body !== undefined) {
+            opts.body = (typeof body === 'string' || body instanceof Uint8Array || body instanceof ArrayBuffer)
+                ? body : JSON.stringify(body);
+        }
+        const res = await fetch(url, opts);
+        if (!res.ok) {
+            const text = await res.text();
+            let parsed;
+            try { parsed = JSON.parse(text); } catch { parsed = null; }
+            throw SubstrioError.fromResponse(res.status, parsed);
+        }
+        return res;
+    }
+}
+
+
+// ─────────────────────────────────────────────────────────────────────────────
+
+// Query: fluent chainable query builder
+// ─────────────────────────────────────────────────────────────────────────────
+
+export class Query {
+    constructor(http, col) {
+        this.http = http;
+        this.col = col;
+        this._where = null;
+        this._limit = null;
+        this._skip = null;
+        this._sort = null;
+        this._select = null;
+        this._count = false;
+    }
+
+    /** Set the where clause. */
+    where(filter) { this._where = filter; return this; }
+
+    /** Limit results. */
+    limit(n) { this._limit = n; return this; }
+
+    /** Skip results. */
+    skip(n) { this._skip = n; return this; }
+
+    /** Sort results. e.g. sort({ age: 1 }) or sort({ age: -1 }) */
+    sort(spec) { this._sort = spec; return this; }
+
+    /** Select fields. e.g. select(['name', 'age']) */
+    select(fields) { this._select = fields; return this; }
+
+    /** Count-only mode: returns just the count, no data. */
+    count(val = true) { this._count = val; return this; }
+
+    /** Execute the query via bytecode: compiles to QX and sends via /_qx. */
+    async run() {
+        const qb = new BoundQueryBuilder(this.http, this.col);
+        QueryBuilder.compileFilter(qb, this._where || {}, {
+            sort: this._sort,
+            limit: this._limit,
+            skip: this._skip,
+            select: this._select,
+            count: this._count
+        });
+        return qb.run();
+    }
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// BoundQueryBuilder: QueryBuilder bound to a collection + HTTP client
+// Uses /_qx endpoint for zero-parse bytecode queries
+// ─────────────────────────────────────────────────────────────────────────────
+
+export class BoundQueryBuilder extends QueryBuilder {
+    constructor(http, col, extraHeaders) {
+        super();
+        this._http = http;
+        this._col = col;
+        this._extraHeaders = extraHeaders || undefined;
+    }
+
+    /** Execute the bytecode query via /_qx endpoint. */
+    async run() {
+        const bytes = this.toUint8Array();
+        return this._http.req('POST', `/v1/${this._col}/_qx`, bytes,
+            { ...this._extraHeaders, 'Content-Type': 'application/octet-stream' });
+    }
+}
+
+// Re-export QueryBuilder for direct use (e.g. in CF SDK or manual construction)
+export { QueryBuilder };
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Collection: the core data primitive
+// ─────────────────────────────────────────────────────────────────────────────
+
+export class Collection {
+    constructor(http, name) {
+        this.http = http;
+        this.name = name;
+    }
+
+    /**
+     * Subscribe to ALL changes on this collection (Firestore-style).
+     * Returns an unsubscribe function.
+     * @param {function} callback - receives { type, collection, operation, doc }
+     * @returns {function} unsubscribe: call to stop listening and close connection
+     */
+    onSnapshot(callback) {
+        const rt = new Realtime(this.http._url, this.http._tenant, this.http._key);
+        rt.ready.then(() => {
+            rt.subscribeCollection(this.name);
+            rt.on('change', callback);
+        });
+        return () => {
+            rt.unsubscribeCollection(this.name);
+            rt.close();
+        };
+    }
+
+    /**
+     * CDC / Resumable Change Stream.
+     * Returns a ChangeStream that tracks _seq for resume-on-disconnect.
+     * _seq (a change history position) comes only on an app that keeps its
+     * change history; without one a change has no _seq and nothing resumes.
+     * @param {function} callback - receives { type, collection, operation, _seq?, _ts, doc, ... }
+     * @param {object} [options] - { resumeAfter: string }: resume after this _seq
+     * @returns {ChangeStream}
+     */
+    watch(callback, options = {}) {
+        return new ChangeStream(this.http._url, this.http._tenant, this.http._key, this.name, callback, options);
+    }
+
+    // ── CRUD ──────────────────────────────────────────────────────────────
+
+    /** Insert one document or an array of documents. */
+    async add(doc) {
+        if (Array.isArray(doc)) {
+            const results = [];
+            for (const d of doc) {
+                results.push(await this.add(d));
+            }
+            return results;
+        }
+        // The server ingests JSON (substrio_parse_insert_body); req sends the
+        // document as JSON.
+        return this.http.req('POST', `/v1/${this.name}`, doc);
+    }
+
+    /** Get a document by ID. */
+    async get(id) {
+        return this.http.req('GET', `/v1/${this.name}/${encodeURIComponent(id)}`);
+    }
+
+    /** Replace all fields on a document by ID (PATCH + $set). */
+    async set(id, doc) {
+        return this.http.req('PATCH', `/v1/${this.name}/${encodeURIComponent(id)}`, { $set: doc });
+    }
+
+    /** Partial update a document by ID. Accepts $set, $unset, $inc, etc. */
+    async update(id, ops) {
+        return this.http.req('PATCH', `/v1/${this.name}/${encodeURIComponent(id)}`, ops);
+    }
+
+    /** Delete a document by ID. */
+    async delete(id) {
+        return this.http.req('DELETE', `/v1/${this.name}/${encodeURIComponent(id)}`);
+    }
+
+    /** Drop the entire collection. */
+    async drop() {
+        return this.http.req('DELETE', `/v1/_meta/collections/${encodeURIComponent(this.name)}`);
+    }
+
+    // ── Query builder ────────────────────────────────────────────────────
+
+    /** Start a fluent query chain. e.g. collection.query().where({age:{$gt:25}}).limit(5).run() */
+    query() { return new Query(this.http, this.name); }
+
+    /**
+     * Start a bytecode query builder (zero-parse path).
+     * Returns a BoundQueryBuilder with .eq(), .gt(), .sort(), etc.
+     * Call .run() to execute via /_qx endpoint.
+     * @returns {BoundQueryBuilder}
+     */
+    qx() { return new BoundQueryBuilder(this.http, this.name); }
+
+    // ── Shorthand query methods ──────────────────────────────────────────
+
+    /**
+     * Find documents matching a filter.
+     * @param {object} filter - Where clause (e.g. { age: { $gt: 25 } })
+     * @param {object} [opts] - { limit, skip, select, sort, cursor }
+     * @returns {Promise<{ data: object[], count: number }>}
+     */
+    async find(filter = {}, opts = {}) {
+        const qb = this.qx();
+        QueryBuilder.compileFilter(qb, filter, opts);
+        return qb.run();
+    }
+
+    /**
+     * Find a single document matching a filter.
+     * @param {object} filter - Where clause (e.g. { name: { $eq: 'Alice' } })
+     * @param {object} [opts] - { select, sort }
+     * @returns {Promise<object|null>} First matching document or null
+     */
+    async findOne(filter = {}, opts = {}) {
+        const r = await this.find(filter, { ...opts, limit: 1 });
+        return (r && r.data && r.data.length > 0) ? r.data[0] : null;
+    }
+
+    /**
+     * Get a single document by its OID.
+     * @param {string} id - Document OID
+     * @returns {Promise<object>}
+     */
+    async findById(id) {
+        return this.get(id);
+    }
+
+    /**
+     * Check if any document matches the filter.
+     * @param {object} filter - Where clause
+     * @returns {Promise<boolean>}
+     */
+    async exists(filter = {}) {
+        const r = await this.find(filter, { limit: 1, select: ['_id'] });
+        return r && r.data && r.data.length > 0;
+    }
+
+    /**
+     * Insert or update a document. If filter matches an existing doc, update it;
+     * otherwise insert the doc.
+     * @param {object} filter - Where clause to find existing doc
+     * @param {object} doc - Document to insert or fields to $set on update
+     * @returns {Promise<object>} The inserted or updated result
+     */
+    async upsert(filter, doc) {
+        const existing = await this.findOne(filter);
+        if (existing) {
+            return this.set(existing._id, doc);
+        }
+        return this.add(doc);
+    }
+
+    /**
+     * Delete all documents matching a filter.
+     * @param {object} filter - Where clause
+     * @returns {Promise<object>} Deletion result with count
+     */
+    async deleteWhere(filter) {
+        return this.rawQuery({ where: filter, $delete: true });
+    }
+
+    /**
+     * Update all documents matching a filter with the given updates.
+     * @param {object} filter - Where clause
+     * @param {object} updates - Fields to $set on each matched document
+     * @returns {Promise<object>} Update result
+     */
+    async updateWhere(filter, updates) {
+        const matched = await this.find(filter);
+        if (!matched || !matched.data) return { updated: 0 };
+        let count = 0;
+        for (const doc of matched.data) {
+            await this.set(doc._id, updates);
+            count++;
+        }
+        return { updated: count };
+    }
+
+    /**
+     * Send a raw query body via bytecode. Compiles filter from the body.
+     * Falls back to _query for features not yet in QX bytecode (explain, timeout).
+     * @param {object} body - Query body (compiled to bytecode)
+     * @returns {Promise<object>}
+     */
+    async rawQuery(body) {
+        // ── Input Validation (mirrors the old _query endpoint) ──────────
+        const KNOWN_KEYS = new Set([
+            'where', 'sort', 'limit', 'skip', 'select', 'count',
+            '$delete', '$exec', 'explain', 'timeout', '$whereJS',
+            // Aggregation keys
+            'sum', 'avg', 'min', 'max', 'variance', 'stddev', 'percentile',
+            'top', 'bottom', 'histogram', 'range_count',
+            // Pipeline
+            '$pipeline',
+            // Other
+            'rank', 'k', 'buckets', 'gte', 'lte', 'noCache',
+        ]);
+        const KNOWN_OPS = new Set([
+            '$eq', '$ne', '$gt', '$gte', '$lt', '$lte',
+            '$in', '$nin', '$regex', '$exists', '$type', '$size',
+            '$all', '$elemMatch', '$not',
+            '$knn', '$box', '$geoWithin', '$geoIntersects',
+        ]);
+        const KNOWN_WHERE_OPS = new Set(['$and', '$or', '$nor', '$not', '$whereJS']);
+
+        // Reject $where: suggest $whereJS
+        if ('$where' in body || (body.where && '$where' in body.where)) {
+            throw new SubstrioError(400, 'INVALID_QUERY',
+                '$where is not supported in Substrio. Use $whereJS for JavaScript expression evaluation.');
+        }
+
+        // Reject unknown top-level $ keys (e.g. $sort, $foobar)
+        for (const k of Object.keys(body)) {
+            if (k.startsWith('$') && !KNOWN_KEYS.has(k)) {
+                const suggestion = k === '$sort' ? ' Did you mean "sort" (without $)?' :
+                    k === '$limit' ? ' Did you mean "limit" (without $)?' :
+                    k === '$skip' ? ' Did you mean "skip" (without $)?' : '';
+                throw new SubstrioError(400, 'INVALID_QUERY',
+                    `Unknown query operator "${k}".${suggestion} Supported: where, sort, limit, skip, select, count, $delete, $exec, explain.`);
+            }
+        }
+
+        // Validate limit type
+        if ('limit' in body && (typeof body.limit !== 'number' || !Number.isFinite(body.limit))) {
+            throw new SubstrioError(400, 'INVALID_QUERY',
+                'limit must be an integer');
+        }
+        // Validate skip type
+        if ('skip' in body && (typeof body.skip !== 'number' || !Number.isFinite(body.skip))) {
+            throw new SubstrioError(400, 'INVALID_QUERY',
+                'skip must be an integer');
+        }
+        // Validate sort type
+        if ('sort' in body && (typeof body.sort !== 'object' || body.sort === null || Array.isArray(body.sort))) {
+            throw new SubstrioError(400, 'INVALID_QUERY',
+                'sort must be an object (e.g. { age: 1 })');
+        }
+        // Validate sort direction values
+        if (body.sort && typeof body.sort === 'object') {
+            for (const [field, dir] of Object.entries(body.sort)) {
+                if (dir !== 1 && dir !== -1) {
+                    throw new SubstrioError(400, 'INVALID_QUERY',
+                        `sort direction for "${field}" must be 1 (ascending) or -1 (descending), got ${dir}`);
+                }
+            }
+        }
+        // Validate select type
+        if ('select' in body && !Array.isArray(body.select)) {
+            throw new SubstrioError(400, 'INVALID_QUERY',
+                'select must be an array of field names');
+        }
+        // Validate count type
+        if ('count' in body && typeof body.count !== 'boolean') {
+            throw new SubstrioError(400, 'INVALID_QUERY',
+                'count must be true or false');
+        }
+
+        // Validate where clause operators
+        const where = body.where;
+        if (where && typeof where === 'object') {
+            for (const [k, v] of Object.entries(where)) {
+                if (k.startsWith('$') && !KNOWN_WHERE_OPS.has(k)) {
+                    throw new SubstrioError(400, 'INVALID_QUERY',
+                        `Unknown query operator "${k}". Supported: $and, $or, $nor, $not, $whereJS, or use field-level operators.`);
+                }
+                // Validate field-level operators
+                if (!k.startsWith('$') && v && typeof v === 'object' && !Array.isArray(v)) {
+                    for (const op of Object.keys(v)) {
+                        if (op.startsWith('$') && !KNOWN_OPS.has(op)) {
+                            throw new SubstrioError(400, 'INVALID_QUERY',
+                                `Unknown field operator "${op}" on field "${k}". Supported: ${[...KNOWN_OPS].join(', ')}`);
+                        }
+                        // Validate $in/$nin must be arrays
+                        if ((op === '$in' || op === '$nin') && !Array.isArray(v[op])) {
+                            throw new SubstrioError(400, 'INVALID_QUERY',
+                                `${op} value for field "${k}" must be an array`);
+                        }
+                    }
+                }
+            }
+        }
+
+        // ── Aggregation keys → delegate to _agg() ───────────────────────
+        const AGG_KEYS = ['sum','avg','min','max','variance','stddev','percentile',
+                          'top','bottom','histogram','range_count'];
+        for (const k of AGG_KEYS) {
+            if (k in body) return this._agg(body);
+        }
+        const qb = this.qx();
+        // Extract known keys and compile to bytecode
+        const filter = body.where || {};
+        const opts = {};
+        if (body.sort) opts.sort = body.sort;
+        if (body.limit !== undefined) opts.limit = body.limit;
+        if (body.skip !== undefined) opts.skip = body.skip;
+        if (body.select) opts.select = body.select;
+        if (body.count) opts.count = body.count;
+        QueryBuilder.compileFilter(qb, filter, opts);
+        if (body.$delete) qb.deleteMatching();
+        if (body.$exec) qb.execOp(body.$exec);
+        if (body.explain) qb.explainOp();
+        if (body.timeout) qb.timeoutOp(body.timeout);
+        return qb.run();
+    }
+
+    /** Count documents matching a filter. */
+    async count(filter = {}) {
+        const r = await this.query().where(filter).count().run();
+        return (typeof r === 'object' && 'count' in r) ? r.count : r;
+    }
+
+    /** Run an aggregation pipeline. @param {Array} stages @param {object} [opts] @param {boolean} [opts.noCache] */
+    async pipeline(stages, opts = {}) {
+        // Route through _query endpoint (JSON): the QX bytecode pipeline encoder
+        // doesn't fully support all stages ($count, $join, $rerank, $bucket output,
+        // $unionWith sub-pipeline, $facet with $count, etc.)
+        return this.http.req('POST', `/v1/${this.name}/_query`, { $pipeline: stages });
+    }
+
+    // ── RAG sub-object ────────────────────────────────────────────────────
+
+    /** Lazy RAG sub-object: collection.rag.set(config), collection.rag.get(), collection.rag.delete(), collection.rag.drift(), collection.rag.reembed(), collection.rag.embed(text) */
+    get rag() {
+        if (!this._rag) {
+            const http = this.http, name = this.name;
+            this._rag = {
+                set: (config) => http.req('POST', `/v1/${name}/_rag`, config),
+                get: () => http.req('GET', `/v1/${name}/_rag`),
+                delete: () => http.req('DELETE', `/v1/${name}/_rag`),
+                drift: () => http.req('GET', `/v1/${name}/_rag/drift`),
+                reembed: (opts) => http.req('POST', `/v1/${name}/_rag/re-embed`, opts),
+                embed: (text) => http.req('POST', `/v1/${name}/_rag/embed`, { text }),
+            };
+        }
+        return this._rag;
+    }
+
+    /** Lazy Schema sub-object: collection.schema.set(rules), collection.schema.get(), collection.schema.delete() */
+    get schema() {
+        if (!this._schema) {
+            const http = this.http, name = this.name;
+            this._schema = {
+                set: (config) => http.req('POST', `/v1/${name}/_schema`, config),
+                get: () => http.req('GET', `/v1/${name}/_schema`),
+                delete: () => http.req('DELETE', `/v1/${name}/_schema`),
+            };
+        }
+        return this._schema;
+    }
+
+    // ── Vector / semantic search ──────────────────────────────────────────
+
+    /**
+     * Vector/semantic search.
+     * @param {string} query - Search query text
+     * @param {object} [opts] - { k, mode, filter, select, decay, boost_feedback }
+     */
+    async search(query, opts = {}) {
+        const config = {
+            query: typeof query === 'string' ? query : (query.query || query),
+            k: opts.k || 10,
+        };
+        if (opts.mode) config.mode = opts.mode;
+        if (opts.filter) config.filter = opts.filter;
+        if (opts.select) config.select = opts.select;
+        if (opts.decay) config.decay = opts.decay;
+        if (opts.boost_feedback !== undefined) config.boost_feedback = opts.boost_feedback;
+        if (opts.limit) config.limit = opts.limit;
+        const qb = this.qx();
+        qb.searchOp(config);
+        return qb.run();
+    }
+
+    /**
+     * RAG context retrieval: search + return context, citations.
+     * @param {string} question
+     * @param {object} [opts] - { k, filter }
+     * @returns {Promise<object>} - { context, citations, search_hits, chunks_used, collection }
+     */
+    async ask(question, opts = {}) {
+        const body = { question };
+        if (opts.k !== undefined) body.search_k = opts.k;
+        if (opts.filter) body.filter = opts.filter;
+        return this.http.req('POST', `/v1/${this.name}/_ask`, body);
+    }
+
+    /**
+     * Cross-vector search: search across multiple named vector fields with RRF fusion.
+     * @param {string} query - Text to search for
+     * @param {object} [opts] - { fields, k, limit }
+     * @returns {Promise<object>} - { data, count, fields_searched, fields_skipped }
+     */
+    async crossSearch(query, opts = {}) {
+        const body = { query };
+        if (opts.fields) body.fields = opts.fields;
+        if (opts.k !== undefined) body.k = opts.k;
+        if (opts.limit !== undefined) body.limit = opts.limit;
+        return this.http.req('POST', `/v1/${this.name}/_cross_search`, body);
+    }
+
+    /** Expand context window around a chunk document. */
+    async expand(opts) {
+        const body = {};
+        if (opts.doc_id) body.doc_id = opts.doc_id;
+        if (opts.before !== undefined) body.before = opts.before;
+        if (opts.after !== undefined) body.after = opts.after;
+        return this.http.req('POST', `/v1/${this.name}/_expand`, body);
+    }
+
+    // ── Feedback sub-object ───────────────────────────────────────────────
+
+    /** Lazy feedback sub-object: collection.feedback.record(signal), .list(opts), .stats() */
+    get feedback() {
+        if (!this._feedback) {
+            const http = this.http, name = this.name;
+            this._feedback = {
+                record: (signal) => http.req('POST', `/v1/${name}/_feedback`, signal),
+                list: (opts) => http.req('GET', `/v1/${name}/_feedback${qs(opts)}`),
+                stats: () => http.req('GET', `/v1/${name}/_feedback/analytics`),
+            };
+        }
+        return this._feedback;
+    }
+
+    // ── Analytics & Stats ─────────────────────────────────────────────────
+
+    /** Get search analytics. */
+    async analytics(opts) {
+        return this.http.req('GET', `/v1/${this.name}/_analytics/search${qs(opts)}`);
+    }
+
+    /** Get collection stats. */
+    async stats() {
+        return this.http.req('GET', `/v1/${this.name}/_stats`);
+    }
+
+    // ── Namespaces ────────────────────────────────────────────────────────
+
+    /** Get a namespace-scoped collection ref. */
+    namespace(name) {
+        return new NamespacedCollection(this.http, this.name, name);
+    }
+
+    /** List all namespaces. */
+    async namespaces() {
+        return this.http.req('GET', `/v1/${this.name}/_namespaces`);
+    }
+
+    /** Delete a namespace. */
+    async deleteNamespace(name) {
+        return this.http.req('DELETE', `/v1/${this.name}/_namespaces/${encodeURIComponent(name)}`);
+    }
+
+    /** Get namespace stats. */
+    async namespaceStats(name) {
+        return this.http.req('GET', `/v1/${this.name}/_namespaces/${encodeURIComponent(name)}/stats`);
+    }
+
+    // ── Join ──────────────────────────────────────────────────────────────
+
+    /**
+     * Cross-collection $join query.
+     * @param {object|object[]} join - { from, localField, foreignField, as } or array of them
+     * @param {object} [opts] - { where, limit, select }
+     */
+    async join(join, opts = {}) {
+        // Route through _query endpoint (JSON): QX bytecode join encoder
+        // doesn't populate foreign fields correctly in all cases.
+        const body = { $join: join };
+        if (opts.where) body.where = opts.where;
+        if (opts.limit !== undefined) body.limit = opts.limit;
+        if (opts.select) body.select = opts.select;
+        return this.http.req('POST', `/v1/${this.name}/_query`, body);
+    }
+
+    // ── Import/Export ─────────────────────────────────────────────────────
+
+    /** Bulk import documents. */
+    async import(data, opts = {}) {
+        const format = opts.format || 'ndjson';
+        const body = typeof data === 'string' ? data : JSON.stringify(data);
+        const ct = format === 'csv' ? 'text/csv' : 'application/x-ndjson';
+        return this.http.req('POST', `/v1/${this.name}/_import${qs({ format })}`, body, { 'Content-Type': ct });
+    }
+
+    /** Export documents. */
+    async export(opts = {}) {
+        return this.http.req('GET', `/v1/${this.name}/_export${qs(opts)}`);
+    }
+
+    // ── Index-Only Analytics ──────────────────────────────────────────────
+    // Zero-hydration columnar aggregation: pure B-tree cursor walk.
+
+    /** @internal Shared analytics helper: bytecode aggregation via /_qx
+     *  Supports both calling conventions:
+     *    _agg('sum', 'field')          : new string-based (from sugar methods)
+     *    _agg({ sum: 'field' })        : legacy object-based (backward compat)
+     */
+    _agg(subType, field, params) {
+        // Backward compat: _agg({ sum: 'revenue', ...opts })
+        if (typeof subType === 'object' && subType !== null) {
+            const body = subType;
+            const ops = ['sum','avg','min','max','variance','stddev','percentile',
+                         'top','bottom','histogram','range_count'];
+            for (const op of ops) {
+                if (op in body) {
+                    return this._agg(op, body[op],
+                        { rank: body.rank, k: body.k, buckets: body.buckets,
+                          gte: body.gte, lte: body.lte });
+                }
+            }
+            throw new Error(`_agg: no recognized aggregation op in ${JSON.stringify(body)}`);
+        }
+        const qb = this.qx();
+        switch (subType) {
+            case 'sum':         qb.aggSum(field); break;
+            case 'avg':         qb.aggAvg(field); break;
+            case 'min':         qb.aggMin(field); break;
+            case 'max':         qb.aggMax(field); break;
+            case 'variance':    qb.aggVariance(field); break;
+            case 'stddev':      qb.aggStddev(field); break;
+            case 'percentile':  qb.aggPercentile(field, params.rank); break;
+            case 'top':         qb.aggTop(field, params.k); break;
+            case 'bottom':      qb.aggBottom(field, params.k); break;
+            case 'histogram':   qb.aggHistogram(field, params.buckets); break;
+            case 'range_count': qb.aggRangeCount(field, params.gte, params.lte); break;
+            default: throw new Error(`_agg: unknown aggregation type '${subType}'`);
+        }
+        return qb.run();
+    }
+
+    /** Index-only SUM of a numeric field. */
+    async sum(field) { return this._agg('sum', field); }
+
+    /** Index-only AVG of a numeric field. */
+    async avg(field) { return this._agg('avg', field); }
+
+    /** Index-only MIN of a field. */
+    async min(field) { return this._agg('min', field); }
+
+    /** Index-only MAX of a field. */
+    async max(field) { return this._agg('max', field); }
+
+    /** Index-only variance (Welford's algorithm). */
+    async variance(field) { return this._agg('variance', field); }
+
+    /** Index-only standard deviation. */
+    async stddev(field) { return this._agg('stddev', field); }
+
+    /** Index-only percentile (0.0–1.0 rank). */
+    async percentile(field, rank) { return this._agg('percentile', field, { rank }); }
+
+    /** Index-only top-K largest values. */
+    async top(field, k) { return this._agg('top', field, { k }); }
+
+    /** Index-only bottom-K smallest values. */
+    async bottom(field, k) { return this._agg('bottom', field, { k }); }
+
+    /** Index-only histogram with N equal-width buckets. */
+    async histogram(field, buckets) { return this._agg('histogram', field, { buckets }); }
+
+    /** Index-only range count (gte..lte). */
+    async rangeCount(field, gte, lte) { return this._agg('range_count', field, { gte, lte }); }
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// NamespacedCollection: namespace-scoped operations
+// ─────────────────────────────────────────────────────────────────────────────
+
+class NamespacedCollection {
+    constructor(http, collection, namespace) {
+        this.http = http;
+        this.collection = collection;
+        this.namespace = namespace;
+        this._nsHeader = { 'X-Substrio-Namespace': namespace };
+    }
+
+    async add(doc) {
+        // JSON, as Collection.add sends it.
+        return this.http.req('POST', `/v1/${this.collection}`, doc, this._nsHeader);
+    }
+
+    async find(query = {}, opts = {}) {
+        const qb = new BoundQueryBuilder(this.http, this.collection, this._nsHeader);
+        QueryBuilder.compileFilter(qb, query, opts);
+        return qb.run();
+    }
+
+    async search(query, opts = {}) {
+        const config = {
+            query: typeof query === 'string' ? query : (query.query || query),
+            k: opts.k || 10,
+        };
+        if (opts.mode) config.mode = opts.mode;
+        if (opts.filter) config.filter = opts.filter;
+        if (opts.select) config.select = opts.select;
+        const qb = new BoundQueryBuilder(this.http, this.collection, this._nsHeader);
+        qb.searchOp(config);
+        return qb.run();
+    }
+
+    async delete(id) {
+        return this.http.req('DELETE', `/v1/${this.collection}/${encodeURIComponent(id)}`, undefined, this._nsHeader);
+    }
+
+    async deleteBy(query) {
+        const qb = new BoundQueryBuilder(this.http, this.collection, this._nsHeader);
+        QueryBuilder.compileFilter(qb, query);
+        qb.deleteMatching();
+        return qb.run();
+    }
+
+    async count(query = {}) {
+        const qb = new BoundQueryBuilder(this.http, this.collection, this._nsHeader);
+        QueryBuilder.compileFilter(qb, query);
+        qb.count();
+        const r = await qb.run();
+        return (typeof r === 'object' && 'count' in r) ? r.count : r;
+    }
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Thread: conversation thread primitive
+// ─────────────────────────────────────────────────────────────────────────────
+
+export class Thread {
+    constructor(http, id, data) {
+        this.http = http;
+        this.id = id;
+        if (data) Object.assign(this, data);
+    }
+
+    /** Fetch thread metadata. */
+    async get() {
+        const d = await this.http.req('GET', `/v1/_threads/${encodeURIComponent(this.id)}`);
+        Object.assign(this, d);
+        return d;
+    }
+
+    /** Update thread config/metadata. */
+    async update(patch) {
+        return this.http.req('PATCH', `/v1/_threads/${encodeURIComponent(this.id)}`, patch);
+    }
+
+    /** Delete this thread and all its messages. */
+    async delete() {
+        return this.http.req('DELETE', `/v1/_threads/${encodeURIComponent(this.id)}`);
+    }
+
+    /** Add a message to the thread. */
+    async addMessage(message) {
+        if (typeof message === 'string') message = { role: 'user', content: message };
+        return this.http.req('POST', `/v1/_threads/${encodeURIComponent(this.id)}/messages`, message);
+    }
+
+    /** List messages in this thread. */
+    async messages(opts) {
+        return this.http.req('GET', `/v1/_threads/${encodeURIComponent(this.id)}/messages${qs(opts)}`);
+    }
+
+    /** Delete a specific message by ID. */
+    async deleteMessage(msgId) {
+        return this.http.req('DELETE', `/v1/_threads/${encodeURIComponent(this.id)}/messages/${encodeURIComponent(msgId)}`);
+    }
+
+    /**
+     * RAG context retrieval within thread context.
+     * @param {string} question
+     * @param {object} [opts] - { rag_collections, k }
+     * @returns {Promise<object>} - { context, citations, search_hits, chunks_used, conversation, thread_id }
+     */
+    async ask(question, opts = {}) {
+        const body = { question };
+        if (opts.rag_collections) body.rag_collections = opts.rag_collections;
+        if (opts.k !== undefined) body.search_k = opts.k;
+        return this.http.req('POST', `/v1/_threads/${encodeURIComponent(this.id)}/_ask`, body);
+    }
+
+    /** Compress old messages into a summary. */
+    async summarize(opts) {
+        return this.http.req('POST', `/v1/_threads/${encodeURIComponent(this.id)}/_summarize`, opts);
+    }
+
+    /** Prune messages by criteria. */
+    async prune(opts) {
+        const body = {};
+        if (opts.keep_last !== undefined) body.keep_last = opts.keep_last;
+        if (opts.msg_ids) body.msg_ids = opts.msg_ids;
+        if (opts.role) body.role = opts.role;
+        return this.http.req('POST', `/v1/_threads/${encodeURIComponent(this.id)}/_prune`, body);
+    }
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Auth: authentication methods
+// ─────────────────────────────────────────────────────────────────────────────
+
+class Auth {
+    constructor(http, tenant) {
+        this.http = http;
+        this.tenant = tenant || 'default';
+    }
+
+    _hostHeader() {
+        return { 'Host': `${this.tenant}.localhost` };
+    }
+
+    async signup(creds) {
+        return this.http.req('POST', '/v1/_auth/register', creds, this._hostHeader());
+    }
+
+    async login(creds) {
+        return this.http.req('POST', '/v1/_auth/login', creds, this._hostHeader());
+    }
+
+    async refresh(token) {
+        return this.http.req('POST', '/v1/_auth/refresh', {}, {
+            ...this._hostHeader(),
+            'Authorization': `Bearer ${token}`,
+        });
+    }
+
+    async oauth(opts) {
+        return this.http.req('POST', '/v1/_auth/oauth', opts, this._hostHeader());
+    }
+
+    async google(opts) {
+        return this.http.req('POST', '/v1/_auth/google', opts, this._hostHeader());
+    }
+
+    async github(opts) {
+        return this.http.req('POST', '/v1/_auth/oauth', { provider: 'github', ...opts }, this._hostHeader());
+    }
+
+    async discord(opts) {
+        return this.http.req('POST', '/v1/_auth/oauth', { provider: 'discord', ...opts }, this._hostHeader());
+    }
+
+    async apple(opts) {
+        return this.http.req('POST', '/v1/_auth/oauth', { provider: 'apple', ...opts }, this._hostHeader());
+    }
+
+    async microsoft(opts) {
+        return this.http.req('POST', '/v1/_auth/oauth', { provider: 'microsoft', ...opts }, this._hostHeader());
+    }
+
+    async twitter(opts) {
+        return this.http.req('POST', '/v1/_auth/oauth', { provider: 'twitter', ...opts }, this._hostHeader());
+    }
+
+    /** Lazy providers sub-object for OAuth provider config CRUD. */
+    get providers() {
+        if (!this._providers) {
+            const http = this.http, hh = this._hostHeader();
+            this._providers = {
+                list: () => http.req('GET', '/v1/_auth/providers', undefined, hh),
+                set: (config) => http.req('POST', '/v1/_auth/providers', config, hh),
+                /** Delete a provider config (auth.provider.delete). */
+                delete: (provider) => http.req('DELETE', `/v1/_auth/providers/${encodeURIComponent(provider)}`, undefined, hh),
+            };
+        }
+        return this._providers;
+    }
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Users: admin user management
+// ─────────────────────────────────────────────────────────────────────────────
+
+class Users {
+    constructor(http) {
+        this.http = http;
+    }
+
+    /** List users with pagination. Options: { limit, skip } */
+    async list(opts = {}) {
+        const params = new URLSearchParams();
+        if (opts.limit) params.set('limit', opts.limit);
+        if (opts.skip) params.set('skip', opts.skip);
+        const qs = params.toString();
+        return this.http.req('GET', qs ? `/v1/_users?${qs}` : '/v1/_users');
+    }
+
+    /** Get a single user by ID */
+    async get(userId) {
+        return this.http.req('GET', `/v1/_users/${encodeURIComponent(userId)}`);
+    }
+
+    /** Admin-create a user. Fields: email, password, role?, keyring?, verified?, metadata? */
+    async create(data) {
+        return this.http.req('POST', '/v1/_users', data);
+    }
+
+    /** Update a user by ID. Fields: locked?, disabled?, admin?, email_verified?, keyring?, password?, metadata?, role? */
+    async update(userId, patch) {
+        return this.http.req('PATCH', `/v1/_users/${encodeURIComponent(userId)}`, patch);
+    }
+
+    /** Delete a user. Options: { hard: true } for permanent removal */
+    async delete(userId, opts = {}) {
+        const qs = opts.hard ? '?hard=true' : '';
+        return this.http.req('DELETE', `/v1/_users/${encodeURIComponent(userId)}${qs}`);
+    }
+
+    /** Get total user count */
+    async count() {
+        return this.http.req('GET', '/v1/_users/_count');
+    }
+
+    /** Impersonate a user (get a token as that user) */
+    async impersonate(userId) {
+        return this.http.req('POST', `/v1/_users/${encodeURIComponent(userId)}/impersonate`, {});
+    }
+
+    /** Assign a role to a user by ID. */
+    async setRole(userId, role) {
+        return this.http.req('PUT', `/v1/_users/${encodeURIComponent(userId)}/role`, { role });
+    }
+
+    /** Check if a user has permission for a collection + operation. */
+    async can(userId, collection, operation) {
+        return this.http.req('GET', `/v1/_users/${encodeURIComponent(userId)}/can?collection=${encodeURIComponent(collection)}&operation=${encodeURIComponent(operation)}`);
+    }
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// KvHttp: HTTP-based Key-Value store operations
+// ─────────────────────────────────────────────────────────────────────────────
+
+class KvHttp {
+    constructor(http, store) {
+        this.http = http;
+        this.store = store;
+    }
+
+    /** Set one or more key-value pairs: [[key, value], ...] */
+    async set(pairs) {
+        return this.http.req('POST', `/v1/kv/${encodeURIComponent(this.store)}`, pairs);
+    }
+
+    /** Get values for an array of keys: [key1, key2, ...] */
+    async get(keys) {
+        return this.http.req('POST', `/v1/kv/${encodeURIComponent(this.store)}/_get`, keys);
+    }
+
+    /** Delete an array of keys: [key1, key2, ...] */
+    async delete(keys) {
+        return this.http.req('POST', `/v1/kv/${encodeURIComponent(this.store)}/_del`, keys);
+    }
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Graph: labeled directed edge operations (TurboGraph)
+//
+// Usage:
+//   const g = db.graph('follows');
+//   await g.addEdge(1, 2);           // src=1 → dst=2
+//   await g.hasEdge(1, 2);           // { exists: true, ... }
+//   await g.neighbors(1);            // { neighbors: [2], count: 1 }
+//   await g.neighbors(1, 'in');      // incoming neighbors
+//   await g.degree(1);               // { out_degree: 1, in_degree: 0 }
+//   await g.removeEdge(1, 2);
+//   await g.stats();                 // { edge_count: ... }
+// ─────────────────────────────────────────────────────────────────────────────
+
+class Graph {
+    constructor(http, label) {
+        this.http = http;
+        this._base = `/v1/_graph/${encodeURIComponent(label)}`;
+    }
+
+    /** Add a directed edge: src → dst. Returns { added: true/false }. */
+    async addEdge(src, dst) {
+        return this.http.req('POST', `${this._base}/edges`, { src, dst });
+    }
+
+    /** Remove a directed edge: src → dst. Returns { removed: true/false }. */
+    async removeEdge(src, dst) {
+        return this.http.req('POST', `${this._base}/edges/_remove`, { src, dst });
+    }
+
+    /** Check if an edge exists: src → dst. Returns { exists: true/false }. */
+    async hasEdge(src, dst) {
+        return this.http.req('POST', `${this._base}/edges/_check`, { src, dst });
+    }
+
+    /**
+     * Get neighbors of a node.
+     * @param {number} nodeId - Node ID
+     * @param {string} [dir='out'] - Direction: 'out' or 'in'
+     * @returns {Promise<{neighbors: number[], count: number}>}
+     */
+    async neighbors(nodeId, dir = 'out') {
+        return this.http.req('POST', `${this._base}/neighbors/${nodeId}`, { dir });
+    }
+
+    /**
+     * Get degree (in/out) of a node.
+     * @param {number} nodeId - Node ID
+     * @returns {Promise<{out_degree: number, in_degree: number}>}
+     */
+    async degree(nodeId) {
+        return this.http.req('GET', `${this._base}/degree/${nodeId}`);
+    }
+
+    /** Get edge count stats for this label. */
+    async stats() {
+        return this.http.req('GET', `${this._base}/stats`);
+    }
+
+    // ── Bitmap-Native Analytics (Batch 1) ────────────────────────────────
+
+    /** Internal: dispatch an analytics operation to POST /analytics. */
+    async _analytics(body) {
+        return this.http.req('POST', `${this._base}/analytics`, body);
+    }
+
+    /** Common neighbors of nodes A and B. Returns { neighbors: [...], count }. */
+    async commonNeighbors(a, b, dir = 'out') {
+        return this._analytics({ op: 'common_neighbors', a, b, dir });
+    }
+
+    /** Count of common neighbors (no materialization). Returns { count }. */
+    async commonNeighborCount(a, b, dir = 'out') {
+        return this._analytics({ op: 'common_neighbor_count', a, b, dir });
+    }
+
+    /** Jaccard similarity: |A∩B| / |A∪B|. Returns { score }. */
+    async jaccard(a, b, dir = 'out') {
+        return this._analytics({ op: 'jaccard', a, b, dir });
+    }
+
+    /** Adamic-Adar index: Σ 1/log(deg(c)) for common neighbors c. Returns { score }. */
+    async adamicAdar(a, b, dir = 'out') {
+        return this._analytics({ op: 'adamic_adar', a, b, dir });
+    }
+
+    /** Preferential attachment: degree(A) × degree(B). Returns { score }. */
+    async preferentialAttachment(a, b, dir = 'out') {
+        return this._analytics({ op: 'preferential_attachment', a, b, dir });
+    }
+
+    /** Neighbors of A that are NOT neighbors of B. Returns { neighbors: [...], count }. */
+    async exclusiveNeighbors(a, b, dir = 'out') {
+        return this._analytics({ op: 'exclusive_neighbors', a, b, dir });
+    }
+
+    /** Combined neighbors of A and B (deduplicated). Returns { neighbors: [...], count }. */
+    async neighborUnion(a, b, dir = 'out') {
+        return this._analytics({ op: 'neighbor_union', a, b, dir });
+    }
+
+    /** Intersection of neighbors across multiple nodes. Returns { neighbors: [...], count }. */
+    async commonNeighborsMulti(nodes, dir = 'out') {
+        return this._analytics({ op: 'common_neighbors_multi', nodes, dir });
+    }
+
+    /** Union of neighbors across multiple nodes. Returns { neighbors: [...], count }. */
+    async neighborUnionMulti(nodes, dir = 'out') {
+        return this._analytics({ op: 'neighbor_union_multi', nodes, dir });
+    }
+
+    /** Overlap coefficient: |A∩B| / min(|A|, |B|). Returns { score }. */
+    async overlapCoefficient(a, b, dir = 'out') {
+        return this._analytics({ op: 'overlap_coefficient', a, b, dir });
+    }
+
+    // ── Bitmap-Native Analytics (Batch 2) ────────────────────────────────
+
+    // ── Tier 1: Link Prediction ──────────────────────────────────────────
+
+    /** Cosine similarity: |A∩B| / sqrt(|A|×|B|). Returns { score }. */
+    async cosineSimilarity(a, b, dir = 'out') {
+        return this._analytics({ op: 'cosine_similarity', a, b, dir });
+    }
+
+    /** Resource allocation: Σ 1/degree(c) for common neighbors c. Returns { score }. */
+    async resourceAllocation(a, b, dir = 'out') {
+        return this._analytics({ op: 'resource_allocation', a, b, dir });
+    }
+
+    // ── Tier 1: Range-Pruned Queries ─────────────────────────────────────
+
+    /**
+     * Neighbors with IDs in [lo, hi]. Returns { neighbors: [...], count }.
+     * @param {number} node - Node ID
+     * @param {number} lo - Range lower bound (inclusive)
+     * @param {number} hi - Range upper bound (inclusive)
+     * @param {string} [dir='out'] - Direction: 'out' or 'in'
+     */
+    async neighborsInRange(node, lo, hi, dir = 'out') {
+        return this._analytics({ op: 'neighbors_in_range', node, lo, hi, dir });
+    }
+
+    /**
+     * Count neighbors with IDs in [lo, hi]. Zero allocation. Returns { count }.
+     * @param {number} node - Node ID
+     * @param {number} lo - Range lower bound (inclusive)
+     * @param {number} hi - Range upper bound (inclusive)
+     * @param {string} [dir='out'] - Direction: 'out' or 'in'
+     */
+    async neighborsInRangeCount(node, lo, hi, dir = 'out') {
+        return this._analytics({ op: 'neighbors_in_range_count', node, lo, hi, dir });
+    }
+
+    // ── Tier 2: Triangle Counting ────────────────────────────────────────
+
+    /** Per-node triangle count. Returns { count }. */
+    async triangleCountNode(node, dir = 'out') {
+        return this._analytics({ op: 'triangle_count_node', node, dir });
+    }
+
+    /** Clustering coefficient: triangles / (deg×(deg-1)/2). Returns { score }. */
+    async clusteringCoefficient(node, dir = 'out') {
+        return this._analytics({ op: 'clustering_coefficient', node, dir });
+    }
+
+    /** Global clustering coefficient across all nodes. Returns { score }. */
+    async globalClusteringCoefficient(dir = 'out') {
+        return this._analytics({ op: 'global_clustering_coefficient', dir });
+    }
+
+    // ── Tier 3: Multi-Hop Traversals ─────────────────────────────────────
+
+    /** Friends-of-friends (2-hop). Returns { neighbors: [...], count }. */
+    async twoHopNeighbors(node, dir = 'out') {
+        return this._analytics({ op: 'two_hop_neighbors', node, dir });
+    }
+
+    /** K-hop BFS neighbors at exactly hop k. Returns { neighbors: [...], count }. */
+    async kHopNeighbors(node, k, dir = 'out') {
+        return this._analytics({ op: 'k_hop_neighbors', node, k, dir });
+    }
+
+    /** K-hop neighbor count (no materialization). Returns { count }. */
+    async kHopCount(node, k, dir = 'out') {
+        return this._analytics({ op: 'k_hop_count', node, k, dir });
+    }
+
+    /** Shortest path length (unweighted BFS). Returns { length } (-1 if unreachable). */
+    async shortestPathLength(src, dst) {
+        return this._analytics({ op: 'shortest_path_length', src, dst });
+    }
+
+    /** Reachability check. Returns { reachable: true/false }. */
+    async reachable(src, dst) {
+        return this._analytics({ op: 'reachable', src, dst });
+    }
+
+    // ── Tier 10: Tree-Structural ─────────────────────────────────────────
+
+    /** Minimum neighbor ID. Returns { value }. */
+    async minNeighbor(node, dir = 'out') {
+        return this._analytics({ op: 'min_neighbor', node, dir });
+    }
+
+    /** Maximum neighbor ID. Returns { value }. */
+    async maxNeighbor(node, dir = 'out') {
+        return this._analytics({ op: 'max_neighbor', node, dir });
+    }
+
+    // ── Bitmap-Native Analytics (Batch 3) ────────────────────────────────
+
+    // ── Tier 4: Degree Analytics ─────────────────────────────────────────
+
+    /** Degree centrality: degree(node) / (N-1). Returns { score }. */
+    async degreeCentrality(node, dir = 'out') {
+        return this._analytics({ op: 'degree_centrality', node, dir });
+    }
+
+    /**
+     * Top-K nodes by degree (min-heap, no full sort). Returns { nodes: [{node, degree}, ...], count }.
+     * @param {number} k - Number of top nodes
+     * @param {string} [dir='out'] - Direction
+     */
+    async topKByDegree(k, dir = 'out') {
+        return this._analytics({ op: 'top_k_by_degree', k, dir });
+    }
+
+    /** Degree distribution: map of degree → count. Returns { distribution: [{degree, count}, ...] }. */
+    async degreeDistribution(dir = 'out') {
+        return this._analytics({ op: 'degree_distribution', dir });
+    }
+
+    /**
+     * Degree histogram: bucketed degree counts. Returns { buckets: [{start, count}, ...] }.
+     * @param {number} bucketSize - Width of each bucket
+     * @param {string} [dir='out'] - Direction
+     */
+    async degreeHistogram(bucketSize, dir = 'out') {
+        return this._analytics({ op: 'degree_histogram', bucket_size: bucketSize, dir });
+    }
+
+    // ── Tier 5: Label-Aware Operations ───────────────────────────────────
+
+    /** Label stats: {node_count, edge_count, avg_degree, density}. */
+    async labelStats() {
+        return this._analytics({ op: 'label_stats' });
+    }
+
+    /**
+     * Neighbors across multiple labels (OR/union). Returns { neighbors: [...], count }.
+     * @param {string[]} labels - Label names to union across
+     * @param {number} node - Node ID
+     * @param {string} [dir='out'] - Direction
+     */
+    async neighborsMultiLabel(labels, node, dir = 'out') {
+        return this._analytics({ op: 'neighbors_multi_label', labels, node, dir });
+    }
+
+    /**
+     * Neighbors present in ALL labels (AND/intersection). Returns { neighbors: [...], count }.
+     * @param {string[]} labels - Label names to intersect
+     * @param {number} node - Node ID
+     * @param {string} [dir='out'] - Direction
+     */
+    async neighborsAllLabels(labels, node, dir = 'out') {
+        return this._analytics({ op: 'neighbors_all_labels', labels, node, dir });
+    }
+
+    // ── Tier 2: Global Triangle Counting ─────────────────────────────────
+
+    /** Global triangle count (all triangles in graph). Returns { count }. */
+    async triangleCountGlobal(dir = 'out') {
+        return this._analytics({ op: 'triangle_count_global', dir });
+    }
+
+    // ── Tier 10: Tree-Structural (Batch 3) ───────────────────────────────
+
+    /**
+     * Neighbor rank: count of neighbors with ID < target. Returns { rank }.
+     * @param {number} node - Node ID
+     * @param {number} target - Target value to rank against
+     * @param {string} [dir='out'] - Direction
+     */
+    async neighborRank(node, target, dir = 'out') {
+        return this._analytics({ op: 'neighbor_rank', node, target, dir });
+    }
+
+    // ── Tier 9: Advanced Graph Analytics ─────────────────────────────────
+
+    /** Topological sort (Kahn's algorithm). Returns { order: [...], count } or empty if cycle. */
+    async topologicalSort() {
+        return this._analytics({ op: 'topological_sort' });
+    }
+
+    /** Cycle detection. Returns { has_cycle: true/false }. */
+    async hasCycle() {
+        return this._analytics({ op: 'has_cycle' });
+    }
+
+    /** Connected components (undirected BFS). Returns { components: [[...], ...], count }. */
+    async connectedComponents() {
+        return this._analytics({ op: 'connected_components' });
+    }
+
+    /**
+     * Comprehensive graph summary in one call. Returns node/edge counts,
+     * density, avg degree, max degree nodes, component count, cycle status.
+     */
+    async graphSummary() {
+        return this._analytics({ op: 'graph_summary' });
+    }
+
+    // ── Bitmap-Native Analytics (Batch 4): Hard Algorithms ──────────────
+
+    /**
+     * PageRank: iterative authority propagation. Returns { nodes: [{node, score}, ...], count }.
+     * @param {object} [opts={}] - Options
+     * @param {number} [opts.iterations=20] - Number of power iterations
+     * @param {number} [opts.damping=0.85] - Damping factor (teleport probability = 1 - damping)
+     */
+    async pagerank(opts = {}) {
+        const body = { op: 'pagerank' };
+        if (opts.iterations !== undefined) body.iterations = opts.iterations;
+        if (opts.damping !== undefined) body.damping = opts.damping;
+        return this._analytics(body);
+    }
+
+    /**
+     * Betweenness centrality (Brandes' algorithm).
+     * Returns { nodes: [{node, score}, ...], count }.
+     */
+    async betweennessCentrality() {
+        return this._analytics({ op: 'betweenness_centrality' });
+    }
+
+    /**
+     * Closeness centrality for a single node: (reachable-1) / Σ distances.
+     * @param {number} node - Node ID
+     * @returns {Promise<{score: number}>}
+     */
+    async closenessCentrality(node) {
+        return this._analytics({ op: 'closeness_centrality', node });
+    }
+
+    /**
+     * HITS: Hyperlink-Induced Topic Search.
+     * Returns { nodes: [{node, hub, authority}, ...], count }.
+     * @param {object} [opts={}] - Options
+     * @param {number} [opts.iterations=20] - Number of iterations
+     */
+    async hits(opts = {}) {
+        const body = { op: 'hits' };
+        if (opts.iterations !== undefined) body.iterations = opts.iterations;
+        return this._analytics(body);
+    }
+
+    /**
+     * Strongly connected components (Kosaraju's).
+     * Returns { components: [[...], ...], count }.
+     */
+    async scc() {
+        return this._analytics({ op: 'scc' });
+    }
+
+    // ── Graph Intrinsics (Batch 5): Paths, Community, Bulk ──────────────
+
+    /**
+     * Shortest path (BFS) from src to dst. Returns { path: [...], length }.
+     * @param {number} src - Source node ID
+     * @param {number} dst - Destination node ID
+     * @param {string} [dir='out'] - Direction: 'out' or 'in'
+     */
+    async shortestPath(src, dst, dir = 'out') {
+        return this._analytics({ op: 'shortest_path', src, dst, dir });
+    }
+
+    /**
+     * All shortest paths from src to dst (same length). Returns { paths: [[...], ...], length, count }.
+     * @param {number} src - Source node ID
+     * @param {number} dst - Destination node ID
+     * @param {string} [dir='out'] - Direction
+     */
+    async allShortestPaths(src, dst, dir = 'out') {
+        return this._analytics({ op: 'all_shortest_paths', src, dst, dir });
+    }
+
+    /**
+     * Eccentricity: max shortest-path distance from node to any reachable node.
+     * @param {number} node - Node ID
+     * @param {string} [dir='out'] - Direction
+     * @returns {Promise<{eccentricity: number}>}
+     */
+    async eccentricity(node, dir = 'out') {
+        return this._analytics({ op: 'eccentricity', node, dir });
+    }
+
+    /**
+     * Diameter: max eccentricity across all nodes (longest shortest path).
+     * @param {string} [dir='out'] - Direction
+     * @returns {Promise<{diameter: number}>}
+     */
+    async diameter(dir = 'out') {
+        return this._analytics({ op: 'diameter', dir });
+    }
+
+    /**
+     * Find a cycle in the graph. Returns { cycle: [...] } or { cycle: [] } if acyclic.
+     * @param {string} [dir='out'] - Direction
+     */
+    async findCycle(dir = 'out') {
+        return this._analytics({ op: 'find_cycle', dir });
+    }
+
+    /**
+     * Count 4-cycles (squares) incident to a node.
+     * @param {number} node - Node ID
+     * @param {string} [dir='out'] - Direction
+     * @returns {Promise<{count: number}>}
+     */
+    async squareCount(node, dir = 'out') {
+        return this._analytics({ op: 'square_count', node, dir });
+    }
+
+    /**
+     * SimRank: structural similarity between two nodes.
+     * @param {number} a - First node ID
+     * @param {number} b - Second node ID
+     * @param {number} [c=0.8] - Decay factor (0 < c < 1)
+     * @param {number} [iterations=5] - Number of iterations
+     * @returns {Promise<{score: number}>}
+     */
+    async simrank(a, b, c = 0.8, iterations = 5) {
+        return this._analytics({ op: 'simrank', a, b, c, iterations });
+    }
+
+    // ── Community Detection ──────────────────────────────────────────────
+
+    /**
+     * Label Propagation community detection.
+     * @param {number} [iterations=10] - Max iterations
+     * @returns {Promise<{assignments: [{node, community}], count}>}
+     */
+    async labelPropagation(iterations = 10) {
+        return this._analytics({ op: 'label_propagation', iterations });
+    }
+
+    /**
+     * Louvain modularity-based community detection.
+     * @returns {Promise<{assignments: [{node, community}], modularity, count}>}
+     */
+    async louvain() {
+        return this._analytics({ op: 'louvain' });
+    }
+
+    /**
+     * Graph coloring (greedy). Returns { coloring: [{node, color}], count }.
+     */
+    async graphColoring() {
+        return this._analytics({ op: 'graph_coloring' });
+    }
+
+    /**
+     * Minimum vertex cover approximation (2-approx).
+     * @returns {Promise<{nodes: number[], count}>}
+     */
+    async minVertexCover() {
+        return this._analytics({ op: 'min_vertex_cover' });
+    }
+
+    /**
+     * Maximum independent set approximation (greedy).
+     * @returns {Promise<{nodes: number[], count}>}
+     */
+    async maxIndependentSet() {
+        return this._analytics({ op: 'max_independent_set' });
+    }
+
+    /**
+     * Bipartite projection: produce co-occurrence edges.
+     * @param {string} [dir='out'] - Direction
+     * @returns {Promise<{edges: [{a, b, weight}], count}>}
+     */
+    async bipartiteProject(dir = 'out') {
+        return this._analytics({ op: 'bipartite_project', dir });
+    }
+
+    // ── Degree Analytics ─────────────────────────────────────────────────
+
+    /**
+     * Degree at a given percentile across all nodes.
+     * @param {number} percentile - Percentile (0.0 to 1.0)
+     * @param {string} [dir='out'] - Direction
+     * @returns {Promise<{value: number}>}
+     */
+    async degreePercentile(percentile, dir = 'out') {
+        return this._analytics({ op: 'degree_percentile', percentile, dir });
+    }
+
+    /**
+     * Median degree across all nodes.
+     * @param {string} [dir='out'] - Direction
+     * @returns {Promise<{value: number}>}
+     */
+    async degreeMedian(dir = 'out') {
+        return this._analytics({ op: 'degree_median', dir });
+    }
+
+    /**
+     * Count nodes with degree strictly greater than threshold.
+     * @param {number} threshold
+     * @param {string} [dir='out'] - Direction
+     * @returns {Promise<{count: number}>}
+     */
+    async nodesWithDegreeGt(threshold, dir = 'out') {
+        return this._analytics({ op: 'nodes_with_degree_gt', threshold, dir });
+    }
+
+    /**
+     * Count nodes with degree >= threshold.
+     * @param {number} threshold
+     * @param {string} [dir='out'] - Direction
+     * @returns {Promise<{count: number}>}
+     */
+    async nodesWithDegreeGte(threshold, dir = 'out') {
+        return this._analytics({ op: 'nodes_with_degree_gte', threshold, dir });
+    }
+
+    /**
+     * Count nodes with degree < threshold.
+     * @param {number} threshold
+     * @param {string} [dir='out'] - Direction
+     * @returns {Promise<{count: number}>}
+     */
+    async nodesWithDegreeLt(threshold, dir = 'out') {
+        return this._analytics({ op: 'nodes_with_degree_lt', threshold, dir });
+    }
+
+    /**
+     * Count nodes with degree in [lo, hi] inclusive.
+     * @param {number} lo - Lower bound
+     * @param {number} hi - Upper bound
+     * @param {string} [dir='out'] - Direction
+     * @returns {Promise<{count: number}>}
+     */
+    async nodesWithDegreeInRange(lo, hi, dir = 'out') {
+        return this._analytics({ op: 'nodes_with_degree_in_range', lo, hi, dir });
+    }
+
+    // ── Node Neighborhood Analytics ──────────────────────────────────────
+
+    /**
+     * Neighbor at a given percentile of a node's sorted neighbor list.
+     * @param {number} node - Node ID
+     * @param {number} [percentile=0.5] - Percentile (0.0 to 1.0)
+     * @param {string} [dir='out'] - Direction
+     * @returns {Promise<{value: number}>}
+     */
+    async neighborAtPercentile(node, percentile = 0.5, dir = 'out') {
+        return this._analytics({ op: 'neighbor_at_percentile', node, percentile, dir });
+    }
+
+    /**
+     * Degree facets for each neighbor of a node.
+     * @param {number} node - Node ID
+     * @param {string} [dir='out'] - Direction
+     * @returns {Promise<{facets: [{neighbor, degree}], count}>}
+     */
+    async neighborDegreeFacets(node, dir = 'out') {
+        return this._analytics({ op: 'neighbor_degree_facets', node, dir });
+    }
+
+    /**
+     * Histogram of neighbor IDs bucketed by value.
+     * @param {number} node - Node ID
+     * @param {number} [bucketSize=10] - Width of each bucket
+     * @param {string} [dir='out'] - Direction
+     * @returns {Promise<{buckets: [{start, count}], bucket_count}>}
+     */
+    async neighborHistogram(node, bucketSize = 10, dir = 'out') {
+        return this._analytics({ op: 'neighbor_histogram', node, bucket_size: bucketSize, dir });
+    }
+
+    // ── Multi-Label Traversal ────────────────────────────────────────────
+
+    /**
+     * K-hop traversal across different labels at each hop.
+     * @param {number} node - Starting node ID
+     * @param {string[]} labels - Label sequence for each hop
+     * @returns {Promise<{neighbors: number[], count}>}
+     */
+    async kHopLabeled(node, labels) {
+        return this._analytics({ op: 'k_hop_labeled', node, labels });
+    }
+
+    // ── Influence & Simulation ───────────────────────────────────────────
+
+    /**
+     * Influence spread estimation (Independent Cascade model, Monte Carlo).
+     * @param {number[]} seeds - Seed node IDs
+     * @param {number} [probability=0.1] - Propagation probability per edge
+     * @param {number} [simulations=100] - Number of Monte Carlo simulations
+     * @returns {Promise<{spread: number}>}
+     */
+    async influenceSpread(seeds, probability = 0.1, simulations = 100) {
+        return this._analytics({ op: 'influence_spread', seeds, probability, simulations });
+    }
+
+    // ── Bulk Operations ──────────────────────────────────────────────────
+
+    /**
+     * Check multiple edges at once. Returns { results: [true/false, ...] }.
+     * @param {Array<[number, number]>} pairs - Array of [src, dst] pairs
+     */
+    async hasEdges(pairs) {
+        return this._analytics({ op: 'has_edges', pairs });
+    }
+
+    /**
+     * Batch-add multiple edges at once. Returns { added: count }.
+     * @param {Array<[number, number]>} pairs - Array of [src, dst] pairs
+     */
+    async addEdges(pairs) {
+        return this._analytics({ op: 'add_edges', pairs });
+    }
+
+    /**
+     * Batch-remove multiple edges at once. Returns { removed: count }.
+     * @param {Array<[number, number]>} pairs - Array of [src, dst] pairs
+     */
+    async removeEdges(pairs) {
+        return this._analytics({ op: 'remove_edges', pairs });
+    }
+
+    /**
+     * Get degrees of multiple nodes at once. Returns { degrees: [N, ...] }.
+     * @param {number[]} nodes - Array of node IDs
+     * @param {string} [dir='out'] - Direction
+     */
+    async degrees(nodes, dir = 'out') {
+        return this._analytics({ op: 'degrees', nodes, dir });
+    }
+
+    /**
+     * Pairwise Jaccard similarity matrix for a set of nodes.
+     * Returns { matrix: [[...], ...] }: NxN symmetric matrix.
+     * @param {number[]} nodes - Array of node IDs
+     * @param {string} [dir='out'] - Direction
+     */
+    async pairwiseJaccard(nodes, dir = 'out') {
+        return this._analytics({ op: 'pairwise_jaccard', nodes, dir });
+    }
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Tenants: multi-tenant shard management
+// ─────────────────────────────────────────────────────────────────────────────
+
+export class Tenants {
+    constructor(http) {
+        this.http = http;
+    }
+
+    /**
+     * Create a new tenant (shard).
+     * Auto-registers a SyncManager for the new tenant.
+     * @param {string} slug - Tenant slug (lowercase alphanumeric + hyphens, 1-32 chars)
+     * @returns {Promise<{_id: number, slug: string, subdomain: string, created: boolean, sync?: {node_id: string}}>}
+     */
+    async create(slug) {
+        return this.http.req('POST', '/v1/tenants', { subdomain: slug });
+    }
+
+    /**
+     * List all tenants with their sync engine status (tenant.list).
+     * @returns {Promise<{data: Array<{_id: number, slug: string, sync: {node_id: string, gossip_mode: number, peers: number}|null}>, count: number, tenant_domains: string[]}>}
+     */
+    async list() {
+        return this.http.req('GET', '/v1/_tenants');
+    }
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// ScatterHttp: Transport wrapper that routes queries through scatter endpoint
+//
+// This wraps the real Http client and intercepts query calls:
+//   POST /v1/{collection}/_query  →  POST /v1/_mesh/scatter
+//
+// The Collection class is reused AS-IS: scatter is only a transport layer.
+// ─────────────────────────────────────────────────────────────────────────────
+
+class ScatterHttp {
+    /**
+     * @param {Http} realHttp - The real HTTP client
+     * @param {object} [opts] - Scatter options
+     * @param {string} [opts.tenant='*'] - Tenant/namespace filter ('*' = all)
+     * @param {number} [opts.timeout=5000] - Per-node timeout in ms
+     * @param {number} [opts.limit] - Global result limit
+     */
+    constructor(realHttp, opts = {}) {
+        this._real = realHttp;
+        this._opts = opts;
+        // Forward properties needed by Collection/Query
+        this._url = realHttp._url;
+        this._tenant = realHttp._tenant;
+        this._key = realHttp._key;
+        this._timing = realHttp._timing;
+    }
+
+    async req(method, path, body) {
+        // Intercept POST /v1/{collection}/_query → scatter
+        const m = path.match(/^\/v1\/([^/]+)\/_query$/);
+        if (method === 'POST' && m) {
+            const collection = m[1];
+            const scatterBody = { collection };
+            // Pass the query body through as-is
+            if (body && Object.keys(body).length > 0) scatterBody.query = body;
+            if (this._opts.tenant) scatterBody.tenant = this._opts.tenant;
+            if (this._opts.timeout) scatterBody.timeout = this._opts.timeout;
+            if (this._opts.limit) scatterBody.limit = this._opts.limit;
+            return this._real.req('POST', '/v1/_mesh/scatter', scatterBody);
+        }
+        // Intercept POST /v1/{collection}/_qx → scatter with bytecode
+        const mQx = path.match(/^\/v1\/([^/]+)\/_qx$/);
+        if (method === 'POST' && mQx) {
+            const collection = mQx[1];
+            // JSON carries no bytes: raw bytecode travels as base64 here.
+            const bytecode = body instanceof Uint8Array ? bytesToBase64(body) : body;
+            const scatterBody = { collection, bytecode };
+            if (this._opts.tenant) scatterBody.tenant = this._opts.tenant;
+            if (this._opts.timeout) scatterBody.timeout = this._opts.timeout;
+            if (this._opts.limit) scatterBody.limit = this._opts.limit;
+            return this._real.req('POST', '/v1/_mesh/scatter', scatterBody);
+        }
+        // Everything else passes through to the real transport
+        return this._real.req(method, path, body);
+    }
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// ScatterScope: Returns Collection objects backed by ScatterHttp transport
+//
+// Usage (identical API surface as normal collections):
+//   db.mesh.scatter.collection('users').find({ age: { $gte: 18 } })
+//   db.mesh.scatter.collection('orders').pipeline([{ $group: ... }])
+//   db.mesh.scatter.collection('logs').query().where({level:'error'}).limit(100).run()
+// ─────────────────────────────────────────────────────────────────────────────
+
+class ScatterScope {
+    /**
+     * @param {Http} realHttp - The real HTTP client
+     * @param {object} [opts] - Default scatter options
+     */
+    constructor(realHttp, opts = {}) {
+        this._http = new ScatterHttp(realHttp, { tenant: '*', ...opts });
+    }
+
+    /**
+     * Get a collection backed by scatter transport.
+     * Same API as db.collection(): find, pipeline, query, count, search all work identically.
+     *
+     * @param {string} name - Collection name
+     * @returns {Collection}
+     *
+     * @example
+     *   db.mesh.scatter.collection('users').find({ age: { $gte: 18 } })
+     */
+    collection(name) {
+        return new Collection(this._http, name);
+    }
+
+    /**
+     * Create a new ScatterScope with custom options.
+     * @param {object} opts - { tenant, timeout, limit }
+     * @returns {ScatterScope}
+     *
+     * @example
+     *   db.mesh.scatter.with({ tenant: 'us-east', timeout: 10000 }).collection('users').find()
+     */
+    with(opts) {
+        return new ScatterScope(this._http._real, opts);
+    }
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Mesh: SubstrioMesh inter-node orchestration
+// ─────────────────────────────────────────────────────────────────────────────
+
+
+export class Mesh {
+    constructor(http) {
+        this.http = http;
+    }
+
+    // ── Scatter-Gather Query Proxy ──────────────────────────────────────
+
+    /**
+     * Scatter-gather scope: returns a scope where collection() creates
+     * scatter-backed collections with identical API to normal collections.
+     *
+     * @type {ScatterScope}
+     *
+     * @example
+     *   // Same API as db.collection(), but queries fan out across all mesh nodes:
+     *   const r = await db.mesh.scatter.collection('users').find({ age: { $gte: 18 } })
+     *   const r = await db.mesh.scatter.collection('orders').pipeline([{ $group: ... }])
+     *   const r = await db.mesh.scatter.collection('logs').query().where({level:'error'}).limit(100).run()
+     *
+     *   // With custom options:
+     *   const r = await db.mesh.scatter.with({ tenant: 'us-east' }).collection('users').find()
+     */
+    get scatter() {
+        if (!this._scatter) this._scatter = new ScatterScope(this.http);
+        return this._scatter;
+    }
+
+    // ── Distributed Cloud Function Invocation ────────────────────────────
+
+    /**
+     * Execute a Cloud Function on any mesh node: computation shipping.
+     * The coordinator routes to whichever node holds the target tenant.
+     *
+     * @param {string} name - Function name to invoke
+     * @param {object} [args={}] - Arguments passed as event.body to the CF
+     * @param {object} [opts={}] - Options
+     * @param {string} [opts.tenant] - Target tenant slug (default: SDK tenant)
+     * @param {number} [opts.timeout] - Timeout in ms (default: 5000)
+     * @returns {Promise<{result: any, tenant: string, node_id: string, timing: {dispatch_us: number, total_us: number}}>}
+     *
+     * @example
+     *   // Invoke on default tenant
+     *   const r = await db.mesh.invoke('processData', { ids: [1,2,3] })
+     *   console.log(r.result)
+     *
+     *   // Invoke on specific tenant (runs where that tenant lives)
+     *   const r = await db.mesh.invoke('aggregate', { field: 'revenue' }, { tenant: 'us-east' })
+     *
+     *   // With custom timeout
+     *   const r = await db.mesh.invoke('heavyCompute', data, { timeout: 30000 })
+     */
+    async invoke(name, args = {}, opts = {}) {
+        const body = { function: name, args };
+        if (opts.tenant) body.tenant = opts.tenant;
+        if (opts.timeout) body.timeout = opts.timeout;
+        if (opts.nodes) body.nodes = opts.nodes;
+        return this.http.req('POST', '/v1/_mesh/invoke', body);
+    }
+
+    // ── Core Operations ─────────────────────────────────────────────────
+
+    /**
+     * Push (provision) a tenant onto remote nodes.
+     * The tenant must exist locally first (create via db.tenants.create()).
+     *
+     * @param {string} slug - Tenant slug to push
+     * @param {object} [opts] - Options
+     * @param {string[]} [opts.nodes=['*']] - Target node addresses or ['*'] for all peers
+     * @returns {Promise<{status: string, slug: string, target: string|string[]}>}
+     *
+     * @example
+     *   // Push to ALL connected peers
+     *   await db.mesh.push('acme-corp')
+     *
+     *   // Push to specific nodes by address
+     *   await db.mesh.push('acme-corp', { nodes: ['10.0.1.1:9000', '10.0.2.1:9000'] })
+     */
+    async push(slug, opts = {}) {
+        const body = { slug };
+        body.nodes = opts.nodes || ['*'];
+        return this.http.req('POST', '/v1/_mesh/push', body);
+    }
+
+    /**
+     * Drop (remove) a tenant from remote nodes.
+     *
+     * @param {string} slug - Tenant slug to drop (cannot be 'default')
+     * @param {object} [opts] - Options
+     * @param {string[]} [opts.nodes=['*']] - Target node addresses or ['*'] for all peers
+     * @returns {Promise<{status: string, slug: string}>}
+     *
+     * @example
+     *   await db.mesh.drop('acme-corp')
+     */
+    async drop(slug, opts = {}) {
+        const body = { slug };
+        body.nodes = opts.nodes || ['*'];
+        return this.http.req('POST', '/v1/_mesh/drop', body);
+    }
+
+    /**
+     * List all tenants on this node with sync metadata.
+     *
+     * @returns {Promise<{node_id: string, port: number, tenants: Array<{slug: string, node_id?: string, oplog_seq?: string, peer_count?: number}>}>}
+     *
+     * @example
+     *   const { tenants } = await db.mesh.tenants()
+     *   tenants.forEach(t => console.log(t.slug, t.peer_count))
+     */
+    async tenants() {
+        return this.http.req('GET', '/v1/_mesh/tenants');
+    }
+
+    /**
+     * Get this node's mesh status (sync stats, peer count, RPC stats).
+     *
+     * @returns {Promise<{node_id: string, port: number, tenant_count: number, sync: object, peer_count: number, rpc: {handlers: number, pending: number}}>}
+     *
+     * @example
+     *   const s = await db.mesh.status()
+     *   console.log(`Node ${s.node_id}: ${s.tenant_count} tenants, ${s.peer_count} peers`)
+     */
+    async status() {
+        return this.http.req('GET', '/v1/_mesh/status');
+    }
+
+    // ── Convenience Methods ─────────────────────────────────────────────
+
+    /**
+     * Create a tenant and immediately push it to remote nodes.
+     * This is the most common workflow: one call to replicate a tenant
+     * across your entire mesh or to specific nodes.
+     *
+     * @param {string} slug - Tenant slug to create and replicate
+     * @param {object} [opts] - Options
+     * @param {string[]} [opts.nodes=['*']] - Target nodes to push to (default: all peers)
+     * @returns {Promise<{created: boolean, slug: string, pushed: object}>}
+     *
+     * @example
+     *   // Create 'acme-corp' and push to all peers: one line
+     *   await db.mesh.replicate('acme-corp')
+     *
+     *   // Create and push to specific regional nodes
+     *   await db.mesh.replicate('acme-corp', { nodes: ['us-east:9000', 'eu-west:9000'] })
+     */
+    async replicate(slug, opts = {}) {
+        let createResult;
+        try {
+            createResult = await this.http.req('POST', '/v1/projects', { subdomain: slug });
+        } catch (e) {
+            // Tenant may already exist: that's OK, proceed with push
+            createResult = e.body || { error: e.message };
+        }
+        let pushResult;
+        try {
+            pushResult = await this.push(slug, opts);
+        } catch (e) {
+            // Push may fail if SyncManager hasn't initialized yet for new tenant
+            pushResult = e.body || { error: e.message };
+        }
+        const alreadyExists = createResult?.error?.includes('already exists') ||
+            createResult?.error?.includes('Tenant already exists');
+        return {
+            created: !!(createResult?.created || createResult?.slug === slug || alreadyExists),
+            slug,
+            pushed: pushResult,
+        };
+    }
+
+    /**
+     * Quick health check: returns true if this node is responsive and has
+     * at least one tenant. Use for load balancer health probes or monitoring.
+     *
+     * @returns {Promise<boolean>}
+     *
+     * @example
+     *   if (await db.mesh.health()) console.log('Node is healthy')
+     */
+    async health() {
+        try {
+            const s = await this.status();
+            return !!(s && typeof s.tenant_count === 'number' && s.tenant_count > 0);
+        } catch { return false; }
+    }
+
+    /**
+     * Get the number of connected peer nodes.
+     *
+     * @returns {Promise<number>}
+     *
+     * @example
+     *   const count = await db.mesh.peerCount()
+     *   console.log(`Connected to ${count} peers`)
+     */
+    async peerCount() {
+        const s = await this.status();
+        return s?.peer_count ?? 0;
+    }
+
+
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Security: IP allowlists, rate limiting, and audit logging
+// ─────────────────────────────────────────────────────────────────────────────
+
+export class Security {
+    constructor(http) {
+        this.http = http;
+    }
+
+    // ── IP Allowlist ─────────────────────────────────────────────────────
+
+    /** IP allowlist management for api, mesh, and kv targets. */
+    get allowlist() {
+        const http = this.http;
+        return {
+            /** GET /v1/_security/allowlist: view all allowlist entries */
+            list: () => http.req('GET', '/v1/_security/allowlist'),
+            /** POST: add an IP or CIDR range to a target (api|mesh|kv) */
+            add: (target, ip) => http.req('POST', '/v1/_security/allowlist', { target, ip }),
+            /** DELETE: remove a specific IP from a target */
+            remove: (target, ip) => http.req('DELETE', '/v1/_security/allowlist', { target, ip }),
+            /** DELETE with clear:true: clear ALL entries for a target */
+            clear: (target) => http.req('DELETE', '/v1/_security/allowlist', { target, clear: true }),
+        };
+    }
+
+    // ── Rate Limiting ────────────────────────────────────────────────────
+
+    /** Rate limit configuration (per-IP token bucket). */
+    get rateLimit() {
+        const http = this.http;
+        return {
+            /** GET /v1/_security/rate_limit: view current config */
+            get: () => http.req('GET', '/v1/_security/rate_limit'),
+            /** POST: set default rate limit { max_tokens, tokens_per_second } */
+            set: (config) => http.req('POST', '/v1/_security/rate_limit', config),
+            /** POST: set per-IP override { ip, max_tokens, tokens_per_second } */
+            setOverride: (ip, config) => http.req('POST', '/v1/_security/rate_limit', { ip, ...config }),
+            /** DELETE: remove per-IP override */
+            removeOverride: (ip) => http.req('DELETE', '/v1/_security/rate_limit', { ip }),
+            /** DELETE with clear:true: reset all rate limits */
+            clear: () => http.req('DELETE', '/v1/_security/rate_limit', { clear: true }),
+        };
+    }
+
+    // ── Audit Log ────────────────────────────────────────────────────────
+
+    /** Authentication failures: a view of the audit trail (auth.failure records). Append-only. */
+    get audit() {
+        const http = this.http;
+        return {
+            /** GET /v1/_security/audit: list auth failures, newest first, with cursor paging */
+            list: (opts = {}) => {
+                const params = new URLSearchParams();
+                for (const k of ['actor_kind', 'actor', 'since', 'until', 'order', 'limit', 'cursor']) {
+                    if (opts[k] !== undefined) params.set(k, String(opts[k]));
+                }
+                const q = params.toString();
+                return http.req('GET', '/v1/_security/audit' + (q ? '?' + q : ''));
+            },
+        };
+    }
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Substrio: the root client
+// ─────────────────────────────────────────────────────────────────────────────
+
+export default class Substrio {
+    /**
+     * @param {object} config
+     * @param {string} config.url     - Server URL (e.g. 'http://localhost:9000')
+     * @param {string} [config.key]   - Master key (sets X-Substrio-Master-Key header)
+     * @param {string} [config.token] - Bearer token from signup/login (sets Authorization header)
+     * @param {string} [config.tenant] - Tenant slug (default: 'default')
+     */
+    constructor(config) {
+        if (!config?.url) throw new Error('Substrio: url is required');
+        const tenant = config.tenant || 'default';
+        const headers = { 'Content-Type': JSON_TYPE };
+        headers['X-Substrio-Tenant'] = tenant;
+        if (config.key) headers['X-Substrio-Master-Key'] = config.key;
+        if (config.token) headers['Authorization'] = `Bearer ${config.token}`;
+        this.http = new Http(config.url, headers, config.url, tenant, config.key);
+        this.auth = new Auth(this.http, tenant);
+        this.users = new Users(this.http);
+        this.tenants = new Tenants(this.http);
+        this.mesh = new Mesh(this.http);
+        // Every registry operation, generated (substrio_operations.mjs):
+        // client.ops.kv.get(input), and client.kv.get(input) where the
+        // client has no member of the group's name.
+        this.ops = bindOperations(this.http);
+        attachOperations(this, this.ops);
+        // Store config for WS connections
+        this._url = config.url;
+        this._tenant = tenant;
+        this._key = config.key || null;
+    }
+
+    // ── Collection ref ────────────────────────────────────────────────────
+
+    /** Get a collection reference (lazy: no HTTP call). */
+    collection(name) {
+        return new Collection(this.http, name);
+    }
+
+    // ── Thread management ─────────────────────────────────────────────────
+
+    /**
+     * Create a new thread or get a ref to an existing one.
+     * - If called with a string: returns a lazy Thread ref (no HTTP).
+     * - If called with an object: creates a new thread (HTTP POST).
+     *
+     * @param {string|Object} opts - Thread ID (string) or creation options (object)
+     * @param {string} [opts.system_prompt] - System prompt for AI conversations
+     * @param {string} [opts.model] - LLM model override
+     * @param {string[]} [opts.rag_collections] - Collections for RAG context
+     * @param {string} [opts.tool_preset] - AI tool access level: 'read_only' (default), 'analyst', 'curator', 'operator'
+     * @param {string[]} [opts.write_collections] - Collections AI can write to (curator/operator only)
+     * @param {number} [opts.tool_budget_max_calls] - Max tool calls per _ask (default 10)
+     * @param {number} [opts.tool_budget_max_writes] - Max write operations per _ask (default 3)
+     * @param {string} [opts.memory_collection] - Collection for AI agent persistent memory
+     * @returns {Promise<Thread>}
+     */
+    async thread(opts) {
+        if (typeof opts === 'string') return new Thread(this.http, opts);
+        const data = await this.ops.thread.create(opts || {});
+        return new Thread(this.http, data.id, data);
+    }
+
+    /** List threads. */
+    async threads(opts) {
+        return this.ops.thread.list(opts);
+    }
+
+    // ── Multi-collection search ───────────────────────────────────────────
+
+    /** Search across multiple collections with RRF fusion. */
+    async search(collections, query, opts = {}) {
+        const body = { collections, query };
+        if (opts.limit !== undefined) body.limit = opts.limit;
+        if (opts.k !== undefined) body.search_k = opts.k;
+        if (opts.mode) body.mode = opts.mode;
+        return this.http.req('POST', '/v1/_multi_search', body);
+    }
+
+    // ── Batch / Transactions ──────────────────────────────────────────────
+
+    /**
+     * Execute multiple operations atomically (or non-atomically).
+     * @param {Array<{op: 'insert'|'update'|'delete', collection: string, doc?: object, id?: string|number, data?: object}>} ops
+     * @param {object} [opts]
+     * @param {boolean} [opts.atomic=true] - If true, all-or-nothing with rollback on failure
+     * @returns {Promise<{ok: boolean, atomic: boolean, count: number, results: Array}>}
+     */
+    async batch(ops, opts = {}) {
+        const atomic = opts.atomic !== undefined ? opts.atomic : true;
+        return this.ops.batch.execute({ atomic, ops });
+    }
+
+    // ── Inline JS Execution ($execJS) ─────────────────────────────────────
+
+    /**
+     * Execute inline JavaScript with full platform access.
+     * The JS code runs in a sandboxed JSC context with a `substrio` object
+     * providing synchronous access to db operations and auth.
+     *
+     * @param {string} code - JavaScript code to execute (use `return` to return values)
+     * @returns {Promise<{result: any, exec_us: number}>}
+     *
+     * @example
+     *   // Simple computation
+     *   await db.exec('return 1 + 2');  // { result: 3, exec_us: ... }
+     *
+     *   // Insert + query in single request
+     *   await db.exec(`
+     *     substrio.db.insert("users", { name: "Alice", age: 30 });
+     *     return substrio.db.query("users");
+     *   `);
+     */
+    async exec(code) {
+        return this.ops.function.execute_inline({ code });
+    }
+
+    // ── Lua Scripting Engine ──────────────────────────────────────────────
+
+    /**
+     * Execute a Lua script on the server via the LuaJIT scripting engine.
+     * @param {string} script - Lua source code to execute
+     * @param {string[]} [keys=[]] - KEYS array passed to the script
+     * @param {string[]} [args=[]] - ARGV array passed to the script
+     * @returns {Promise<{result: any}>}
+     */
+    async luaEval(script, keys = [], args = []) {
+        return this.http.req('POST', '/v1/eval', { script, keys, args });
+    }
+
+    /**
+     * Execute a previously-loaded Lua script by SHA1 digest.
+     * @param {string} sha - SHA1 hex digest of the script
+     * @param {string[]} [keys=[]] - KEYS array passed to the script
+     * @param {string[]} [args=[]] - ARGV array passed to the script
+     * @returns {Promise<{result: any}>}
+     */
+    async luaEvalSha(sha, keys = [], args = []) {
+        return this.http.req('POST', '/v1/eval', { sha, keys, args });
+    }
+
+    /**
+     * Load a Lua script into the server's script cache.
+     * @param {string} script - Lua source code
+     * @returns {Promise<{sha: string}>}
+     */
+    async luaLoad(script) {
+        return this.http.req('POST', '/v1/eval', { script, load: true });
+    }
+
+    // ── Health ────────────────────────────────────────────────────────────
+
+    async health() {
+        return this.ops.system.health();
+    }
+
+    // ── Collections metadata ──────────────────────────────────────────────
+
+    async collections() {
+        const r = await this.http.req('GET', '/v1/_meta/collections');
+        return r.collections || r;
+    }
+
+    // ── OpenAPI / Swagger ─────────────────────────────────────────────────
+
+    async openapi() {
+        return this.ops.documentation.openapi();
+    }
+
+    // ── Gossip Stats ─────────────────────────────────────────────────────
+
+    async gossipStats() {
+        const r = await this.http.req('GET', '/v1/_sync');
+        return r.gossip || {};
+    }
+
+    // ── Secrets ───────────────────────────────────────────────────────────
+
+    get secrets() {
+        if (!this._secrets) this._secrets = new Secrets(this.http, this.ops);
+        return this._secrets;
+    }
+
+
+
+    // ── Triggers ──────────────────────────────────────────────────────────
+
+    get triggers() {
+        if (!this._triggers) this._triggers = new Resource(this.http, '/v1/_triggers', {
+                list: this.ops.trigger.list, create: this.ops.trigger.create,
+                delete: this.ops.trigger.delete, patch: this.ops.trigger.update,
+            });
+        return this._triggers;
+    }
+
+    // ── Webhooks ──────────────────────────────────────────────────────────
+
+    get webhooks() {
+        if (!this._webhooks) this._webhooks = new Webhooks(this.http, this.ops);
+        return this._webhooks;
+    }
+
+    // ── Cron Jobs ─────────────────────────────────────────────────────────
+
+    get crons() {
+        if (!this._crons) this._crons = new Resource(this.http, '/v1/_cron', {
+                list: this.ops.schedule.list, create: this.ops.schedule.create,
+                delete: this.ops.schedule.delete, patch: this.ops.schedule.update,
+            });
+        return this._crons;
+    }
+
+    // ── Views (scheduled) ─────────────────────────────────────────────────
+
+    get views() {
+        if (!this._views) this._views = new Views(this.http, '/v1/_views', this.ops.view, false);
+        return this._views;
+    }
+
+    // ── Live Views ────────────────────────────────────────────────────────
+
+    get live() {
+        if (!this._live) this._live = new Views(this.http, '/v1/_live_views', this.ops.live_view, true);
+        return this._live;
+    }
+
+    // ── Backups ───────────────────────────────────────────────────────────
+
+    get backups() {
+        if (!this._backups) this._backups = new Backups(this.http, this.ops);
+        return this._backups;
+    }
+
+    // ── Jobs ──────────────────────────────────────────────────────────────
+
+    async job(id) {
+        return this.ops.job.get({ id });
+    }
+
+    // ── Rate Limits ───────────────────────────────────────────────────────
+
+    get limits() {
+        if (!this._limits) this._limits = new Resource(this.http, '/v1/_ratelimit', {
+                list: this.ops.rate_limit.list, create: this.ops.rate_limit.set, delete: this.ops.rate_limit.delete,
+            });
+        return this._limits;
+    }
+
+    // ── Security Rules ───────────────────────────────────────────────────
+
+    get rules() {
+        if (!this._rules) {
+            const rules = this.ops.security.rules;
+            this._rules = {
+                set: (config) => rules.set(config),
+                get: () => rules.get(),
+                /** Delete security rules. */
+                delete: () => rules.delete(),
+            };
+        }
+        return this._rules;
+    }
+
+    // ── Security Admin ───────────────────────────────────────────────────
+
+    get security() {
+        if (!this._security) this._security = new Security(this.http);
+        return this._security;
+    }
+
+    // ── Logs ──────────────────────────────────────────────────────────────
+
+    get logs() {
+        if (!this._logs) this._logs = new Logs(this.http, this.ops);
+        return this._logs;
+    }
+
+    // ── Files ─────────────────────────────────────────────────────────────
+
+    get files() {
+        if (!this._files) this._files = new Files(this.http, this.ops);
+        return this._files;
+    }
+
+    // ── Cloud Functions ───────────────────────────────────────────────────
+
+    /** Cloud functions sub-object: db.functions.list(), .invoke(name, body), etc. */
+    get functions() {
+        if (!this._functions) this._functions = new Functions(this.http, this.ops);
+        return this._functions;
+    }
+
+    // ── Deploy ────────────────────────────────────────────────────────────
+
+    async deploy(payload) {
+        return this.ops.function.deploy(payload);
+    }
+
+    // ── Roles ─────────────────────────────────────────────────────────────
+
+    get roles() {
+        if (!this._roles) this._roles = new Resource(this.http, '/v1/_roles', {
+                list: this.ops.role.list, create: this.ops.role.create,
+                delete: this.ops.role.delete, patch: this.ops.role.update,
+            });
+        return this._roles;
+    }
+
+    // ── Projects/Tenants ──────────────────────────────────────────────────
+
+    get projects() {
+        if (!this._projects) this._projects = new Resource(this.http, '/v1/projects', {
+                list: this.ops.tenant.list, create: this.ops.tenant.create, get: this.ops.tenant.get,
+                delete: this.ops.tenant.delete, patch: this.ops.tenant.update,
+            });
+        return this._projects;
+    }
+
+    /** Convenience: create a project/tenant. Alias for db.projects.create(cfg). */
+    async createProject(cfg) { return this.projects.create(cfg); }
+
+    /** Convenience: list all tenants/projects. Alias for db.projects.list(). */
+    async listTenants(opts) { return this.projects.list(opts); }
+
+    /** Convenience: create a collection with options (e.g. acl_flags). */
+    async createCollection(cfg) {
+        const name = cfg.name;
+        if (!name) throw new Error('createCollection: name is required');
+        return this.http.req('POST', `/v1/_meta/collections`, cfg);
+    }
+
+    // ── SubstrioLink Sync ─────────────────────────────────────────────────────
+
+    get sync() {
+        if (!this._sync) this._sync = new Sync(this.http);
+        return this._sync;
+    }
+
+    // ── Tools manifest (AI agent discovery) ───────────────────────────────
+
+
+    // ── AI: grouped sub-object for AI config, audit, tools ─────────────
+
+    /**
+     * AI sub-object: db.ai.config, db.ai.audit(filters), db.ai.tools()
+     *
+     * @example
+     *   const cfg = await db.ai.config.get();
+     *   await db.ai.config.patch({ defaults: { tool_budget_max_calls: 30 } });
+     *   const events = await db.ai.audit({ limit: 10 });
+     *   const tools = await db.ai.tools();
+     */
+    get ai() {
+        if (!this._ai) {
+            const http = this.http;
+            this._ai = {
+                /** AI configuration sub-object: .get(), .set(cfg), .patch(cfg), .delete() */
+                config: {
+                    /** Get resolved AI config (global + tenant merged) */
+                    get: () => http.req('GET', '/v1/_ai/config'),
+                    /** Set full tenant AI config (replaces existing) */
+                    set: (cfg) => http.req('POST', '/v1/_ai/config', cfg),
+                    /** Merge partial update into tenant config */
+                    patch: (cfg) => http.req('PATCH', '/v1/_ai/config', cfg),
+                    /** Remove tenant override (revert to global) */
+                    delete: () => http.req('DELETE', '/v1/_ai/config'),
+                },
+                /** Query the AI agent audit trail. */
+                audit: async (filters = {}) => {
+                    const params = new URLSearchParams();
+                    if (filters.context_id) params.set('context_id', filters.context_id);
+                    if (filters.tool_name) params.set('tool_name', filters.tool_name);
+                    if (filters.since) params.set('since', String(filters.since));
+                    if (filters.limit) params.set('limit', String(filters.limit));
+                    const qs = params.toString();
+                    return http.req('GET', '/v1/_ai/audit' + (qs ? '?' + qs : ''));
+                },
+                /** Get available AI tools manifest. */
+                tools: () => http.req('GET', '/v1/_tools'),
+            };
+        }
+        return this._ai;
+    }
+    // ── Models ────────────────────────────────────────────────────────────
+
+    async models() {
+        return this.ops.ai.models();
+    }
+
+    // ── Stats ─────────────────────────────────────────────────────────────
+
+    async stats() {
+        return this.http.req('GET', '/v1/realtime/stats');
+    }
+
+    // ── WebSocket: Realtime Subscriptions ──────────────────────────────────
+
+    /** Create a Realtime pub/sub connection (WebSocket). */
+    realtime() {
+        return new Realtime(this._url, this._tenant, this._key);
+    }
+
+    // ── WebSocket: Query Streaming ─────────────────────────────────────────
+
+    /** Create a WS query connection (lower-latency alternative to HTTP). */
+    wsQuery() {
+        return new WsQuery(this._url, this._tenant, this._key);
+    }
+
+    /**
+     * Open a binary KV WebSocket connection for ultra-low-latency key-value ops.
+     * @param {string} store - Collection/store name
+     * @returns {Promise<KvWs>} Ready-to-use KvWs client with registered collection
+     */
+    async kvWs(store) {
+        const kv = new KvWs(this._url, this._tenant, this._key);
+        await kv.ready;
+        await kv.register(store);
+        return kv;
+    }
+
+    /**
+     * Open a raw TCP KV connection (text protocol, Memcached-compatible).
+     * Zero WebSocket overhead: direct TCP with string-based parsing.
+     * Ideal for high-throughput KV workloads on localhost.
+     *
+     * @param {string} [store] - KV store/collection name (default: uses server default '_kv_default')
+     * @param {number} [port=9001] - SubstrioWire TCP port
+     * @param {string} [host] - Server host (extracted from url by default)
+     * @returns {Promise<KvTcp>} Ready-to-use KvTcp client
+     */
+    async kvTcp(store, port = 9001, host) {
+        const h = host || new URL(this._url).hostname;
+        const kv = new KvTcp(h, port, this._tenant, this._key);
+        await kv.ready;
+        if (store) await kv.use(store);
+        return kv;
+    }
+
+    /**
+     * Open a binary SubstrioWire TCP KV connection with configurable in-flight depth.
+     * Depth is a client-side sliding window, not server-side batching.
+     *
+     * @param {string} [store] - KV store/collection name
+     * @param {number} [port=9001] - SubstrioWire TCP port
+     * @param {string} [host] - Server host (extracted from url by default)
+     * @param {object} [options] - Binary TCP client options
+     * @param {number} [options.maxInFlight=16] - Max outstanding requests per socket
+     * @returns {Promise<KvWireTcp>} Ready-to-use binary SubstrioWire client
+     */
+    async kvWire(store, port = 9001, host, options = {}) {
+        const h = host || new URL(this._url).hostname;
+        const kv = new KvWireTcp(h, port, this._tenant, this._key, options);
+        await kv.ready;
+        if (store) await kv.register(store);
+        return kv;
+    }
+
+    // ── HTTP KV ───────────────────────────────────────────────────────────
+
+    /**
+     * Get a scoped HTTP KV client for a store.
+     * @param {string} store - KV store/collection name
+     * @returns {KvHttp} Scoped client with set/get/delete methods
+     *
+     * @example
+     *   const kv = db.kv('session');
+     *   await kv.set([['user:1', 'alice'], ['user:2', 'bob']]);
+     *   const r = await kv.get(['user:1', 'user:2']);
+     *   await kv.delete(['user:1']);
+     */
+    kv(store) {
+        return new KvHttp(this.http, store);
+    }
+
+    // ── Graph API ─────────────────────────────────────────────────────────
+
+    /**
+     * Get a scoped Graph client for a labeled edge set.
+     * @param {string} label - Graph edge label (e.g. 'follows', 'likes')
+     * @returns {Graph} Scoped client with addEdge/removeEdge/hasEdge/neighbors/degree/stats
+     *
+     * @example
+     *   const g = db.graph('follows');
+     *   await g.addEdge(1, 2);       // 1 → 2
+     *   await g.neighbors(1);        // [2]
+     *   await g.hasEdge(1, 2);       // true
+     *   await g.degree(1);           // { out_degree: 1, in_degree: 0 }
+     *   await g.removeEdge(1, 2);
+     */
+    graph(label) {
+        return new Graph(this.http, label);
+    }
+
+    /**
+     * List all graph labels across the tenant.
+     * @returns {Promise<{labels: string[], count: number}>}
+     */
+    async graphLabels() {
+        return this.http.req('GET', '/v1/_graph');
+    }
+
+
+    // ── GC / Meta ─────────────────────────────────────────────────────────
+
+    /** Get garbage collection status. */
+    async gc() {
+        return this.http.req('GET', '/v1/_meta/gc');
+    }
+
+    /** Trigger garbage collection. */
+    async runGc() {
+        return this.http.req('POST', '/v1/_meta/gc');
+    }
+
+
+
+    // ── Transactions ──────────────────────────────────────────────────────
+
+    /**
+     * Run an atomic transaction. All operations succeed or all are rolled back.
+     * @param {Array} ops - Array of operation objects:
+     *   { op: 'insert', collection: 'users', doc: { ... } }
+     *   { op: 'update', collection: 'users', id: 'xxx', data: { $set: { ... } } }
+     *   { op: 'delete', collection: 'users', id: 'xxx' }
+     * @returns {{ ok: boolean, count: number, results: Array }}
+     */
+    async transaction(ops) {
+        if (!Array.isArray(ops) || ops.length === 0) {
+            throw new Error('transaction requires a non-empty array of operations');
+        }
+        return this.http.req('POST', '/v1/_batch', { atomic: true, ops });
+    }
+
+    /**
+     * Close this Substrio instance and release all resources.
+     * Aborts in-flight HTTP requests (tears down keep-alive sockets),
+     * closes any cached KV TCP/WS connections and Realtime subscriptions.
+     * The instance should not be used after calling close().
+     */
+    close() {
+        this.http.close();
+    }
+
+    // =========================================================================
+    // Enterprise Type Factories
+    // Static methods for creating the typed JSON wrappers the server stores
+    // typed on insert (src/substrio/core/substrio_typed_value.h).
+    // =========================================================================
+
+    /** Create a DATE typed value. Accepts Date instance, ISO string, or ms-epoch number; sends ms-epoch. */
+    static date(val) {
+        const ms = val instanceof Date ? val.getTime() : typeof val === 'string' ? Date.parse(val) : val;
+        if (!Number.isInteger(ms)) throw new TypeError(`Substrio.date: not a valid date: ${val}`);
+        return { $date: ms };
+    }
+
+    /** Create an INTEGER typed value. For exact int64 values (including > 2^53). */
+    static int(val) { return { $int: val }; }
+
+    /** Create a DECIMAL typed value. For financial/monetary exact decimal. */
+    static decimal(val) { return { $decimal: String(val) }; }
+
+    /** Create a UUID typed value. Auto-generates if no value provided. */
+    static uuid(val) { return { $uuid: val ?? globalThis.crypto?.randomUUID?.() ?? _generateUUID() }; }
+
+    /** Create a BINARY typed value from a base64 string. */
+    static binary(val) { return { $binary: val }; }
+
+    /** Create a REGEX typed value with pattern and optional flags. */
+    static regex(pattern, options) { return { $regex: { pattern, options: options ?? '' } }; }
+
+    /**
+     * Create a BITMAP typed value. Accepts:
+     * - An integer bitmask (e.g. 0b1010, 255, 0xFF)
+     * - An array of booleans (packed into integer, index 0 = bit 0)
+     */
+    static bitmap(val) {
+        if (Array.isArray(val)) {
+            let bits = 0;
+            for (let i = 0; i < val.length; i++) {
+                if (val[i]) bits |= (1 << i);
+            }
+            return { $bitmap: bits };
+        }
+        return { $bitmap: val };
+    }
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Sync: SubstrioLink sync engine control (KCP/UDP transport)
+// ─────────────────────────────────────────────────────────────────────────────
+
+class Sync {
+    constructor(http) { this.http = http; }
+
+    /** Get sync status (gossip mode, peers, collections, oplog). */
+    async status() { return this.http.req('GET', '/v1/_sync'); }
+
+    /** Generic action dispatch. */
+    async action(payload) { return this.http.req('POST', '/v1/_sync', payload); }
+
+    /** Set gossip mode: full_mesh, write_only, receive_only, paused. */
+    async gossipMode(mode) { return this.action({ action: 'set_gossip_mode', mode }); }
+
+    /** Connect to a peer by address (host:port). Optional token for auth. */
+    async connectPeer(address, token) {
+        const payload = { action: 'connect_peer', address };
+        if (token) payload.token = token;
+        return this.action(payload);
+    }
+
+    /** Disconnect a peer by node ID. */
+    async disconnectPeer(peerId) { return this.action({ action: 'disconnect_peer', peer_id: peerId }); }
+
+    /** Remove a peer permanently. */
+    async removePeer(peerId) { return this.action({ action: 'remove_peer', peer_id: peerId }); }
+
+    /** Set per-peer state: active, send_only, receive_only, paused, disconnected. */
+    async peerState(peerId, state) { return this.action({ action: 'set_peer_state', peer_id: peerId, state }); }
+
+    /** Enable sync for a collection. opts: { conflict: 'lww'|'counter_merge'|'max_wins' } */
+    async collectionSync(collection, opts = {}) {
+        return this.action({ action: 'set_collection_sync', collection, ...opts });
+    }
+
+    /** Disable sync for a collection. */
+    async removeCollectionSync(collection) {
+        return this.action({ action: 'remove_collection_sync', collection });
+    }
+
+    /** Create a link token for peer discovery. */
+    async linkToken() { return this.action({ action: 'create_link_token' }); }
+
+    /** Join a cluster using a link token. */
+    async joinToken(token) { return this.action({ action: 'join_with_token', token }); }
+
+    /** Update node config: sync_port, max_peers, etc. */
+    async nodeConfig(cfg) { return this.action({ action: 'set_node_config', ...cfg }); }
+
+    /** Get current node config. */
+    async getNodeConfig() { return this.action({ action: 'get_node_config' }); }
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Resource: reusable base for all REST resources
+// Every resource follows the same predictable API:
+//   resource.list()           → GET
+//   resource.create(config)   → POST
+//   resource.get(id)          → GET /:id
+//   resource.delete(id)       → DELETE /:id
+//   resource.patch(id, data)  → PATCH /:id
+// ─────────────────────────────────────────────────────────────────────────────
+
+// The HTTP method of each resource verb: the route a registry operation
+// with several (secret.write: POST, PUT, DELETE) is called on.
+const VIA = Object.freeze({
+    list: Object.freeze({ method: 'GET' }), create: Object.freeze({ method: 'POST' }),
+    get: Object.freeze({ method: 'GET' }), delete: Object.freeze({ method: 'DELETE' }),
+    patch: Object.freeze({ method: 'PATCH' }),
+});
+
+// Calls `operation` on the record `id` names: the path parameter (id,
+// name, slug, key) of its route for `via`'s method takes it.
+function onRecord(operation, id, data, via) {
+    const routes = operation.operation.routes;
+    const route = routes.find((r) => r.method === via.method && r.params.length) ?? routes.find((r) => r.params.length);
+    return operation({ ...data, [route.params[0]]: id }, via);
+}
+
+/**
+ * A resource's verbs, each its registry operation (`ops`: verb -> a
+ * generated operation of client.ops) where the registry has one, else the
+ * resource's own route under `path`.
+ */
+class Resource {
+    constructor(http, path, ops = {}) { this.http = http; this.path = path; this.ops = ops; }
+
+    async list(opts) {
+        return this.ops.list ? this.ops.list(opts, VIA.list) : this.http.req('GET', `${this.path}${qs(opts)}`);
+    }
+    async create(config) {
+        return this.ops.create ? this.ops.create(config, VIA.create) : this.http.req('POST', this.path, config);
+    }
+    async get(id) {
+        return this.ops.get ? onRecord(this.ops.get, id, {}, VIA.get)
+            : this.http.req('GET', `${this.path}/${encodeURIComponent(id)}`);
+    }
+    /** Delete a resource by ID. */
+    async delete(id) {
+        return this.ops.delete ? onRecord(this.ops.delete, id, {}, VIA.delete)
+            : this.http.req('DELETE', `${this.path}/${encodeURIComponent(id)}`);
+    }
+    async patch(id, data) {
+        return this.ops.patch ? onRecord(this.ops.patch, id, data, VIA.patch)
+            : this.http.req('PATCH', `${this.path}/${encodeURIComponent(id)}`, data);
+    }
+}
+
+// ── Secrets (custom: .set(name, value) instead of .create({...})) ─────────
+
+class Secrets extends Resource {
+    constructor(http, ops) {
+        super(http, '/v1/_secrets', { list: ops.secret.list, create: ops.secret.write, delete: ops.secret.write });
+    }
+    async set(name, value) { return this.ops.create({ key: name, value }, VIA.create); }
+}
+
+// ── Webhooks (custom: .logs(id)) ──────────────────────────────────────────
+
+class Webhooks extends Resource {
+    constructor(http, ops) {
+        const w = ops.webhook;
+        super(http, '/v1/_webhooks', { list: w.list, create: w.create, get: w.get, delete: w.delete, patch: w.update });
+        this.logsOf = w.logs;
+    }
+    async logs(id) { return onRecord(this.logsOf, id, {}, VIA.get); }
+}
+
+// ── Views (auto-normalizes 'collection' → 'source_collection') ───────────
+
+class Views extends Resource {
+    /** `group` is ops.view (scheduled views) or ops.live_view (live views). */
+    constructor(http, path, group, live) {
+        super(http, path, { list: group.list, create: group.create, delete: group.delete, patch: group.update });
+        this.dataOf = group.get;
+        this.live = live;
+    }
+    async create(config) {
+        const body = { ...config };
+        // Live views use 'source_collection', scheduled views use 'collection'
+        if (this.live && body.collection && !body.source_collection) {
+            body.source_collection = body.collection;
+            delete body.collection;
+        }
+        return super.create(body);
+    }
+    async data(name) { return onRecord(this.dataOf, name, {}, VIA.get); }
+}
+
+// ── Backups (custom: .restore(id)) ────────────────────────────────────────
+
+class Backups extends Resource {
+    constructor(http, ops) {
+        const b = ops.backup;
+        super(http, '/v1/_backups', { list: b.list, create: b.create, get: b.get, delete: b.delete });
+        this.restoreOf = b.restore;
+    }
+    async restore(id) { return onRecord(this.restoreOf, id, {}, VIA.create); }
+}
+
+// ── Logs ───────────────────────────────────────────────────────────────────
+
+class Logs extends Resource {
+    constructor(http, ops) { super(http, '/v1/_logs', { list: ops.function.logs }); }
+    async clear() { return this.ops.list.clear(); }
+}
+
+// ── Files (custom upload with content-type headers) ───────────────────────
+
+class Files extends Resource {
+    constructor(http, ops) {
+        const f = ops.file;
+        super(http, '/v1/files', { list: f.list, get: f.download, delete: f.delete });
+    }
+    async upload(data, filename, contentType) {
+        const extra = {};
+        if (contentType) extra['Content-Type'] = contentType;
+        if (filename) extra['X-Filename'] = filename;
+        return this.http.req('POST', this.path, data, extra);
+    }
+    async download(id) { return this.get(id); }
+}
+
+// ── Cloud Functions ───────────────────────────────────────────────────────
+
+class Functions extends Resource {
+    constructor(http, ops) {
+        const f = ops.function;
+        super(http, '/v1/functions', { list: f.list, create: f.deploy, get: f.get, delete: f.delete, patch: f.update });
+    }
+    /** Deploy a cloud function. @param {{ name: string, script: string }} config */
+    async deploy(config) { return this.create(config); }
+    async invoke(name, body) {
+        return this.http.req('POST', `/fn/${encodeURIComponent(name)}`, body);
+    }
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Realtime: WebSocket pub/sub subscriptions (/v1/realtime)
+//
+// Usage:
+//   const rt = db.realtime();
+//   await rt.ready;
+//   rt.subscribe({ collection: 'posts', field: 'city', value: 'NYC' });
+//   rt.on('notification', ev => console.log(ev));
+//   rt.close();
+// ─────────────────────────────────────────────────────────────────────────────
+
+class Realtime {
+    constructor(url, tenant, key) {
+        const wsUrl = url.replace(/^http/, 'ws');
+        const headers = { 'X-Substrio-Tenant': tenant };
+        if (key) headers['X-Substrio-Master-Key'] = key;
+        this._handlers = {};
+        this._ws = new WebSocket(`${wsUrl}/v1/realtime`, { headers });
+        this._ws.onmessage = (ev) => {
+            try {
+                const msg = JSON.parse(ev.data);
+                const type = msg.type || (msg.error ? 'error' : 'message');
+                if (this._handlers[type]) this._handlers[type].forEach(fn => fn(msg));
+                if (this._handlers['*']) this._handlers['*'].forEach(fn => fn(msg));
+            } catch { }
+        };
+        let readyReject;
+        this._ws.onerror = (ev) => {
+            if (readyReject) { readyReject(ev); readyReject = null; }
+            if (this._handlers.error) this._handlers.error.forEach(fn => fn(ev));
+        };
+        this.ready = new Promise((resolve, reject) => {
+            readyReject = reject;
+            this._ws.onopen = () => { readyReject = null; resolve(this); };
+        });
+    }
+
+    /** Register handler: type = 'connected'|'pong'|'subscribed'|'notification'|'error'|'*' */
+    on(type, fn) {
+        (this._handlers[type] ||= []).push(fn);
+        return this;
+    }
+
+    /** Send a raw message. */
+    send(msg) {
+        this._ws.send(typeof msg === 'string' ? msg : JSON.stringify(msg));
+    }
+
+    /** Subscribe to a field-value pair on a collection. */
+    subscribe(opts) {
+        this.send({ type: 'subscribe', ...opts });
+    }
+
+    /** Subscribe to ALL changes (insert/update/delete) on a collection. */
+    subscribeCollection(collection) {
+        this.send({ type: 'subscribe_collection', collection });
+    }
+
+    /** Unsubscribe from collection-level change stream. */
+    unsubscribeCollection(collection) {
+        this.send({ type: 'unsubscribe_collection', collection });
+    }
+
+    /**
+     * Batch subscribe to multiple field-value pairs. The 'subscribed_batch'
+     * reply answers every entry in request order: results[i] is { topic } or
+     * { code, error } ('invalid_subscription', 'subscription_limit'); count is
+     * how many were taken.
+     */
+    subscribeBatch(subscriptions) {
+        this.send({ type: 'subscribe_batch', subscriptions });
+    }
+
+    /** Send ping. */
+    ping() { this.send({ type: 'ping' }); }
+
+    /** Close the connection. */
+    close() {
+        if (this._ws.readyState <= 1) this._ws.close();
+    }
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// ChangeStream: CDC / Resumable Change Stream
+//
+// Usage:
+//   const stream = db.col('orders').watch((event) => {
+//       console.log(event.operation, event._seq);
+//   }, { resumeAfter: '12345' });
+//   stream.resumeToken;  // latest _seq seen, or null: none sent (no change history)
+//   stream.close();
+// ─────────────────────────────────────────────────────────────────────────────
+
+class ChangeStream {
+    /**
+     * @param {string} url - Substrio server URL
+     * @param {string} tenant - Tenant slug
+     * @param {string} key - Master key
+     * @param {string} collection - Collection name
+     * @param {function} callback - Event handler: receives {type, collection, operation, _seq, _ts, ...}
+     * @param {object} [options] - { resumeAfter: string }
+     */
+    constructor(url, tenant, key, collection, callback, options = {}) {
+        this._url = url;
+        this._tenant = tenant;
+        this._key = key;
+        this._collection = collection;
+        this._callback = callback;
+        this._resumeAfter = options.resumeAfter || null;
+        // The newest _seq received: a position in the app's change history,
+        // the only thing a stream resumes after. null while none came: an
+        // app without change history sends no _seq, and such a stream
+        // reconnects as a new subscription, never resumes (B109ag).
+        this._resumeToken = this._resumeAfter;
+        this._closed = false;
+        this._reconnectAttempts = 0;
+        this._maxReconnectDelay = 30000;
+        this._ws = null;
+        this._subscribeAck = null;
+
+        // Ready promise resolves when first subscribe_collection ack received
+        this.ready = new Promise((resolve, reject) => {
+            this._readyResolve = resolve;
+            this._readyReject = reject;
+        });
+
+        this._connect();
+    }
+
+    /** Latest _seq received (a history position), or null when none came. Use as resumeAfter on reconnect. */
+    get resumeToken() { return this._resumeToken; }
+
+    /** @private Keeps the newest _seq of a message; one without _seq changes nothing. */
+    _advanceResumeToken(msg) {
+        if (msg._seq === undefined) return;
+        if (this._resumeToken === null || BigInt(msg._seq) > BigInt(this._resumeToken)) {
+            this._resumeToken = msg._seq;
+        }
+    }
+
+    /** Number of events replayed on subscribe (from resumeAfter). */
+    get replayedCount() { return this._replayedCount || 0; }
+
+    /** Close the change stream permanently. */
+    close() {
+        this._closed = true;
+        if (this._reconnectTimer) { clearTimeout(this._reconnectTimer); this._reconnectTimer = null; }
+        if (this._ws) {
+            // Remove event handlers before closing to prevent onclose triggering reconnect
+            this._ws.onclose = null;
+            this._ws.onmessage = null;
+            this._ws.onerror = null;
+            if (this._ws.readyState <= 1) this._ws.close();
+            this._ws = null;
+        }
+        // Null out references to prevent structured clone issues in test runners
+        this._callback = null;
+        this._readyResolve = null;
+        this._readyReject = null;
+    }
+
+    /** @private */
+    _connect() {
+        if (this._closed) return;
+
+        const wsUrl = this._url.replace(/^http/, 'ws');
+        const headers = { 'X-Substrio-Tenant': this._tenant };
+        if (this._key) headers['X-Substrio-Master-Key'] = this._key;
+
+        this._ws = new WebSocket(`${wsUrl}/v1/realtime`, { headers });
+
+        this._ws.onopen = () => {
+            this._reconnectAttempts = 0;
+            // Subscribe with optional resumeAfter
+            const msg = { type: 'subscribe_collection', collection: this._collection };
+            if (this._resumeAfter) {
+                msg.resumeAfter = String(this._resumeAfter);
+            }
+            this._ws.send(JSON.stringify(msg));
+        };
+
+        this._ws.onmessage = (ev) => {
+            try {
+                const msg = JSON.parse(ev.data);
+
+                if (msg.type === 'subscribed_collection') {
+                    // Ack: the replay count, and _seq on a history stream
+                    this._subscribeAck = msg;
+                    this._replayedCount = Number(msg._replayed || 0);
+                    this._advanceResumeToken(msg);
+                    if (this._readyResolve) {
+                        this._readyResolve(this);
+                        this._readyResolve = null;
+                    }
+                    return;
+                }
+
+                if (msg.type === 'change') {
+                    this._advanceResumeToken(msg);
+                    this._callback(msg);
+                    return;
+                }
+
+                if (msg.type === 'error') {
+                    // A typed refusal, e.g. history_not_kept: the resume point
+                    // is not in the kept history, so the changes since it
+                    // cannot be replayed. The token is dropped (a reconnect
+                    // never resumes from it again) and ready rejects: the
+                    // caller reads the collection again.
+                    this._resumeToken = null;
+                    this._resumeAfter = null;
+                    if (this._readyReject) {
+                        this._readyReject(new SubstrioError(0, msg.code || '', msg.error || 'change stream refused', msg));
+                        this._readyReject = null;
+                        this._readyResolve = null;
+                    }
+                }
+            } catch { }
+        };
+
+        this._ws.onerror = (ev) => {
+            if (this._readyReject) {
+                this._readyReject(ev);
+                this._readyReject = null;
+            }
+        };
+
+        this._ws.onclose = () => {
+            if (this._closed) return;
+            // Auto-reconnect with exponential backoff: resumes after the last
+            // _seq, or subscribes anew when the stream sent none.
+            this._resumeAfter = this._resumeToken;
+            const delay = Math.min(1000 * Math.pow(2, this._reconnectAttempts), this._maxReconnectDelay);
+            this._reconnectAttempts++;
+            this._reconnectTimer = setTimeout(() => this._connect(), delay);
+        };
+    }
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// WsQuery: WebSocket query streaming (/v1/query/ws)
+//
+// Usage:
+//   const ws = db.wsQuery();
+//   await ws.ready;
+//   const result = await ws.query({ where: {} });
+//   ws.close();
+// ─────────────────────────────────────────────────────────────────────────────
+
+class WsQuery {
+    constructor(url, tenant, key) {
+        const wsUrl = url.replace(/^http/, 'ws');
+        const headers = { 'X-Substrio-Tenant': tenant };
+        if (key) headers['X-Substrio-Master-Key'] = key;
+        this._ws = new WebSocket(`${wsUrl}/v1/query/ws`, { headers });
+        this._pending = null;
+        this._ws.onmessage = (ev) => {
+            if (this._pending) {
+                try {
+                    this._pending.resolve(JSON.parse(ev.data));
+                } catch (e) {
+                    this._pending.resolve(ev.data);
+                }
+                this._pending = null;
+            }
+        };
+        this._ws.onerror = (ev) => {
+            if (this._pending) { this._pending.reject(ev); this._pending = null; }
+        };
+        this.ready = new Promise((resolve, reject) => {
+            this._ws.onopen = () => resolve(this);
+            this._ws.onerror = (e) => reject(e);
+        });
+    }
+
+    /** Send a query and await the response. */
+    query(body) {
+        return new Promise((resolve, reject) => {
+            this._pending = { resolve, reject };
+            this._ws.send(JSON.stringify(body));
+        });
+    }
+
+    /** Close the connection. */
+    close() {
+        if (this._ws.readyState <= 1) this._ws.close();
+    }
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// KvWs: Binary KV WebSocket client (/v1/kv/ws)
+//
+// Zero-overhead binary protocol. Uses ArrayBuffer/DataView for zero-copy.
+// No JSON, no Buffer, no string intermediaries in the hot path.
+//
+// Usage:
+//   const kv = await db.kvWs('my_store');
+//   await kv.put([['k1','v1'], ['k2','v2']]);
+//   const vals = await kv.get(['k1','k2']);  // Map { 'k1' => 'v1', ... }
+//   await kv.delete(['k1']);
+//   kv.close();
+// ─────────────────────────────────────────────────────────────────────────────
+
+const _kvEnc = new TextEncoder();
+const _kvDec = new TextDecoder();
+
+export class KvWs {
+    static OP_PUT = 0x01;
+    static OP_GET = 0x02;
+    static OP_DEL = 0x03;
+    static OP_REG = 0x10;
+    static OP_ERR = 0xFF;
+
+    constructor(url, tenant, key) {
+        const wsUrl = url.replace(/^http/, 'ws');
+        const headers = { 'X-Substrio-Tenant': tenant };
+        if (key) headers['X-Substrio-Master-Key'] = key;
+        this._ws = new WebSocket(`${wsUrl}/v1/kv/ws`, { headers });
+        this._ws.binaryType = 'arraybuffer';
+        this._pending = null;
+        this._colId = 0;
+        // Pre-allocated reusable send buffer (64KB): eliminates per-op ArrayBuffer+DataView alloc
+        this._reuseBuf = new ArrayBuffer(65536);
+        this._reuseDv = new DataView(this._reuseBuf);
+        this._reuseU8 = new Uint8Array(this._reuseBuf);
+        this._ws.onmessage = (ev) => {
+            if (this._pending) {
+                const p = this._pending;
+                this._pending = null;
+                // Zero-copy: use ArrayBuffer directly from WebSocket frame
+                p.resolve(new Uint8Array(ev.data instanceof ArrayBuffer ? ev.data : ev.data.buffer || ev.data));
+            }
+        };
+        this._ws.onerror = (ev) => {
+            if (this._pending) { const p = this._pending; this._pending = null; p.reject(ev); }
+        };
+        this.ready = new Promise((resolve, reject) => {
+            this._ws.onopen = () => resolve(this);
+            this._ws.onerror = (e) => reject(e);
+        });
+    }
+
+    _send(buf, len) {
+        return new Promise((resolve, reject) => {
+            this._pending = { resolve, reject };
+            // If len provided, send a subarray view (reusable buffer path)
+            if (len !== undefined) {
+                this._ws.send(new Uint8Array(buf, 0, len));
+            } else {
+                this._ws.send(buf);
+            }
+        });
+    }
+
+    /** Register a collection → get 1-byte handle. */
+    async register(name) {
+        const nb = _kvEnc.encode(name);
+        const buf = new ArrayBuffer(4 + nb.length);
+        const dv = new DataView(buf);
+        dv.setUint8(0, 0x10); dv.setUint8(1, 0);
+        dv.setUint16(2, nb.length, true);
+        new Uint8Array(buf).set(nb, 4);
+        const r = await this._send(buf);
+        if (r[0] !== 0x10 || r[2] !== 1) throw new Error('KvWs: register failed');
+        this._colId = r[1];
+        return this._colId;
+    }
+
+    /** PUT [[key,val],...] → number of successes. */
+    async put(pairs) {
+        const enc = new Array(pairs.length);
+        let sz = 4;
+        for (let i = 0; i < pairs.length; i++) {
+            const k = _kvEnc.encode(pairs[i][0]), v = _kvEnc.encode(pairs[i][1]);
+            enc[i] = { k, v }; sz += 6 + k.length + v.length;
+        }
+        // Reuse pre-allocated buffer when payload fits (hot path for single-key ops)
+        const reuse = sz <= 65536;
+        const dv = reuse ? this._reuseDv : new DataView(new ArrayBuffer(sz));
+        const u = reuse ? this._reuseU8 : new Uint8Array(dv.buffer);
+        dv.setUint8(0, 0x01); dv.setUint8(1, this._colId);
+        dv.setUint16(2, pairs.length, true);
+        let o = 4;
+        for (const { k, v } of enc) {
+            dv.setUint16(o, k.length, true); o += 2;
+            dv.setUint32(o, v.length, true); o += 4;
+            u.set(k, o); o += k.length;
+            u.set(v, o); o += v.length;
+        }
+        const r = await this._send(dv.buffer, reuse ? sz : undefined);
+        if (r[0] === 0xFF) throw new Error('KvWs PUT: ' + _kvDec.decode(r.subarray(3)));
+        const cnt = r[1] | (r[2] << 8);
+        let ok = 0;
+        for (let i = 0; i < cnt; i++) if (r[3 + (i >> 3)] & (1 << (i & 7))) ok++;
+        return ok;
+    }
+
+    /** GET [key,...] → Map<string, string|null>. */
+    async get(keys) {
+        const kb = new Array(keys.length);
+        let sz = 4;
+        for (let i = 0; i < keys.length; i++) { kb[i] = _kvEnc.encode(keys[i]); sz += 2 + kb[i].length; }
+        // Reuse pre-allocated buffer when payload fits
+        const reuse = sz <= 65536;
+        const dv = reuse ? this._reuseDv : new DataView(new ArrayBuffer(sz));
+        const u = reuse ? this._reuseU8 : new Uint8Array(dv.buffer);
+        dv.setUint8(0, 0x02); dv.setUint8(1, this._colId);
+        dv.setUint16(2, keys.length, true);
+        let o = 4;
+        for (const b of kb) { dv.setUint16(o, b.length, true); o += 2; u.set(b, o); o += b.length; }
+        const r = await this._send(dv.buffer, reuse ? sz : undefined);
+        if (r[0] === 0xFF) throw new Error('KvWs GET: ' + _kvDec.decode(r.subarray(3)));
+        const cnt = r[1] | (r[2] << 8);
+        const m = new Map();
+        let p = 3;
+        for (let i = 0; i < cnt && p < r.length; i++) {
+            if (r[p++] === 1 && p + 4 <= r.length) {
+                const vl = r[p] | (r[p + 1] << 8) | (r[p + 2] << 16) | ((r[p + 3] << 24) >>> 0); p += 4;
+                m.set(keys[i], _kvDec.decode(r.subarray(p, p + vl))); p += vl;
+            } else { m.set(keys[i], null); }
+        }
+        return m;
+    }
+
+    /** DEL [key,...] → number of deleted. */
+    async del(keys) {
+        const kb = new Array(keys.length);
+        let sz = 4;
+        for (let i = 0; i < keys.length; i++) { kb[i] = _kvEnc.encode(keys[i]); sz += 2 + kb[i].length; }
+        // Reuse pre-allocated buffer when payload fits
+        const reuse = sz <= 65536;
+        const dv = reuse ? this._reuseDv : new DataView(new ArrayBuffer(sz));
+        const u = reuse ? this._reuseU8 : new Uint8Array(dv.buffer);
+        dv.setUint8(0, 0x03); dv.setUint8(1, this._colId);
+        dv.setUint16(2, keys.length, true);
+        let o = 4;
+        for (const b of kb) { dv.setUint16(o, b.length, true); o += 2; u.set(b, o); o += b.length; }
+        const r = await this._send(dv.buffer, reuse ? sz : undefined);
+        if (r[0] === 0xFF) throw new Error('KvWs DEL: ' + _kvDec.decode(r.subarray(3)));
+        const cnt = r[1] | (r[2] << 8);
+        let ok = 0;
+        for (let i = 0; i < cnt; i++) if (r[3 + (i >> 3)] & (1 << (i & 7))) ok++;
+        return ok;
+    }
+
+    /** Alias for del(): matches idiomatic JS naming. */
+    async delete(keys) { return this.del(keys); }
+
+    /** Send raw frame, get raw Uint8Array. For benchmarks. */
+    async raw(frame) { return this._send(frame); }
+
+    close() { if (this._ws.readyState <= 1) this._ws.close(); }
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// KvTcp: Raw TCP text-protocol KV client (SubstrioWire)
+//
+// Memcached-compatible text protocol over raw TCP.
+// Uses setEncoding('utf8') + indexOf('\r\n') for maximum V8 string perf.
+// Zero Buffer allocations in the hot path.
+//
+// Usage:
+//   const kv = await db.kvTcp(9001);
+//   await kv.set('key', 'value');
+//   const val = await kv.get('key');   // 'value' or null
+//   await kv.delete('key');
+//   kv.close();
+// ─────────────────────────────────────────────────────────────────────────────
+
+export class KvTcp {
+    constructor(host, port, tenant, key) {
+        this._queue = [];
+        this._buf = '';
+
+        this.ready = (async () => {
+            const net = (await import('net')).default || await import('net');
+            this._sock = net.connect(port, host);
+            this._sock.setEncoding('utf8');
+            this._sock.setNoDelay(true);
+            this._sock.on('data', (c) => this._onData(c));
+            this._sock.on('error', (err) => {
+                if (this._queue.length) this._queue.shift().reject(err);
+            });
+
+            await new Promise((resolve, reject) => {
+                this._sock.once('connect', resolve);
+                this._sock.once('error', reject);
+            });
+
+            // AUTH on connect
+            const authResp = await this._send(
+                `AUTH ${tenant} ${key}\r\n`,
+                this._lineParser
+            );
+            if (authResp !== 'OK') throw new Error('KvTcp: auth failed: ' + authResp);
+
+            return this;
+        })();
+    }
+
+    _onData(chunk) {
+        this._buf += chunk;
+        while (this._queue.length) {
+            const head = this._queue[0];
+            const result = head.parser(this._buf);
+            if (result === null) break;
+            this._queue.shift();
+            this._buf = result.rest;
+            head.resolve(result.value);
+        }
+    }
+
+    _send(cmd, parser) {
+        return new Promise((resolve, reject) => {
+            this._queue.push({ resolve, reject, parser });
+            this._sock.write(cmd);
+        });
+    }
+
+    _lineParser(buf) {
+        const i = buf.indexOf('\r\n');
+        if (i < 0) return null;
+        return { value: buf.substring(0, i), rest: buf.substring(i + 2) };
+    }
+
+    _getParser(buf) {
+        const endIdx = buf.indexOf('END\r\n');
+        if (endIdx === -1) return null;
+        const block = buf.substring(0, endIdx);
+        const rest = buf.substring(endIdx + 5);
+        if (block.startsWith('VALUE')) {
+            const firstLine = block.indexOf('\r\n');
+            const data = block.substring(firstLine + 2).replace(/\r\n$/, '');
+            return { value: data, rest };
+        }
+        return { value: null, rest };
+    }
+
+    /** Switch to a different KV collection. Tree handle is cached: zero overhead after first call. */
+    async use(collection) {
+        const r = await this._send(`USE ${collection}\r\n`, this._lineParser);
+        if (r !== 'OK') throw new Error('KvTcp: USE failed: ' + r);
+        return true;
+    }
+
+    /** SET key=value. Returns true on success. */
+    async set(key, value) {
+        const cmd = `set ${key} 0 0 ${Buffer.byteLength(value)}\r\n${value}\r\n`;
+        const r = await this._send(cmd, this._lineParser);
+        return r === 'STORED';
+    }
+
+    /** GET key → value string or null. */
+    async get(key) {
+        return this._send(`get ${key}\r\n`, this._getParser);
+    }
+
+    /** DEL key → true if deleted, false if not found. */
+    async del(key) {
+        const r = await this._send(`delete ${key}\r\n`, this._lineParser);
+        return r === 'DELETED';
+    }
+
+    /** Alias for del(): matches idiomatic JS naming. */
+    async delete(key) { return this.del(key); }
+
+    /** PUT [[key,val],...] → number of successes (sequential, one await per key). */
+    async put(pairs) {
+        let ok = 0;
+        for (const [k, v] of pairs) {
+            if (await this.set(k, v)) ok++;
+        }
+        return ok;
+    }
+
+    /**
+     * PIPELINE SET [[key,val],...] → number of successes.
+     * Sends ALL commands in a single socket.write() (one syscall), then drains
+     * all responses in one pass. Eliminates per-op roundtrip latency entirely.
+     */
+    async pipeSet(pairs) {
+        if (!pairs.length) return 0;
+        const total = pairs.length;
+        // Build all commands into a single buffer
+        let cmd = '';
+        for (const [k, v] of pairs) {
+            cmd += `set ${k} 0 0 ${Buffer.byteLength(v)}\r\n${v}\r\n`;
+        }
+        // Custom parser: counts STORED/error lines until all N responses received.
+        // Tracks consumed offset so re-reads never happen when _onData passes
+        // the full buffer on subsequent calls after a partial return.
+        let ok = 0, remaining = total, consumed = 0;
+        const pipeParser = (buf) => {
+            let pos = consumed;
+            while (remaining > 0) {
+                const nl = buf.indexOf('\r\n', pos);
+                if (nl < 0) { consumed = pos; return null; } // need more data
+                const line = buf.substring(pos, nl);
+                pos = nl + 2;
+                if (line === 'STORED') ok++;
+                remaining--;
+            }
+            consumed = pos;
+            return { value: ok, rest: buf.substring(pos) };
+        };
+        return this._send(cmd, pipeParser);
+    }
+
+    /**
+     * PIPELINE GET [key,...] → [value|null, ...].
+     * Sends ALL get commands in a single write, drains all VALUE/END blocks.
+     */
+    async pipeGet(keys) {
+        if (!keys.length) return [];
+        const total = keys.length;
+        let cmd = '';
+        for (const k of keys) cmd += `get ${k}\r\n`;
+        // Custom parser: collects N get responses (VALUE...END or just END).
+        // Tracks consumed offset to avoid re-reading on partial returns.
+        const results = [];
+        let remaining = total, consumed = 0;
+        const pipeParser = (buf) => {
+            let pos = consumed;
+            while (remaining > 0) {
+                const endIdx = buf.indexOf('END\r\n', pos);
+                if (endIdx === -1) { consumed = pos; return null; } // need more data
+                const block = buf.substring(pos, endIdx);
+                pos = endIdx + 5;
+                if (block.startsWith('VALUE')) {
+                    const firstLine = block.indexOf('\r\n');
+                    results.push(block.substring(firstLine + 2).replace(/\r\n$/, ''));
+                } else {
+                    results.push(null);
+                }
+                remaining--;
+            }
+            consumed = pos;
+            return { value: results, rest: buf.substring(pos) };
+        };
+        return this._send(cmd, pipeParser);
+    }
+
+    /** Flush all keys. */
+    async flush() {
+        return this._send('flush_all\r\n', this._lineParser);
+    }
+
+    /** INCR key delta → new numeric value. Returns null if key not found. */
+    async incr(key, delta = 1) {
+        const r = await this._send(`incr ${key} ${delta}\r\n`, this._lineParser);
+        if (r === 'NOT_FOUND') return null;
+        if (r.startsWith('CLIENT_ERROR')) throw new Error(r);
+        return parseInt(r, 10);
+    }
+
+    /** DECR key delta → new numeric value. Returns null if key not found. Floors at 0. */
+    async decr(key, delta = 1) {
+        const r = await this._send(`decr ${key} ${delta}\r\n`, this._lineParser);
+        if (r === 'NOT_FOUND') return null;
+        if (r.startsWith('CLIENT_ERROR')) throw new Error(r);
+        return parseInt(r, 10);
+    }
+
+    /** ADD key value: set only if key does NOT exist. Returns true if stored. */
+    async add(key, value) {
+        const cmd = `add ${key} 0 0 ${Buffer.byteLength(value)}\r\n${value}\r\n`;
+        const r = await this._send(cmd, this._lineParser);
+        return r === 'STORED';
+    }
+
+    /** REPLACE key value: set only if key DOES exist. Returns true if stored. */
+    async replace(key, value) {
+        const cmd = `replace ${key} 0 0 ${Buffer.byteLength(value)}\r\n${value}\r\n`;
+        const r = await this._send(cmd, this._lineParser);
+        return r === 'STORED';
+    }
+
+    /** APPEND suffix to existing value. Returns true if stored. Key must exist. */
+    async append(key, suffix) {
+        const bytes = Buffer.byteLength(suffix);
+        const cmd = `append ${key} 0 0 ${bytes}\r\n${suffix}\r\n`;
+        const r = await this._send(cmd, this._lineParser);
+        return r === 'STORED';
+    }
+
+    /** PREPEND prefix to existing value. Returns true if stored. Key must exist. */
+    async prepend(key, prefix) {
+        const bytes = Buffer.byteLength(prefix);
+        const cmd = `prepend ${key} 0 0 ${bytes}\r\n${prefix}\r\n`;
+        const r = await this._send(cmd, this._lineParser);
+        return r === 'STORED';
+    }
+
+    /** EXISTS key → boolean. Checks existence without fetching value. */
+    async exists(key) {
+        const r = await this._send(`exists ${key}\r\n`, this._lineParser);
+        return r === 'EXISTS';
+    }
+
+    /** LEN key → byte length of value, or null if not found. */
+    async len(key) {
+        const r = await this._send(`len ${key}\r\n`, this._lineParser);
+        if (r === 'NOT_FOUND') return null;
+        return parseInt(r, 10);
+    }
+
+    /** GETDEL key → value string (atomically deletes), or null if not found. */
+    async getdel(key) {
+        return this._send(`getdel ${key}\r\n`, this._getParser);
+    }
+
+    /** VERSION → server version string. */
+    async version() {
+        const r = await this._send('version\r\n', this._lineParser);
+        return r.startsWith('VERSION ') ? r.substring(8) : r;
+    }
+
+    /** STATS → Map<string, string> of server statistics. */
+    async stats() {
+        const statsParser = (buf) => {
+            const endIdx = buf.indexOf('END\r\n');
+            if (endIdx === -1) return null;
+            const block = buf.substring(0, endIdx);
+            const rest = buf.substring(endIdx + 5);
+            const m = new Map();
+            for (const line of block.split('\r\n')) {
+                if (line.startsWith('STAT ')) {
+                    const sp = line.indexOf(' ', 5);
+                    if (sp > 0) m.set(line.substring(5, sp), line.substring(sp + 1));
+                }
+            }
+            return { value: m, rest };
+        };
+        return this._send('stats\r\n', statsParser);
+    }
+
+    /** SCAN prefix [limit] → [[key, value], ...]. Prefix scan over keys. */
+    async scan(prefix, limit = 100) {
+        const scanParser = (buf) => {
+            const endIdx = buf.indexOf('END\r\n');
+            if (endIdx === -1) return null;
+            const block = buf.substring(0, endIdx);
+            const rest = buf.substring(endIdx + 5);
+            const results = [];
+            const lines = block.split('\r\n');
+            let i = 0;
+            while (i < lines.length) {
+                if (lines[i].startsWith('VALUE ')) {
+                    const parts = lines[i].split(' ');
+                    const key = parts[1];
+                    const bytes = parseInt(parts[3], 10);
+                    // Value is on next line
+                    i++;
+                    if (i < lines.length) {
+                        results.push([key, lines[i]]);
+                    }
+                }
+                i++;
+            }
+            return { value: results, rest };
+        };
+        return this._send(`scan ${prefix} ${limit}\r\n`, scanParser);
+    }
+
+    /** MGET [key,...] → Map<key, value|null>. Multi-key get in a single call. */
+    async mget(keys) {
+        if (!keys.length) return new Map();
+        // Build multi-key get: "get key1 key2 key3\r\n"
+        // Each key returns its own VALUE...END block, so we pipeline individual gets
+        const total = keys.length;
+        let cmd = '';
+        for (const k of keys) cmd += `get ${k}\r\n`;
+        const results = new Map();
+        let remaining = total, consumed = 0, idx = 0;
+        const mgetParser = (buf) => {
+            let pos = consumed;
+            while (remaining > 0) {
+                const endIdx = buf.indexOf('END\r\n', pos);
+                if (endIdx === -1) { consumed = pos; return null; }
+                const block = buf.substring(pos, endIdx);
+                pos = endIdx + 5;
+                if (block.startsWith('VALUE')) {
+                    const firstLine = block.indexOf('\r\n');
+                    results.set(keys[idx], block.substring(firstLine + 2).replace(/\r\n$/, ''));
+                } else {
+                    results.set(keys[idx], null);
+                }
+                idx++;
+                remaining--;
+            }
+            consumed = pos;
+            return { value: results, rest: buf.substring(pos) };
+        };
+        return this._send(cmd, mgetParser);
+    }
+
+    /** GETS key → {value, cas} or null. Returns value with CAS version token. */
+    async gets(key) {
+        const getsParser = (buf) => {
+            const endIdx = buf.indexOf('END\r\n');
+            if (endIdx === -1) return null;
+            const block = buf.substring(0, endIdx);
+            const rest = buf.substring(endIdx + 5);
+            if (block.startsWith('VALUE')) {
+                // VALUE key flags bytes cas_token\r\ndata
+                const firstLine = block.indexOf('\r\n');
+                const header = block.substring(0, firstLine);
+                const parts = header.split(' ');
+                const cas = parts[4];  // CAS token (version_timestamp as decimal string)
+                const data = block.substring(firstLine + 2).replace(/\r\n$/, '');
+                return { value: { value: data, cas }, rest };
+            }
+            return { value: null, rest };
+        };
+        return this._send(`gets ${key}\r\n`, getsParser);
+    }
+
+    /** CAS key value cas_token → 'STORED'|'EXISTS'|'NOT_FOUND'. Compare-and-swap. */
+    async cas(key, value, casToken) {
+        const bytes = Buffer.byteLength(value);
+        const cmd = `cas ${key} 0 0 ${bytes} ${casToken}\r\n${value}\r\n`;
+        const r = await this._send(cmd, this._lineParser);
+        return r;  // 'STORED', 'EXISTS', or 'NOT_FOUND'
+    }
+
+    close() {
+        if (this._sock) {
+            this._sock.destroy();
+            this._sock = null;
+        }
+    }
+}