@net-mesh/core 0.21.0 → 0.22.0

package/aggregator.d.ts

@@ -0,0 +1,56 @@
+export type RegistryErrorKind = 'transport' | 'codec' | 'unknown-template' | 'duplicate-group-name' | 'spawn-rejected' | 'spawn-not-supported' | 'invalid-args';
+export type FoldQueryErrorKind = 'transport' | 'codec' | 'unknown-kind' | 'invalid-args';
+export declare class RegistryClientError extends Error {
+    readonly kind: RegistryErrorKind;
+    readonly serverDetail?: string;
+    constructor(kind: RegistryErrorKind, detail: string);
+}
+export declare class FoldQueryClientError extends Error {
+    readonly kind: FoldQueryErrorKind;
+    readonly serverDetail?: string;
+    constructor(kind: FoldQueryErrorKind, detail: string);
+}
+/**
+ * Inspect an error message for the `agg:` prefix and return the
+ * structured `{kind, detail}` if it matches. Returns `null` when
+ * the message is missing the prefix or is malformed.
+ */
+export declare function parseAggregatorError(e: unknown): {
+    kind: string;
+    detail: string;
+} | null;
+/**
+ * Re-throw a typed error for the given raw error if it carries the
+ * `agg:` prefix. Non-matching errors pass through unchanged so
+ * `throw classifyAggregatorError(e)` is safe at any catch site.
+ *
+ * Routes to `RegistryClientError` for registry-shaped kinds and
+ * `FoldQueryClientError` for fold-query-shaped kinds. Both surfaces
+ * share `transport` / `codec` / `invalid-args`; we route by the
+ * caller's typing — pass an explicit `surface` if you know which
+ * client raised it, otherwise the default routing biases to
+ * `RegistryClientError` for shared kinds (the substrate's primary
+ * surface).
+ */
+export declare function classifyAggregatorError(e: unknown, surface?: 'registry' | 'fold-query'): unknown;
+export interface RegistryReplicaRow {
+    generation: bigint;
+    healthy: boolean;
+    diagnostic?: string;
+    placementNodeId?: bigint;
+}
+export interface RegistryGroupSummary {
+    name: string;
+    groupSeedHex: string;
+    replicas: RegistryReplicaRow[];
+}
+export interface SummaryBucket {
+    name: string;
+    count: bigint;
+}
+export interface SummaryAnnouncement {
+    foldKind: number;
+    sourceSubnet: string;
+    generation: bigint;
+    buckets: SummaryBucket[];
+}

package/aggregator.js

@@ -0,0 +1,130 @@
+"use strict";
+// Typed error classes + classifier for the `aggregator.registry`
+// / `fold.query` RPC clients.
+//
+// The napi binding throws plain Error with the stable `agg:`
+// prefix (`agg:<kind>: <detail>`); `classifyAggregatorError`
+// re-throws as a typed `RegistryClientError` /
+// `FoldQueryClientError`. Prefix locked against
+// `ERR_AGG_PREFIX` in `bindings/node/src/aggregator.rs`;
+// `tests/error_kind_mirror.rs` is the cross-language pin.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.FoldQueryClientError = exports.RegistryClientError = void 0;
+exports.parseAggregatorError = parseAggregatorError;
+exports.classifyAggregatorError = classifyAggregatorError;
+const ERR_AGG_PREFIX = 'agg:';
+class RegistryClientError extends Error {
+    kind;
+    serverDetail;
+    constructor(kind, detail) {
+        super(`${kind}: ${detail}`);
+        this.name = 'RegistryClientError';
+        this.kind = kind;
+        this.serverDetail = detail;
+        Object.setPrototypeOf(this, RegistryClientError.prototype);
+    }
+}
+exports.RegistryClientError = RegistryClientError;
+class FoldQueryClientError extends Error {
+    kind;
+    serverDetail;
+    constructor(kind, detail) {
+        super(`${kind}: ${detail}`);
+        this.name = 'FoldQueryClientError';
+        this.kind = kind;
+        this.serverDetail = detail;
+        Object.setPrototypeOf(this, FoldQueryClientError.prototype);
+    }
+}
+exports.FoldQueryClientError = FoldQueryClientError;
+const REGISTRY_KINDS = new Set([
+    'transport',
+    'codec',
+    'unknown-template',
+    'duplicate-group-name',
+    'spawn-rejected',
+    'spawn-not-supported',
+    'invalid-args',
+]);
+const FOLD_KINDS = new Set([
+    'transport',
+    'codec',
+    'unknown-kind',
+    'invalid-args',
+]);
+/**
+ * Inspect an error message for the `agg:` prefix and return the
+ * structured `{kind, detail}` if it matches. Returns `null` when
+ * the message is missing the prefix or is malformed.
+ */
+function parseAggregatorError(e) {
+    const msg = extractMessage(e);
+    if (!msg.startsWith(ERR_AGG_PREFIX))
+        return null;
+    const after = msg.slice(ERR_AGG_PREFIX.length);
+    // Find the FIRST `: ` separator — kinds are stable kebab-case
+    // identifiers with no colons; the detail may contain colons.
+    const sepIdx = after.indexOf(': ');
+    if (sepIdx === -1) {
+        // No detail, just the kind (defensive — substrate always emits
+        // a detail string today).
+        return { kind: after, detail: '' };
+    }
+    return {
+        kind: after.slice(0, sepIdx),
+        detail: after.slice(sepIdx + 2),
+    };
+}
+/**
+ * Re-throw a typed error for the given raw error if it carries the
+ * `agg:` prefix. Non-matching errors pass through unchanged so
+ * `throw classifyAggregatorError(e)` is safe at any catch site.
+ *
+ * Routes to `RegistryClientError` for registry-shaped kinds and
+ * `FoldQueryClientError` for fold-query-shaped kinds. Both surfaces
+ * share `transport` / `codec` / `invalid-args`; we route by the
+ * caller's typing — pass an explicit `surface` if you know which
+ * client raised it, otherwise the default routing biases to
+ * `RegistryClientError` for shared kinds (the substrate's primary
+ * surface).
+ */
+function classifyAggregatorError(e, surface) {
+    const parsed = parseAggregatorError(e);
+    if (!parsed)
+        return e;
+    // Surface-specific kinds take priority — they are unambiguous.
+    if (parsed.kind === 'unknown-kind') {
+        return new FoldQueryClientError('unknown-kind', parsed.detail);
+    }
+    if (parsed.kind === 'unknown-template' ||
+        parsed.kind === 'duplicate-group-name' ||
+        parsed.kind === 'spawn-rejected' ||
+        parsed.kind === 'spawn-not-supported') {
+        return new RegistryClientError(parsed.kind, parsed.detail);
+    }
+    // Shared kinds — route by caller hint, default to registry.
+    if (parsed.kind === 'transport' ||
+        parsed.kind === 'codec' ||
+        parsed.kind === 'invalid-args') {
+        if (surface === 'fold-query') {
+            return new FoldQueryClientError(parsed.kind, parsed.detail);
+        }
+        return new RegistryClientError(parsed.kind, parsed.detail);
+    }
+    // Unknown kind under the `agg:` umbrella — keep the original
+    // error so callers see the full string instead of a synthetic
+    // typed wrapper that drops information.
+    void REGISTRY_KINDS;
+    void FOLD_KINDS;
+    return e;
+}
+function extractMessage(e) {
+    if (e === null || e === undefined)
+        return '';
+    if (typeof e === 'string')
+        return e;
+    if (typeof e !== 'object')
+        return '';
+    const msg = e.message;
+    return typeof msg === 'string' ? msg : '';
+}

package/meshdb.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Result of {@link parseMeshDbErrorKind}: extracted structured
+ * discriminator + the human-readable message stripped of the
+ * `<<meshdb-kind:...>>` prefix.
+ */
+export interface ParsedMeshDbError {
+    kind: string;
+    message: string;
+}
+/**
+ * Pull the structured error kind out of a MeshDB error message.
+ *
+ * The Rust binding embeds the kind discriminator (one of the
+ * `MeshError` variant tags such as `planner_error`,
+ * `executor_error`, `query_cancelled`, `historical_range_unavailable`,
+ * `ambiguous_discovery`, etc.) at the start of the error message
+ * as `<<meshdb-kind:KIND>>MSG`. This helper parses it back.
+ *
+ * Returns `null` for errors that don't carry a kind prefix
+ * (SDK-side validation failures, factory rejections) — those
+ * surface with the plain message intact.
+ */
+export declare function parseMeshDbErrorKind(err: unknown): ParsedMeshDbError | null;

package/meshdb.js

@@ -0,0 +1,101 @@
+"use strict";
+// MeshDB AsyncIterable shim.
+//
+// Augments the napi-rs–generated `MeshQueryStream` class with
+// `[Symbol.asyncIterator]` so callers can write `for await (const row
+// of await runner.execute(query)) { ... }`. The locked Node SDK
+// decision is `Promise<AsyncIterable<Row>>`; importing this module
+// once at startup makes the shape land.
+//
+// Usage:
+//
+//   import "@net-mesh/core/meshdb";  // augments MeshQueryStream
+//   import { MeshQuery, MeshQueryRunner } from "@net-mesh/core";
+//
+//   const runner = new MeshQueryRunner(reader);
+//   const stream = await runner.execute(MeshQuery.latest(0xABn));
+//   for await (const row of stream) {
+//     console.log(row.seq, row.payload);
+//   }
+//
+// The shim is idempotent — re-imports are no-ops. It detaches
+// cleanly under tree-shaking too (no top-level side effects beyond
+// the prototype attach, which only fires when `MeshQueryStream` is
+// part of the loaded native binding).
+//
+// Phase-F note: this shim is a wire-shape ergonomics layer; it
+// doesn't change semantics. The underlying `next()` / `toArray()`
+// methods stay available for callers that prefer manual iteration
+// or batch drain.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.parseMeshDbErrorKind = parseMeshDbErrorKind;
+// The napi-generated MeshQueryStream is a constructor function with a
+// prototype, but the original cast typed it as a plain object — the
+// later `typeof === "function"` narrowing then collapsed it to `never`
+// and reading `.prototype` errored under `-D warnings`. Cast as a
+// Function with a prototype so both type-guards line up.
+const native = require("./index");
+if (native.MeshQueryStream &&
+    typeof native.MeshQueryStream === "function" &&
+    !(Symbol.asyncIterator in native.MeshQueryStream.prototype)) {
+    Object.defineProperty(native.MeshQueryStream.prototype, Symbol.asyncIterator, {
+        value() {
+            const stream = this;
+            return {
+                async next() {
+                    const row = await stream.next();
+                    if (row === null || row === undefined) {
+                        return { value: undefined, done: true };
+                    }
+                    return { value: row, done: false };
+                },
+                // `return(value)` is invoked when a `for await (...)` loop
+                // `break`s, `return`s from the enclosing function, or an
+                // exception unwinds out of the loop body. Without this,
+                // the backing row Vec stays pinned on the AsyncMutex
+                // until JS GC eventually drops the stream — for a 10k+
+                // row result that's a sizeable memory pin.
+                async return(value) {
+                    if (typeof stream.release === "function") {
+                        await stream.release();
+                    }
+                    return { value, done: true };
+                },
+                // `throw(err)` is the iteration-protocol's error path.
+                // Symmetric to `return()`: free the buffer, then
+                // re-surface the error to the caller.
+                async throw(err) {
+                    if (typeof stream.release === "function") {
+                        await stream.release();
+                    }
+                    throw err;
+                },
+            };
+        },
+        enumerable: false,
+        configurable: true,
+        writable: true,
+    });
+}
+/**
+ * Pull the structured error kind out of a MeshDB error message.
+ *
+ * The Rust binding embeds the kind discriminator (one of the
+ * `MeshError` variant tags such as `planner_error`,
+ * `executor_error`, `query_cancelled`, `historical_range_unavailable`,
+ * `ambiguous_discovery`, etc.) at the start of the error message
+ * as `<<meshdb-kind:KIND>>MSG`. This helper parses it back.
+ *
+ * Returns `null` for errors that don't carry a kind prefix
+ * (SDK-side validation failures, factory rejections) — those
+ * surface with the plain message intact.
+ */
+function parseMeshDbErrorKind(err) {
+    if (!(err instanceof Error))
+        return null;
+    // Accept digits too (`protocol_v2_mismatch`-style future kinds).
+    const m = err.message.match(/^<<meshdb-kind:([a-z0-9_]+)>>(.*)$/s);
+    if (!m)
+        return null;
+    return { kind: m[1], message: m[2] };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@net-mesh/core",
-  "version": "0.21.0",
+  "version": "0.22.0",
   "description": "High-performance, schema-agnostic event bus for AI runtime workloads",
   "main": "index.js",
   "types": "index.d.ts",
@@ -20,6 +20,10 @@
     "./meshdb": {
       "types": "./meshdb.d.ts",
       "default": "./meshdb.js"
+    },
+    "./aggregator": {
+      "types": "./aggregator.d.ts",
+      "default": "./aggregator.js"
     }
   },
   "napi": {
@@ -56,6 +60,10 @@
     "errors.d.ts",
     "mesh_rpc.js",
     "mesh_rpc.d.ts",
+    "meshdb.js",
+    "meshdb.d.ts",
+    "aggregator.js",
+    "aggregator.d.ts",
     "*.node"
   ],
   "devDependencies": {
@@ -66,9 +74,9 @@
   },
   "scripts": {
     "artifacts": "napi artifacts",
-    "build": "napi build --platform --release --features redis,net,cortex,compute,groups,meshos,deck,meshdb",
-    "build:debug": "napi build --platform --features redis,net,cortex,compute,groups,meshos,deck,meshdb",
-    "build:test": "napi build --platform --features redis,net,cortex,compute,groups,meshos,deck,meshdb,test-helpers",
+    "build": "napi build --platform --release --features redis,net,cortex,compute,groups,meshos,deck,meshdb,aggregator",
+    "build:debug": "napi build --platform --features redis,net,cortex,compute,groups,meshos,deck,meshdb,aggregator",
+    "build:test": "napi build --platform --features redis,net,cortex,compute,groups,meshos,deck,meshdb,aggregator,test-helpers",
     "build:ts": "tsc -p tsconfig.build.json",
     "prepublishOnly": "npm run build:ts && napi prepublish -t npm",
     "test": "vitest run",
@@ -83,13 +91,13 @@
     "node": ">=20"
   },
   "optionalDependencies": {
-    "@net-mesh/core-win32-x64-msvc": "0.21.0",
-    "@net-mesh/core-win32-arm64-msvc": "0.21.0",
-    "@net-mesh/core-darwin-x64": "0.21.0",
-    "@net-mesh/core-darwin-arm64": "0.21.0",
-    "@net-mesh/core-linux-x64-gnu": "0.21.0",
-    "@net-mesh/core-linux-x64-musl": "0.21.0",
-    "@net-mesh/core-linux-arm64-gnu": "0.21.0",
-    "@net-mesh/core-linux-arm64-musl": "0.21.0"
+    "@net-mesh/core-win32-x64-msvc": "0.22.0",
+    "@net-mesh/core-win32-arm64-msvc": "0.22.0",
+    "@net-mesh/core-darwin-x64": "0.22.0",
+    "@net-mesh/core-darwin-arm64": "0.22.0",
+    "@net-mesh/core-linux-x64-gnu": "0.22.0",
+    "@net-mesh/core-linux-x64-musl": "0.22.0",
+    "@net-mesh/core-linux-arm64-gnu": "0.22.0",
+    "@net-mesh/core-linux-arm64-musl": "0.22.0"
   }
 }