@net-mesh/sdk 0.19.0

package/dist/capability-schema.d.ts

@@ -0,0 +1,112 @@
+/**
+ * Capability axis schema + `validateCapabilities` — Phase 9a of
+ * `CAPABILITY_SYSTEM_SDK_PLAN.md`.
+ *
+ * Mirrors the substrate's `AXIS_SCHEMA` const + the canonical
+ * `validate_capabilities` validator. The wire shape of the
+ * `ValidationReport` (lowercase `kind` discriminator, axis as
+ * lowercase string, value type as lowercase string) is pinned by the
+ * cross-binding fixture `tests/cross_lang_capability/capability_validation.json`.
+ *
+ * Source-of-truth for the schema is
+ * `net/crates/net/docs/CAPABILITIES_SCHEMA.md`. The substrate's Rust
+ * mirror in `behavior/schema.rs` and this TS mirror are
+ * hand-maintained against the doc; CI guards each binding's
+ * regenerated schema once the codegen tool from Phase 9a's plan
+ * lands.
+ *
+ * @packageDocumentation
+ */
+import type { CapabilitySetWire, TaxonomyAxis } from './capability-enhancements';
+export type ValueType = 'presence' | 'number' | 'string' | 'enumeration' | 'bool' | 'csv';
+export interface KeyEntry {
+    /** Full key under its axis, e.g. `cpu_cores`, `gpu.vendor`. */
+    key: string;
+    valueType: ValueType;
+}
+export type KeyShapeKind = {
+    kind: 'indexedCollection';
+} | {
+    kind: 'keyedMap';
+    valueType: ValueType;
+};
+export interface KeyShape {
+    /** Axis-relative prefix, e.g. `model.` (trailing `.` mandatory). */
+    prefix: string;
+    shape: KeyShapeKind;
+    /** Per-element sub-keys for indexed collections; empty for keyed maps. */
+    subKeys: KeyEntry[];
+}
+export interface AxisEntry {
+    keys: KeyEntry[];
+    shapes: KeyShape[];
+}
+export interface AxisSchema {
+    hardware: AxisEntry;
+    software: AxisEntry;
+    devices: AxisEntry;
+    dataforts: AxisEntry;
+    metadataReserved: string[];
+    metadataReservedPrefixes: string[];
+}
+/** Reserved metadata keys (substrate-defined). */
+export declare const METADATA_RESERVED_KEYS: readonly string[];
+/** Reserved metadata-key prefixes (`tool::<id>::input_schema` etc.). */
+export declare const METADATA_RESERVED_PREFIXES: readonly string[];
+/** Default soft cap for `metadata` total size. */
+export declare const METADATA_SOFT_CAP_BYTES: number;
+/** The canonical axis schema. Mirrors `behavior::schema::AXIS_SCHEMA`. */
+export declare const AXIS_SCHEMA: AxisSchema;
+export type SchemaError = {
+    kind: 'unknown_axis';
+    axis_prefix: string;
+    tag: string;
+} | {
+    kind: 'type_mismatch';
+    axis: TaxonomyAxis;
+    key: string;
+    expected: ValueType;
+    actual: string;
+} | {
+    kind: 'index_malformed';
+    axis: TaxonomyAxis;
+    prefix: string;
+    index: string;
+    tag: string;
+};
+export type ValidationWarning = {
+    kind: 'unknown_key';
+    axis: TaxonomyAxis;
+    key: string;
+} | {
+    kind: 'metadata_oversize';
+    soft_cap_bytes: number;
+    actual_bytes: number;
+} | {
+    kind: 'legacy_tag';
+    tag: string;
+} | {
+    kind: 'metadata_reserved_key';
+    key: string;
+} | {
+    kind: 'metadata_reserved_prefix';
+    key: string;
+    prefix: string;
+};
+export interface ValidationReport {
+    errors: SchemaError[];
+    warnings: ValidationWarning[];
+}
+/**
+ * Validate a wire-format capability set against a schema. Defaults to
+ * the canonical {@link AXIS_SCHEMA}; pass a custom schema for
+ * application-specific extensions.
+ *
+ * Mirrors the substrate's `validate_capabilities`. Output shape pinned
+ * by `tests/cross_lang_capability/capability_validation.json`.
+ */
+export declare function validateCapabilities(caps: CapabilitySetWire, schema?: AxisSchema): ValidationReport;
+/** True iff there are zero errors and zero warnings. */
+export declare function isReportClean(r: ValidationReport): boolean;
+/** True iff there are zero errors. Warnings are allowed. */
+export declare function isReportValid(r: ValidationReport): boolean;

package/dist/capability-schema.js

@@ -0,0 +1,317 @@
+"use strict";
+/**
+ * Capability axis schema + `validateCapabilities` — Phase 9a of
+ * `CAPABILITY_SYSTEM_SDK_PLAN.md`.
+ *
+ * Mirrors the substrate's `AXIS_SCHEMA` const + the canonical
+ * `validate_capabilities` validator. The wire shape of the
+ * `ValidationReport` (lowercase `kind` discriminator, axis as
+ * lowercase string, value type as lowercase string) is pinned by the
+ * cross-binding fixture `tests/cross_lang_capability/capability_validation.json`.
+ *
+ * Source-of-truth for the schema is
+ * `net/crates/net/docs/CAPABILITIES_SCHEMA.md`. The substrate's Rust
+ * mirror in `behavior/schema.rs` and this TS mirror are
+ * hand-maintained against the doc; CI guards each binding's
+ * regenerated schema once the codegen tool from Phase 9a's plan
+ * lands.
+ *
+ * @packageDocumentation
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.AXIS_SCHEMA = exports.METADATA_SOFT_CAP_BYTES = exports.METADATA_RESERVED_PREFIXES = exports.METADATA_RESERVED_KEYS = void 0;
+exports.validateCapabilities = validateCapabilities;
+exports.isReportClean = isReportClean;
+exports.isReportValid = isReportValid;
+const capability_enhancements_1 = require("./capability-enhancements");
+// ============================================================================
+// AXIS_SCHEMA — mirrors `behavior::schema::AXIS_SCHEMA`.
+// ============================================================================
+const HARDWARE_KEYS = [
+    { key: 'cpu_cores', valueType: 'number' },
+    { key: 'cpu_threads', valueType: 'number' },
+    { key: 'memory_gb', valueType: 'number' },
+    { key: 'gpu', valueType: 'presence' },
+    { key: 'gpu.vendor', valueType: 'enumeration' },
+    { key: 'gpu.model', valueType: 'string' },
+    { key: 'gpu.vram_gb', valueType: 'number' },
+    { key: 'gpu.compute_units', valueType: 'number' },
+    { key: 'gpu.tensor_cores', valueType: 'number' },
+    { key: 'gpu.fp16_tflops_x10', valueType: 'number' },
+    { key: 'storage_gb', valueType: 'number' },
+    { key: 'network_gbps', valueType: 'number' },
+    { key: 'limits.max_concurrent_requests', valueType: 'number' },
+    { key: 'limits.max_tokens_per_request', valueType: 'number' },
+    { key: 'limits.rate_limit_rpm', valueType: 'number' },
+    { key: 'limits.max_batch_size', valueType: 'number' },
+    { key: 'limits.max_input_bytes', valueType: 'number' },
+    { key: 'limits.max_output_bytes', valueType: 'number' },
+];
+const SOFTWARE_KEYS = [
+    { key: 'os', valueType: 'string' },
+    { key: 'os_version', valueType: 'string' },
+    { key: 'cuda_version', valueType: 'string' },
+];
+const SOFTWARE_SHAPES = [
+    {
+        prefix: 'runtime.',
+        shape: { kind: 'keyedMap', valueType: 'string' },
+        subKeys: [],
+    },
+    {
+        prefix: 'framework.',
+        shape: { kind: 'keyedMap', valueType: 'string' },
+        subKeys: [],
+    },
+    {
+        prefix: 'driver.',
+        shape: { kind: 'keyedMap', valueType: 'string' },
+        subKeys: [],
+    },
+    {
+        prefix: 'model.',
+        shape: { kind: 'indexedCollection' },
+        subKeys: [
+            { key: 'id', valueType: 'string' },
+            { key: 'family', valueType: 'string' },
+            { key: 'parameters_b_x10', valueType: 'number' },
+            { key: 'context_length', valueType: 'number' },
+            { key: 'quantization', valueType: 'string' },
+            { key: 'modalities', valueType: 'csv' },
+            { key: 'tokens_per_sec', valueType: 'number' },
+            { key: 'loaded', valueType: 'bool' },
+        ],
+    },
+    {
+        prefix: 'tool.',
+        shape: { kind: 'indexedCollection' },
+        subKeys: [
+            { key: 'tool_id', valueType: 'string' },
+            { key: 'name', valueType: 'string' },
+            { key: 'version', valueType: 'string' },
+            { key: 'requires', valueType: 'csv' },
+            { key: 'estimated_time_ms', valueType: 'number' },
+            { key: 'stateless', valueType: 'bool' },
+        ],
+    },
+];
+/** Reserved metadata keys (substrate-defined). */
+exports.METADATA_RESERVED_KEYS = [
+    'intent',
+    'colocate-with',
+    'colocate-with-strict',
+    'priority',
+    'owner',
+];
+/** Reserved metadata-key prefixes (`tool::<id>::input_schema` etc.). */
+exports.METADATA_RESERVED_PREFIXES = ['tool::'];
+/** Default soft cap for `metadata` total size. */
+exports.METADATA_SOFT_CAP_BYTES = 4 * 1024;
+/** The canonical axis schema. Mirrors `behavior::schema::AXIS_SCHEMA`. */
+exports.AXIS_SCHEMA = {
+    hardware: { keys: HARDWARE_KEYS, shapes: [] },
+    software: { keys: SOFTWARE_KEYS, shapes: SOFTWARE_SHAPES },
+    devices: { keys: [], shapes: [] },
+    dataforts: { keys: [], shapes: [] },
+    metadataReserved: [...exports.METADATA_RESERVED_KEYS],
+    metadataReservedPrefixes: [...exports.METADATA_RESERVED_PREFIXES],
+};
+// ============================================================================
+// Validator
+// ============================================================================
+function axisEntry(schema, axis) {
+    switch (axis) {
+        case 'hardware':
+            return schema.hardware;
+        case 'software':
+            return schema.software;
+        case 'devices':
+            return schema.devices;
+        case 'dataforts':
+            return schema.dataforts;
+    }
+}
+function checkValue(entry, observedType, observedValue, axis, errors) {
+    if (entry.valueType === 'presence') {
+        if (observedType !== 'presence') {
+            errors.push({
+                kind: 'type_mismatch',
+                axis,
+                key: entry.key,
+                expected: 'presence',
+                actual: observedValue ?? '',
+            });
+        }
+        return;
+    }
+    if (observedValue === undefined) {
+        errors.push({
+            kind: 'type_mismatch',
+            axis,
+            key: entry.key,
+            expected: entry.valueType,
+            actual: '<no value>',
+        });
+        return;
+    }
+    let parses = false;
+    switch (entry.valueType) {
+        case 'number':
+            // Substrate `Number` is unsigned (u64-only) — Rust uses
+            // `value.parse::<u64>()` (schema.rs:704). The accepted-set is
+            // ASCII digits with an optional leading `+`, bounded by
+            // `u64::MAX` (18446744073709551615). N-5: the pre-fix regex
+            // `^\d+$` admitted values exceeding u64::MAX (e.g.
+            // `18446744073709551616`) that the substrate rejects; mirror
+            // the Python `_U64_LITERAL` + `int(...) <= u64::MAX` shape so
+            // cross-binding fixture rows agree.
+            if (/^\+?[0-9]+$/.test(observedValue)) {
+                try {
+                    parses = BigInt(observedValue) <= 0xffffffffffffffffn;
+                }
+                catch {
+                    parses = false;
+                }
+            }
+            break;
+        case 'string':
+        case 'enumeration':
+        case 'csv':
+            parses = observedValue.length > 0;
+            break;
+        case 'bool':
+            parses = observedValue === 'true' || observedValue === 'false';
+            break;
+    }
+    if (!parses) {
+        errors.push({
+            kind: 'type_mismatch',
+            axis,
+            key: entry.key,
+            expected: entry.valueType,
+            actual: observedValue,
+        });
+    }
+}
+function validateAxisKey(axis, key, observedType, observedValue, schema, errors, warnings, tagWire) {
+    const entry = axisEntry(schema, axis);
+    const fixed = entry.keys.find((e) => e.key === key);
+    if (fixed) {
+        checkValue(fixed, observedType, observedValue, axis, errors);
+        return;
+    }
+    for (const shape of entry.shapes) {
+        if (!key.startsWith(shape.prefix))
+            continue;
+        const rest = key.slice(shape.prefix.length);
+        if (shape.shape.kind === 'indexedCollection') {
+            const dot = rest.indexOf('.');
+            if (dot < 0)
+                continue;
+            const idx = rest.slice(0, dot);
+            const sub = rest.slice(dot + 1);
+            // Q10: substrate parses the index as `u32`; strings of digits
+            // longer than `u32::MAX` (e.g. `"4294967296"`, 2^32) are
+            // accepted by the TS regex but rejected by the substrate as
+            // `IndexMalformed`. Mirror the u32 range so client-side
+            // validation doesn't silently pass payloads the substrate
+            // would later reject.
+            const idxNum = Number(idx);
+            if (!/^\d+$/.test(idx) ||
+                !Number.isInteger(idxNum) ||
+                idxNum > 0xffff_ffff) {
+                errors.push({
+                    kind: 'index_malformed',
+                    axis,
+                    prefix: shape.prefix,
+                    index: idx,
+                    tag: tagWire,
+                });
+                return;
+            }
+            const subEntry = shape.subKeys.find((e) => e.key === sub);
+            if (subEntry) {
+                checkValue(subEntry, observedType, observedValue, axis, errors);
+                return;
+            }
+            warnings.push({ kind: 'unknown_key', axis, key });
+            return;
+        }
+        // KeyedMap: the rest IS the user-defined name.
+        if (rest.length > 0) {
+            const synth = {
+                key: shape.prefix,
+                valueType: shape.shape.valueType,
+            };
+            checkValue(synth, observedType, observedValue, axis, errors);
+            return;
+        }
+    }
+    warnings.push({ kind: 'unknown_key', axis, key });
+}
+/**
+ * Validate a wire-format capability set against a schema. Defaults to
+ * the canonical {@link AXIS_SCHEMA}; pass a custom schema for
+ * application-specific extensions.
+ *
+ * Mirrors the substrate's `validate_capabilities`. Output shape pinned
+ * by `tests/cross_lang_capability/capability_validation.json`.
+ */
+function validateCapabilities(caps, schema = exports.AXIS_SCHEMA) {
+    const errors = [];
+    const warnings = [];
+    for (const wire of caps.tags) {
+        const tag = (0, capability_enhancements_1.tagFromString)(wire);
+        switch (tag.kind) {
+            case 'axisPresent':
+                validateAxisKey(tag.axis, tag.key, 'presence', undefined, schema, errors, warnings, wire);
+                break;
+            case 'axisValue':
+                validateAxisKey(tag.axis, tag.key, 'string', tag.value, schema, errors, warnings, wire);
+                break;
+            case 'reserved':
+                // Reserved-prefix tags pass through unchecked.
+                break;
+            case 'legacy':
+                warnings.push({ kind: 'legacy_tag', tag: tag.raw });
+                break;
+        }
+    }
+    // P2-H: metadata-key reservation check. The schema declares
+    // `metadataReserved` (exact-match) and `metadataReservedPrefixes`
+    // (prefix-match) but pre-fix the validator never consulted them
+    // — a user's `with_metadata("intent", …)` smuggling onto a
+    // scheduler-reserved key emitted no warning. Mirrors the
+    // substrate's CR-14 fix.
+    for (const key of Object.keys(caps.metadata)) {
+        if (schema.metadataReserved.includes(key)) {
+            warnings.push({ kind: 'metadata_reserved_key', key });
+            continue;
+        }
+        const prefix = schema.metadataReservedPrefixes.find((p) => key.startsWith(p));
+        if (prefix !== undefined) {
+            warnings.push({ kind: 'metadata_reserved_prefix', key, prefix });
+        }
+    }
+    // Metadata soft-cap check.
+    let metadataBytes = 0;
+    for (const [k, v] of Object.entries(caps.metadata)) {
+        metadataBytes += k.length + v.length;
+    }
+    if (metadataBytes > exports.METADATA_SOFT_CAP_BYTES) {
+        warnings.push({
+            kind: 'metadata_oversize',
+            soft_cap_bytes: exports.METADATA_SOFT_CAP_BYTES,
+            actual_bytes: metadataBytes,
+        });
+    }
+    return { errors, warnings };
+}
+/** True iff there are zero errors and zero warnings. */
+function isReportClean(r) {
+    return r.errors.length === 0 && r.warnings.length === 0;
+}
+/** True iff there are zero errors. Warnings are allowed. */
+function isReportValid(r) {
+    return r.errors.length === 0;
+}

package/dist/channel.d.ts

@@ -0,0 +1,56 @@
+/**
+ * Typed channels — strongly typed pub/sub over named channels.
+ */
+import type { Net as NapiNet } from '@net-mesh/core';
+import type { SubscribeOpts } from './types';
+import { EventStream, TypedEventStream } from './stream';
+/**
+ * A strongly typed channel for publishing and subscribing to events.
+ *
+ * @example
+ * ```typescript
+ * interface TemperatureReading {
+ *   sensor_id: string;
+ *   celsius: number;
+ *   timestamp: number;
+ * }
+ *
+ * const temps = node.channel<TemperatureReading>('sensors/temperature');
+ * temps.publish({ sensor_id: 'A1', celsius: 22.5, timestamp: Date.now() });
+ *
+ * for await (const reading of temps.subscribe()) {
+ *   console.log(`${reading.sensor_id}: ${reading.celsius}°C`);
+ * }
+ * ```
+ */
+export declare class TypedChannel<T> {
+    private bus;
+    private channelName;
+    private validator?;
+    private readonly filter;
+    constructor(bus: NapiNet, channelName: string, validator?: (data: unknown) => T);
+    /** The channel name. */
+    get name(): string;
+    /**
+     * Publish a typed event to this channel.
+     *
+     * The event is serialized to JSON with the channel name embedded.
+     */
+    publish(event: T): boolean;
+    /**
+     * Publish a batch of typed events to this channel.
+     * Returns the number of events successfully published.
+     */
+    publishBatch(events: T[]): number;
+    /**
+     * Subscribe to typed events on this channel.
+     *
+     * Returns an async iterable that deserializes and optionally validates
+     * each event.
+     */
+    subscribe(opts?: SubscribeOpts): TypedEventStream<T>;
+    /**
+     * Subscribe to raw events on this channel.
+     */
+    subscribeRaw(opts?: SubscribeOpts): EventStream;
+}

package/dist/channel.js

@@ -0,0 +1,95 @@
+"use strict";
+/**
+ * Typed channels — strongly typed pub/sub over named channels.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.TypedChannel = void 0;
+const stream_1 = require("./stream");
+/**
+ * A strongly typed channel for publishing and subscribing to events.
+ *
+ * @example
+ * ```typescript
+ * interface TemperatureReading {
+ *   sensor_id: string;
+ *   celsius: number;
+ *   timestamp: number;
+ * }
+ *
+ * const temps = node.channel<TemperatureReading>('sensors/temperature');
+ * temps.publish({ sensor_id: 'A1', celsius: 22.5, timestamp: Date.now() });
+ *
+ * for await (const reading of temps.subscribe()) {
+ *   console.log(`${reading.sensor_id}: ${reading.celsius}°C`);
+ * }
+ * ```
+ */
+class TypedChannel {
+    bus;
+    channelName;
+    validator;
+    // Filter is a constant for the lifetime of the channel; build the
+    // JSON string once instead of regenerating it on every subscribe /
+    // subscribeRaw call.
+    filter;
+    constructor(bus, channelName, validator) {
+        this.bus = bus;
+        this.channelName = channelName;
+        this.validator = validator;
+        this.filter = JSON.stringify({ path: '_channel', value: channelName });
+    }
+    /** The channel name. */
+    get name() {
+        return this.channelName;
+    }
+    /**
+     * Publish a typed event to this channel.
+     *
+     * The event is serialized to JSON with the channel name embedded.
+     */
+    publish(event) {
+        const payload = JSON.stringify({
+            ...event,
+            _channel: this.channelName,
+        });
+        return this.bus.ingestFire(payload);
+    }
+    /**
+     * Publish a batch of typed events to this channel.
+     * Returns the number of events successfully published.
+     */
+    publishBatch(events) {
+        const payloads = events.map((event) => JSON.stringify({
+            ...event,
+            _channel: this.channelName,
+        }));
+        return this.bus.ingestBatchFire(payloads);
+    }
+    /**
+     * Subscribe to typed events on this channel.
+     *
+     * Returns an async iterable that deserializes and optionally validates
+     * each event.
+     */
+    subscribe(opts = {}) {
+        const mergedOpts = {
+            ...opts,
+            filter: opts.filter ?? this.filter,
+        };
+        const parse = this.validator
+            ? (raw) => this.validator(JSON.parse(raw))
+            : (raw) => JSON.parse(raw);
+        return new stream_1.TypedEventStream(this.bus, mergedOpts, parse);
+    }
+    /**
+     * Subscribe to raw events on this channel.
+     */
+    subscribeRaw(opts = {}) {
+        const mergedOpts = {
+            ...opts,
+            filter: opts.filter ?? this.filter,
+        };
+        return new stream_1.EventStream(this.bus, mergedOpts);
+    }
+}
+exports.TypedChannel = TypedChannel;