@net-mesh/sdk 0.20.2 → 0.22.0

package/dist/capability-aggregation.d.ts

@@ -0,0 +1,129 @@
+/**
+ * Capability aggregation surface — Phase 6c of
+ * `MULTIFOLD_PHASE_6C_CAPACITY_AGGREGATION.md`.
+ *
+ * Three composable primitives map onto the Rust core's
+ * `Fold::aggregate` and `Fold::capacity_ranking`:
+ *
+ *  - {@link TagMatcher} — picks which entries the aggregation
+ *    walks. Tagged-union: `kind: 'exact' | 'prefix' | 'axis' |
+ *    'axisKey' | 'regex' | 'versionRange'`.
+ *  - {@link GroupBy} — buckets matching entries.
+ *  - {@link Aggregation} — reduces each bucket to a number.
+ *
+ * {@link CapacityQuery} composes a matcher + groupBy + optional RTT
+ * filter + optional summed-capacity axis into a single
+ * `capacityRanking(...)` call; the materialized view returns
+ * per-bucket state breakdown sorted by available capacity.
+ *
+ * The Rust core takes JSON-encoded tagged unions over the napi
+ * boundary; these helpers handle the conversion so TS callers work
+ * with idiomatic discriminated unions.
+ */
+import type { TaxonomyAxis } from './capability-enhancements';
+export type { TaxonomyAxis };
+/**
+ * Pre-grouping filter. An entry is included if any of its tags
+ * matches the matcher.
+ */
+export type TagMatcher = {
+    kind: 'exact';
+    value: string;
+} | {
+    kind: 'prefix';
+    value: string;
+} | {
+    kind: 'axis';
+    axis: TaxonomyAxis;
+} | {
+    kind: 'axisKey';
+    axis: TaxonomyAxis;
+    key: string;
+} | {
+    kind: 'regex';
+    pattern: string;
+} | {
+    kind: 'versionRange';
+    axisKey: string;
+    min?: string;
+    max?: string;
+};
+/** Bucket-key derivation. */
+export type GroupBy = {
+    kind: 'class';
+} | {
+    kind: 'state';
+} | {
+    kind: 'region';
+} | {
+    kind: 'publisher';
+} | {
+    kind: 'tagStem';
+    prefix: string;
+} | {
+    kind: 'tagValue';
+    axis: TaxonomyAxis;
+    key: string;
+};
+/** Per-bucket reduction. */
+export type Aggregation = {
+    kind: 'count';
+} | {
+    kind: 'distinctPublishers';
+} | {
+    kind: 'distinctValues';
+    axis: TaxonomyAxis;
+    key: string;
+} | {
+    kind: 'sumNumericTag';
+    axisKey: string;
+} | {
+    kind: 'minNumericTag';
+    axisKey: string;
+} | {
+    kind: 'maxNumericTag';
+    axisKey: string;
+};
+/** Composed capacity-ranking query. */
+export interface CapacityQuery {
+    /** Optional pre-filter. */
+    matcher?: TagMatcher;
+    /** How to bucket matching entries. */
+    groupBy: GroupBy;
+    /**
+     * Drop entries whose publisher's RTT exceeds this. `undefined`
+     * disables the RTT filter (the `rttEntries` argument to
+     * {@link MeshNode.capabilityCapacityRanking} is unused regardless).
+     */
+    maxRttMs?: number;
+    /**
+     * Canonical `<axis>.<key>` of a numeric tag to sum across each
+     * bucket (e.g. `"hardware.gpu.count"`).
+     */
+    sumAxisKey?: string;
+    /** Top-N buckets by `available` descending. `0` = no truncation. */
+    limit: number;
+}
+/** One row of an aggregate result. */
+export interface AggregateRow {
+    bucket: string;
+    value: bigint;
+}
+/** One row of a capacity-ranking result. */
+export interface CapacityRow {
+    /** Bucket key. */
+    bucket: string;
+    /** Entries in `Idle` that pass the matcher + RTT gates. */
+    idle: bigint;
+    /** Entries in `Busy` that pass. */
+    busy: bigint;
+    /** Entries in `Reserved` that pass. */
+    reserved: bigint;
+    /** `idle + busy + reserved`. Faulty entries are always excluded. */
+    available: bigint;
+    /**
+     * Sum of the `sumAxisKey` numeric tag across the bucket;
+     * `undefined` when no `sumAxisKey` was requested.
+     */
+    summedCapacity?: bigint;
+}

package/dist/capability-aggregation.js

@@ -0,0 +1,124 @@
+"use strict";
+/**
+ * Capability aggregation surface — Phase 6c of
+ * `MULTIFOLD_PHASE_6C_CAPACITY_AGGREGATION.md`.
+ *
+ * Three composable primitives map onto the Rust core's
+ * `Fold::aggregate` and `Fold::capacity_ranking`:
+ *
+ *  - {@link TagMatcher} — picks which entries the aggregation
+ *    walks. Tagged-union: `kind: 'exact' | 'prefix' | 'axis' |
+ *    'axisKey' | 'regex' | 'versionRange'`.
+ *  - {@link GroupBy} — buckets matching entries.
+ *  - {@link Aggregation} — reduces each bucket to a number.
+ *
+ * {@link CapacityQuery} composes a matcher + groupBy + optional RTT
+ * filter + optional summed-capacity axis into a single
+ * `capacityRanking(...)` call; the materialized view returns
+ * per-bucket state breakdown sorted by available capacity.
+ *
+ * The Rust core takes JSON-encoded tagged unions over the napi
+ * boundary; these helpers handle the conversion so TS callers work
+ * with idiomatic discriminated unions.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.tagMatcherToJson = tagMatcherToJson;
+exports.groupByToJson = groupByToJson;
+exports.aggregationToJson = aggregationToJson;
+exports.capacityQueryToJson = capacityQueryToJson;
+// =====================================================
+// JSON encoding for the napi boundary
+// =====================================================
+//
+// The Rust core's serde uses snake_case kind values + snake_case
+// field names. The TS surface above uses camelCase per ergonomics;
+// these helpers translate.
+/** @internal */
+function tagMatcherToJson(matcher) {
+    switch (matcher.kind) {
+        case 'exact':
+            return JSON.stringify({ kind: 'exact', value: matcher.value });
+        case 'prefix':
+            return JSON.stringify({ kind: 'prefix', value: matcher.value });
+        case 'axis':
+            return JSON.stringify({ kind: 'axis', axis: matcher.axis });
+        case 'axisKey':
+            return JSON.stringify({
+                kind: 'axis_key',
+                axis: matcher.axis,
+                key: matcher.key,
+            });
+        case 'regex':
+            return JSON.stringify({ kind: 'regex', pattern: matcher.pattern });
+        case 'versionRange':
+            return JSON.stringify({
+                kind: 'version_range',
+                axis_key: matcher.axisKey,
+                min: matcher.min ?? null,
+                max: matcher.max ?? null,
+            });
+    }
+}
+/** @internal */
+function groupByToJson(groupBy) {
+    switch (groupBy.kind) {
+        case 'class':
+            return JSON.stringify({ kind: 'class' });
+        case 'state':
+            return JSON.stringify({ kind: 'state' });
+        case 'region':
+            return JSON.stringify({ kind: 'region' });
+        case 'publisher':
+            return JSON.stringify({ kind: 'publisher' });
+        case 'tagStem':
+            return JSON.stringify({ kind: 'tag_stem', prefix: groupBy.prefix });
+        case 'tagValue':
+            return JSON.stringify({
+                kind: 'tag_value',
+                axis: groupBy.axis,
+                key: groupBy.key,
+            });
+    }
+}
+/** @internal */
+function aggregationToJson(agg) {
+    switch (agg.kind) {
+        case 'count':
+            return JSON.stringify({ kind: 'count' });
+        case 'distinctPublishers':
+            return JSON.stringify({ kind: 'distinct_publishers' });
+        case 'distinctValues':
+            return JSON.stringify({
+                kind: 'distinct_values',
+                axis: agg.axis,
+                key: agg.key,
+            });
+        case 'sumNumericTag':
+            return JSON.stringify({
+                kind: 'sum_numeric_tag',
+                axis_key: agg.axisKey,
+            });
+        case 'minNumericTag':
+            return JSON.stringify({
+                kind: 'min_numeric_tag',
+                axis_key: agg.axisKey,
+            });
+        case 'maxNumericTag':
+            return JSON.stringify({
+                kind: 'max_numeric_tag',
+                axis_key: agg.axisKey,
+            });
+    }
+}
+/** @internal */
+function capacityQueryToJson(query) {
+    return JSON.stringify({
+        matcher: query.matcher
+            ? JSON.parse(tagMatcherToJson(query.matcher))
+            : null,
+        group_by: JSON.parse(groupByToJson(query.groupBy)),
+        max_rtt_ms: query.maxRttMs ?? null,
+        sum_axis_key: query.sumAxisKey ?? null,
+        limit: query.limit,
+    });
+}

package/dist/index.d.ts

@@ -43,6 +43,7 @@ export type { AxisEntry, AxisSchema, KeyEntry, KeyShape, KeyShapeKind, SchemaErr
 export { AXIS_SCHEMA, METADATA_RESERVED_KEYS, METADATA_RESERVED_PREFIXES, METADATA_SOFT_CAP_BYTES, isReportClean, isReportValid, validateCapabilities, } from './capability-schema';
 export { subnetId, GLOBAL_SUBNET } from './subnets';
 export type { SubnetId, SubnetRule, SubnetPolicy } from './subnets';
+export type { Aggregation, AggregateRow, CapacityQuery, CapacityRow, GroupBy, TagMatcher, } from './capability-aggregation';
 export { DaemonRuntime, DaemonHandle, DaemonError, MigrationHandle, MigrationError, } from './compute';
 export type { CausalEvent, MeshDaemon, DaemonFactory, DaemonHostConfig, DaemonStats, MigrationPhase, MigrationOptions, MigrationErrorKind, } from './compute';
 export { DisposableMeshQueryRunner, InMemoryChainReader, MeshQuery, MeshQueryRunner, MeshQueryStream, QueryBuilder, parseMeshDbErrorKind, } from './meshdb';

package/dist/mesh.d.ts

@@ -36,6 +36,7 @@
  * ```
  */
 import { type CapabilityFilter, type CapabilitySet, type ScopeFilter } from './capabilities';
+import { type Aggregation, type AggregateRow, type CapacityQuery, type CapacityRow, type GroupBy, type TagMatcher } from './capability-aggregation';
 import type { SubnetId, SubnetPolicy } from './subnets';
 import type { Token } from './identity';
 /** Reliability mode chosen at stream-open time. */
@@ -299,6 +300,64 @@ export declare class MeshNode {
      * ```
      */
     findNodesScoped(filter: CapabilityFilter, scope: ScopeFilter): bigint[];
+    /**
+     * Bucketed aggregation over the local capability fold —
+     * `Fold::aggregate(matcher, groupBy, agg)`. Composes a matcher,
+     * a bucket-derivation, and a per-bucket reduction into a
+     * lex-sorted `[bucket, value][]`. Phase 6c-A of
+     * `MULTIFOLD_PHASE_6C_CAPACITY_AGGREGATION.md`.
+     *
+     * `matcher === undefined` walks every entry.
+     *
+     * @example
+     * ```typescript
+     * // Top GPU types by count.
+     * const rows = node.capabilityAggregate(
+     *   { kind: 'prefix', value: 'hardware.gpu' },
+     *   { kind: 'tagStem', prefix: 'hardware.gpu' },
+     *   { kind: 'count' },
+     * );
+     * for (const r of rows) console.log(r.bucket, r.value);
+     * ```
+     */
+    capabilityAggregate(matcher: TagMatcher | undefined, groupBy: GroupBy, aggregation: Aggregation): AggregateRow[];
+    /**
+     * Capacity-ranked materialized view —
+     * `Fold::capacity_ranking(query, rttLookup)`. Per-bucket state
+     * breakdown + latency gate + optional summed numeric capacity,
+     * sorted by `available` desc (ties broken on bucket asc) and
+     * truncated to `query.limit`. Phase 6c-B.
+     *
+     * `rttEntries` is the materialized RTT map. `undefined`/empty
+     * disables the RTT filter regardless of `query.maxRttMs`. Per
+     * the plan, a `ThreadsafeFunction` closure variant is a follow-
+     * up; the map shape matches the Go / C wrappers and lines up
+     * with what operators typically have cached from the proximity
+     * graph.
+     *
+     * @example
+     * ```typescript
+     * // Top 5 GPU types available within 50 ms latency.
+     * const rttMap = [
+     *   { nodeId: 0x1234n, rttMs: 25 },
+     *   { nodeId: 0x5678n, rttMs: 75 },
+     * ];
+     * const rows = node.capabilityCapacityRanking(
+     *   {
+     *     matcher: { kind: 'prefix', value: 'hardware.gpu' },
+     *     groupBy: { kind: 'tagStem', prefix: 'hardware.gpu' },
+     *     maxRttMs: 50,
+     *     sumAxisKey: 'hardware.gpu.count',
+     *     limit: 5,
+     *   },
+     *   rttMap,
+     * );
+     * ```
+     */
+    capabilityCapacityRanking(query: CapacityQuery, rttEntries?: Array<{
+        nodeId: bigint;
+        rttMs: number;
+    }>): CapacityRow[];
     /** Shutdown the mesh node. */
     shutdown(): Promise<void>;
 }

package/dist/mesh.js

@@ -41,6 +41,7 @@ exports.ChannelAuthError = exports.ChannelError = exports.MeshNode = exports.Not
 const core_1 = require("@net-mesh/core");
 const _internal_js_1 = require("./_internal.js");
 const capabilities_1 = require("./capabilities");
+const capability_aggregation_1 = require("./capability-aggregation");
 /**
  * Thrown by {@link MeshNode.sendOnStream} / `sendWithRetry` /
  * `sendBlocking` when the stream's per-stream in-flight window is
@@ -122,6 +123,21 @@ class MeshNode {
         }
         native.testInjectSyntheticPeer(nodeId);
     }
+    /**
+     * Test-only — same shape as {@link _testInjectSyntheticPeer} but
+     * stages the synthetic peer with the supplied canonical tag
+     * strings. Used by the Phase 6c aggregation smoke tests to set
+     * up multi-bucket fixtures without spinning up multiple meshes.
+     *
+     * @internal
+     */
+    _testInjectSyntheticPeerWithTags(nodeId, tags) {
+        const native = this.native;
+        if (typeof native.testInjectSyntheticPeerWithTags !== 'function') {
+            throw new Error('testInjectSyntheticPeerWithTags: NAPI build missing `test-helpers` feature');
+        }
+        native.testInjectSyntheticPeerWithTags(nodeId, tags);
+    }
     /** Create and configure a new mesh node. */
     static async create(config) {
         const native = await core_1.NetMesh.create({
@@ -389,6 +405,69 @@ class MeshNode {
     findNodesScoped(filter, scope) {
         return this.native.findNodesScoped((0, capabilities_1.capabilityFilterToNapi)(filter), (0, capabilities_1.scopeFilterToNapi)(scope));
     }
+    /**
+     * Bucketed aggregation over the local capability fold —
+     * `Fold::aggregate(matcher, groupBy, agg)`. Composes a matcher,
+     * a bucket-derivation, and a per-bucket reduction into a
+     * lex-sorted `[bucket, value][]`. Phase 6c-A of
+     * `MULTIFOLD_PHASE_6C_CAPACITY_AGGREGATION.md`.
+     *
+     * `matcher === undefined` walks every entry.
+     *
+     * @example
+     * ```typescript
+     * // Top GPU types by count.
+     * const rows = node.capabilityAggregate(
+     *   { kind: 'prefix', value: 'hardware.gpu' },
+     *   { kind: 'tagStem', prefix: 'hardware.gpu' },
+     *   { kind: 'count' },
+     * );
+     * for (const r of rows) console.log(r.bucket, r.value);
+     * ```
+     */
+    capabilityAggregate(matcher, groupBy, aggregation) {
+        const matcherJson = matcher ? (0, capability_aggregation_1.tagMatcherToJson)(matcher) : null;
+        const groupByJson = (0, capability_aggregation_1.groupByToJson)(groupBy);
+        const aggregationJson = (0, capability_aggregation_1.aggregationToJson)(aggregation);
+        return this.native.capabilityAggregate(matcherJson, groupByJson, aggregationJson);
+    }
+    /**
+     * Capacity-ranked materialized view —
+     * `Fold::capacity_ranking(query, rttLookup)`. Per-bucket state
+     * breakdown + latency gate + optional summed numeric capacity,
+     * sorted by `available` desc (ties broken on bucket asc) and
+     * truncated to `query.limit`. Phase 6c-B.
+     *
+     * `rttEntries` is the materialized RTT map. `undefined`/empty
+     * disables the RTT filter regardless of `query.maxRttMs`. Per
+     * the plan, a `ThreadsafeFunction` closure variant is a follow-
+     * up; the map shape matches the Go / C wrappers and lines up
+     * with what operators typically have cached from the proximity
+     * graph.
+     *
+     * @example
+     * ```typescript
+     * // Top 5 GPU types available within 50 ms latency.
+     * const rttMap = [
+     *   { nodeId: 0x1234n, rttMs: 25 },
+     *   { nodeId: 0x5678n, rttMs: 75 },
+     * ];
+     * const rows = node.capabilityCapacityRanking(
+     *   {
+     *     matcher: { kind: 'prefix', value: 'hardware.gpu' },
+     *     groupBy: { kind: 'tagStem', prefix: 'hardware.gpu' },
+     *     maxRttMs: 50,
+     *     sumAxisKey: 'hardware.gpu.count',
+     *     limit: 5,
+     *   },
+     *   rttMap,
+     * );
+     * ```
+     */
+    capabilityCapacityRanking(query, rttEntries) {
+        const queryJson = (0, capability_aggregation_1.capacityQueryToJson)(query);
+        return this.native.capabilityCapacityRanking(queryJson, rttEntries ?? null);
+    }
     /** Shutdown the mesh node. */
     async shutdown() {
         await this.native.shutdown();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@net-mesh/sdk",
-  "version": "0.20.2",
+  "version": "0.22.0",
   "description": "Ergonomic TypeScript SDK for the Net mesh network",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -29,7 +29,7 @@
     "test:watch": "vitest"
   },
   "peerDependencies": {
-    "@net-mesh/core": ">=0.20.2"
+    "@net-mesh/core": ">=0.22.0"
   },
   "devDependencies": {
     "@net-mesh/core": "file:../bindings/node",