@net-mesh/sdk 0.19.0

package/dist/_internal.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Module-internal handles used by sibling SDK modules to share
+ * the underlying NAPI objects without exposing them on the
+ * public class surface.
+ *
+ * Previously this was a leading-underscore method (`_napiRuntime`,
+ * `_napiNetMesh`) on each wrapper class. That left a runtime-
+ * discoverable escape hatch: a consumer casting the class instance
+ * to `any` could call the method and reach the unstable NAPI
+ * surface, bypassing the wrapper's typed error / lifecycle
+ * boundaries. `stripInternal: true` hid the method from emitted
+ * `.d.ts` but the method still existed on every instance.
+ *
+ * This file swaps that for a WeakMap-per-handle so the napi
+ * pointer is keyed off the wrapper instance but is NOT a property
+ * of it. Only code that imports these helpers directly can reach
+ * the native pointer; the helpers are `@internal` and never
+ * re-exported from `index.ts`, so a consumer would have to deep-
+ * import this file deliberately — the usual "you're breaking the
+ * seal" ergonomics.
+ *
+ * @internal
+ * @packageDocumentation
+ */
+export {};

package/dist/_internal.js

@@ -0,0 +1,60 @@
+"use strict";
+/**
+ * Module-internal handles used by sibling SDK modules to share
+ * the underlying NAPI objects without exposing them on the
+ * public class surface.
+ *
+ * Previously this was a leading-underscore method (`_napiRuntime`,
+ * `_napiNetMesh`) on each wrapper class. That left a runtime-
+ * discoverable escape hatch: a consumer casting the class instance
+ * to `any` could call the method and reach the unstable NAPI
+ * surface, bypassing the wrapper's typed error / lifecycle
+ * boundaries. `stripInternal: true` hid the method from emitted
+ * `.d.ts` but the method still existed on every instance.
+ *
+ * This file swaps that for a WeakMap-per-handle so the napi
+ * pointer is keyed off the wrapper instance but is NOT a property
+ * of it. Only code that imports these helpers directly can reach
+ * the native pointer; the helpers are `@internal` and never
+ * re-exported from `index.ts`, so a consumer would have to deep-
+ * import this file deliberately — the usual "you're breaking the
+ * seal" ergonomics.
+ *
+ * @internal
+ * @packageDocumentation
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.setNapiRuntime = setNapiRuntime;
+exports.getNapiRuntime = getNapiRuntime;
+exports.setNapiMesh = setNapiMesh;
+exports.getNapiMesh = getNapiMesh;
+// `WeakMap<object, …>` avoids pinning the wrapper in memory — when
+// a DaemonRuntime is garbage-collected the entry evicts automatically.
+const napiRuntimes = new WeakMap();
+const napiMeshes = new WeakMap();
+/** @internal */
+function setNapiRuntime(host, napi) {
+    napiRuntimes.set(host, napi);
+}
+/** @internal */
+function getNapiRuntime(host) {
+    const r = napiRuntimes.get(host);
+    if (!r) {
+        throw new Error('internal: no NAPI runtime registered for this DaemonRuntime — ' +
+            'constructor may not have run');
+    }
+    return r;
+}
+/** @internal */
+function setNapiMesh(host, napi) {
+    napiMeshes.set(host, napi);
+}
+/** @internal */
+function getNapiMesh(host) {
+    const r = napiMeshes.get(host);
+    if (!r) {
+        throw new Error('internal: no NAPI mesh registered for this MeshNode — ' +
+            'constructor may not have run');
+    }
+    return r;
+}

package/dist/capabilities.d.ts

@@ -0,0 +1,271 @@
+/**
+ * Capability declarations — hardware / software / models / tools /
+ * tags / resource limits — and the filters that query them.
+ *
+ * Construct a {@link CapabilitySet} from whatever your node actually
+ * runs, hand it to {@link MeshNode.announceCapabilities}, and the
+ * mesh pushes it to every directly-connected peer. Peers keep the
+ * latest announcement from each node in their local capability
+ * index; {@link MeshNode.findNodes} queries that index.
+ *
+ * @example
+ * ```ts
+ * import { MeshNode } from '@net-mesh/sdk';
+ *
+ * await node.announceCapabilities({
+ *   hardware: {
+ *     cpuCores: 16,
+ *     memoryGb: 64,
+ *     gpu: { vendor: 'nvidia', model: 'RTX 4090', vramGb: 24 },
+ *   },
+ *   tags: ['gpu', 'inference'],
+ *   models: [{ modelId: 'llama-3.1-70b', family: 'llama' }],
+ * });
+ *
+ * const peers = node.findNodes({ requireTags: ['gpu'], minVramMb: 16_384 });
+ * ```
+ *
+ * Multi-hop propagation is deferred; today peers more than one hop
+ * away are not visible.
+ */
+/**
+ * GPU vendor. Case-insensitive on input (`'NVIDIA'`, `'nvidia'`,
+ * `'Nvidia'` all normalize to `'nvidia'`). Unknown / misspelled
+ * vendors collapse to `'unknown'`.
+ */
+export type GpuVendor = 'nvidia' | 'amd' | 'intel' | 'apple' | 'qualcomm' | 'unknown';
+export interface GpuInfo {
+    vendor?: GpuVendor;
+    model: string;
+    vramGb: number;
+    computeUnits?: number;
+    tensorCores?: number;
+    /** FP16 TFLOPS × 10 (integer) — e.g. 825 for 82.5 TFLOPS. */
+    fp16TflopsX10?: number;
+}
+export type AcceleratorKind = 'tpu' | 'npu' | 'fpga' | 'asic' | 'dsp' | 'unknown';
+export interface Accelerator {
+    kind: AcceleratorKind;
+    model: string;
+    memoryGb?: number;
+    /** TOPS × 10 (integer). */
+    topsX10?: number;
+}
+export interface Hardware {
+    cpuCores?: number;
+    cpuThreads?: number;
+    memoryGb?: number;
+    gpu?: GpuInfo;
+    additionalGpus?: GpuInfo[];
+    /** Storage in GB. BigInt to carry multi-TB values without loss. */
+    storageGb?: bigint;
+    networkGbps?: number;
+    accelerators?: Accelerator[];
+}
+/** `[runtime_name, version]` pair used by runtimes/frameworks/drivers. */
+export type SoftwarePair = [string, string];
+export interface Software {
+    os?: string;
+    osVersion?: string;
+    runtimes?: SoftwarePair[];
+    frameworks?: SoftwarePair[];
+    cudaVersion?: string;
+    drivers?: SoftwarePair[];
+}
+export type Modality = 'text' | 'image' | 'audio' | 'video' | 'code' | 'embedding' | 'tool-use';
+export interface ModelCapability {
+    modelId: string;
+    family?: string;
+    /**
+     * Parameter count, billions × 10 (70 B ⇒ 700). Integer-encoded to
+     * avoid float precision loss; the core uses the same layout.
+     */
+    parametersBX10?: number;
+    contextLength?: number;
+    quantization?: string;
+    modalities?: Modality[];
+    tokensPerSec?: number;
+    loaded?: boolean;
+}
+export interface ToolCapability {
+    toolId: string;
+    name?: string;
+    version?: string;
+    /** JSON-Schema string. */
+    inputSchema?: string;
+    /** JSON-Schema string. */
+    outputSchema?: string;
+    requires?: string[];
+    estimatedTimeMs?: number;
+    stateless?: boolean;
+}
+export interface CapabilityLimits {
+    maxConcurrentRequests?: number;
+    maxTokensPerRequest?: number;
+    rateLimitRpm?: number;
+    maxBatchSize?: number;
+    maxInputBytes?: number;
+    maxOutputBytes?: number;
+}
+export interface CapabilitySet {
+    hardware?: Hardware;
+    software?: Software;
+    models?: ModelCapability[];
+    tools?: ToolCapability[];
+    tags?: string[];
+    limits?: CapabilityLimits;
+}
+export interface CapabilityFilter {
+    requireTags?: string[];
+    requireModels?: string[];
+    requireTools?: string[];
+    minMemoryMb?: number;
+    requireGpu?: boolean;
+    gpuVendor?: GpuVendor;
+    minVramMb?: number;
+    minContextLength?: number;
+    requireModalities?: Modality[];
+}
+interface NapiGpuInfo {
+    vendor?: string;
+    model: string;
+    vramGb: number;
+    computeUnits?: number;
+    tensorCores?: number;
+    fp16TflopsX10?: number;
+}
+interface NapiAccelerator {
+    kind: string;
+    model: string;
+    memoryGb?: number;
+    topsX10?: number;
+}
+interface NapiHardware {
+    cpuCores?: number;
+    cpuThreads?: number;
+    memoryGb?: number;
+    gpu?: NapiGpuInfo;
+    additionalGpus?: NapiGpuInfo[];
+    storageGb?: bigint;
+    networkGbps?: number;
+    accelerators?: NapiAccelerator[];
+}
+interface NapiSoftware {
+    os?: string;
+    osVersion?: string;
+    runtimes?: string[][];
+    frameworks?: string[][];
+    cudaVersion?: string;
+    drivers?: string[][];
+}
+interface NapiModel {
+    modelId: string;
+    family?: string;
+    parametersBX10?: number;
+    contextLength?: number;
+    quantization?: string;
+    modalities?: string[];
+    tokensPerSec?: number;
+    loaded?: boolean;
+}
+interface NapiTool {
+    toolId: string;
+    name?: string;
+    version?: string;
+    inputSchema?: string;
+    outputSchema?: string;
+    requires?: string[];
+    estimatedTimeMs?: number;
+    stateless?: boolean;
+}
+interface NapiLimits {
+    maxConcurrentRequests?: number;
+    maxTokensPerRequest?: number;
+    rateLimitRpm?: number;
+    maxBatchSize?: number;
+    maxInputBytes?: number;
+    maxOutputBytes?: number;
+}
+/** Shape that napi-rs expects for `announceCapabilities`. */
+export interface NapiCapabilitySet {
+    hardware?: NapiHardware;
+    software?: NapiSoftware;
+    models?: NapiModel[];
+    tools?: NapiTool[];
+    tags?: string[];
+    limits?: NapiLimits;
+}
+/** Shape that napi-rs expects for `findNodes`. */
+export interface NapiCapabilityFilter {
+    requireTags?: string[];
+    requireModels?: string[];
+    requireTools?: string[];
+    minMemoryMb?: number;
+    requireGpu?: boolean;
+    gpuVendor?: string;
+    minVramMb?: number;
+    minContextLength?: number;
+    requireModalities?: string[];
+}
+export declare function capabilitySetToNapi(caps: CapabilitySet): NapiCapabilitySet;
+export declare function capabilityFilterToNapi(f: CapabilityFilter): NapiCapabilityFilter;
+/**
+ * Caller's intent for narrowing peer discovery by reserved
+ * `scope:*` tags. See {@link MeshNode.findNodesScoped}.
+ *
+ * Tag-based scope is a query-time concern — the wire format is
+ * untouched. Untagged peers resolve to `Global` and stay visible
+ * under most filters by design (matches the v1-permissive
+ * default). Peers tagged `scope:subnet-local` only show up under
+ * `sameSubnet`.
+ */
+export type ScopeFilter = {
+    kind: 'any';
+} | {
+    kind: 'globalOnly';
+} | {
+    kind: 'sameSubnet';
+} | {
+    kind: 'tenant';
+    tenant: string;
+} | {
+    kind: 'tenants';
+    tenants: string[];
+} | {
+    kind: 'region';
+    region: string;
+} | {
+    kind: 'regions';
+    regions: string[];
+};
+/** Shape that napi-rs expects for `findNodesScoped`. */
+export interface NapiScopeFilter {
+    kind: string;
+    tenant?: string;
+    tenants?: string[];
+    region?: string;
+    regions?: string[];
+}
+export declare function scopeFilterToNapi(s: ScopeFilter): NapiScopeFilter;
+/** Reserved tag prefix for tenant-scoped announcements. */
+export declare const SCOPE_TENANT_PREFIX = "scope:tenant:";
+/** Reserved tag prefix for region-scoped announcements. */
+export declare const SCOPE_REGION_PREFIX = "scope:region:";
+/** Reserved tag marking an announcement subnet-local. */
+export declare const SCOPE_SUBNET_LOCAL = "scope:subnet-local";
+/**
+ * Append a `scope:tenant:<id>` tag to a tag list. Idempotent —
+ * safe to call repeatedly with the same id. Empty `tenantId` is a
+ * no-op.
+ */
+export declare function withTenantScope(tags: string[] | undefined, tenantId: string): string[];
+/** Append a `scope:region:<name>` tag to a tag list. Idempotent. */
+export declare function withRegionScope(tags: string[] | undefined, region: string): string[];
+/**
+ * Append the `scope:subnet-local` tag to a tag list. Idempotent.
+ * Strictest form wins on the resolver — when this tag is present,
+ * tenant/region tags on the same set are ignored by
+ * `CapabilityScope`.
+ */
+export declare function withSubnetLocalScope(tags: string[] | undefined): string[];
+export {};

package/dist/capabilities.js

@@ -0,0 +1,186 @@
+"use strict";
+/**
+ * Capability declarations — hardware / software / models / tools /
+ * tags / resource limits — and the filters that query them.
+ *
+ * Construct a {@link CapabilitySet} from whatever your node actually
+ * runs, hand it to {@link MeshNode.announceCapabilities}, and the
+ * mesh pushes it to every directly-connected peer. Peers keep the
+ * latest announcement from each node in their local capability
+ * index; {@link MeshNode.findNodes} queries that index.
+ *
+ * @example
+ * ```ts
+ * import { MeshNode } from '@net-mesh/sdk';
+ *
+ * await node.announceCapabilities({
+ *   hardware: {
+ *     cpuCores: 16,
+ *     memoryGb: 64,
+ *     gpu: { vendor: 'nvidia', model: 'RTX 4090', vramGb: 24 },
+ *   },
+ *   tags: ['gpu', 'inference'],
+ *   models: [{ modelId: 'llama-3.1-70b', family: 'llama' }],
+ * });
+ *
+ * const peers = node.findNodes({ requireTags: ['gpu'], minVramMb: 16_384 });
+ * ```
+ *
+ * Multi-hop propagation is deferred; today peers more than one hop
+ * away are not visible.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SCOPE_SUBNET_LOCAL = exports.SCOPE_REGION_PREFIX = exports.SCOPE_TENANT_PREFIX = void 0;
+exports.capabilitySetToNapi = capabilitySetToNapi;
+exports.capabilityFilterToNapi = capabilityFilterToNapi;
+exports.scopeFilterToNapi = scopeFilterToNapi;
+exports.withTenantScope = withTenantScope;
+exports.withRegionScope = withRegionScope;
+exports.withSubnetLocalScope = withSubnetLocalScope;
+function gpuToNapi(g) {
+    return {
+        vendor: g.vendor,
+        model: g.model,
+        vramGb: g.vramGb,
+        computeUnits: g.computeUnits,
+        tensorCores: g.tensorCores,
+        fp16TflopsX10: g.fp16TflopsX10,
+    };
+}
+function acceleratorToNapi(a) {
+    return {
+        kind: a.kind,
+        model: a.model,
+        memoryGb: a.memoryGb,
+        topsX10: a.topsX10,
+    };
+}
+function hardwareToNapi(h) {
+    return {
+        cpuCores: h.cpuCores,
+        cpuThreads: h.cpuThreads,
+        memoryGb: h.memoryGb,
+        gpu: h.gpu ? gpuToNapi(h.gpu) : undefined,
+        additionalGpus: h.additionalGpus?.map(gpuToNapi),
+        storageGb: h.storageGb,
+        networkGbps: h.networkGbps,
+        accelerators: h.accelerators?.map(acceleratorToNapi),
+    };
+}
+function pairToArray(p) {
+    return [p[0], p[1]];
+}
+function softwareToNapi(s) {
+    return {
+        os: s.os,
+        osVersion: s.osVersion,
+        runtimes: s.runtimes?.map(pairToArray),
+        frameworks: s.frameworks?.map(pairToArray),
+        cudaVersion: s.cudaVersion,
+        drivers: s.drivers?.map(pairToArray),
+    };
+}
+function modelToNapi(m) {
+    return {
+        modelId: m.modelId,
+        family: m.family,
+        parametersBX10: m.parametersBX10,
+        contextLength: m.contextLength,
+        quantization: m.quantization,
+        modalities: m.modalities,
+        tokensPerSec: m.tokensPerSec,
+        loaded: m.loaded,
+    };
+}
+function toolToNapi(t) {
+    return {
+        toolId: t.toolId,
+        name: t.name,
+        version: t.version,
+        inputSchema: t.inputSchema,
+        outputSchema: t.outputSchema,
+        requires: t.requires,
+        estimatedTimeMs: t.estimatedTimeMs,
+        stateless: t.stateless,
+    };
+}
+function capabilitySetToNapi(caps) {
+    return {
+        hardware: caps.hardware ? hardwareToNapi(caps.hardware) : undefined,
+        software: caps.software ? softwareToNapi(caps.software) : undefined,
+        models: caps.models?.map(modelToNapi),
+        tools: caps.tools?.map(toolToNapi),
+        tags: caps.tags,
+        limits: caps.limits,
+    };
+}
+function capabilityFilterToNapi(f) {
+    return {
+        requireTags: f.requireTags,
+        requireModels: f.requireModels,
+        requireTools: f.requireTools,
+        minMemoryMb: f.minMemoryMb,
+        requireGpu: f.requireGpu,
+        gpuVendor: f.gpuVendor,
+        minVramMb: f.minVramMb,
+        minContextLength: f.minContextLength,
+        requireModalities: f.requireModalities,
+    };
+}
+function scopeFilterToNapi(s) {
+    switch (s.kind) {
+        case 'any':
+        case 'globalOnly':
+        case 'sameSubnet':
+            return { kind: s.kind };
+        case 'tenant':
+            return { kind: 'tenant', tenant: s.tenant };
+        case 'tenants':
+            return { kind: 'tenants', tenants: s.tenants };
+        case 'region':
+            return { kind: 'region', region: s.region };
+        case 'regions':
+            return { kind: 'regions', regions: s.regions };
+    }
+}
+// =====================================================
+// Reserved scope tag helpers
+// =====================================================
+/** Reserved tag prefix for tenant-scoped announcements. */
+exports.SCOPE_TENANT_PREFIX = 'scope:tenant:';
+/** Reserved tag prefix for region-scoped announcements. */
+exports.SCOPE_REGION_PREFIX = 'scope:region:';
+/** Reserved tag marking an announcement subnet-local. */
+exports.SCOPE_SUBNET_LOCAL = 'scope:subnet-local';
+/**
+ * Append a `scope:tenant:<id>` tag to a tag list. Idempotent —
+ * safe to call repeatedly with the same id. Empty `tenantId` is a
+ * no-op.
+ */
+function withTenantScope(tags, tenantId) {
+    if (!tenantId)
+        return tags ?? [];
+    const tag = `${exports.SCOPE_TENANT_PREFIX}${tenantId}`;
+    const list = tags ?? [];
+    return list.includes(tag) ? list : [...list, tag];
+}
+/** Append a `scope:region:<name>` tag to a tag list. Idempotent. */
+function withRegionScope(tags, region) {
+    if (!region)
+        return tags ?? [];
+    const tag = `${exports.SCOPE_REGION_PREFIX}${region}`;
+    const list = tags ?? [];
+    return list.includes(tag) ? list : [...list, tag];
+}
+/**
+ * Append the `scope:subnet-local` tag to a tag list. Idempotent.
+ * Strictest form wins on the resolver — when this tag is present,
+ * tenant/region tags on the same set are ignored by
+ * `CapabilityScope`.
+ */
+function withSubnetLocalScope(tags) {
+    const list = tags ?? [];
+    return list.includes(exports.SCOPE_SUBNET_LOCAL)
+        ? list
+        : [...list, exports.SCOPE_SUBNET_LOCAL];
+}