@net-mesh/sdk 0.19.0

package/dist/capability-enhancements.d.ts

@@ -0,0 +1,574 @@
+/**
+ * Capability-System Enhancements — TypeScript surface.
+ *
+ * This module mirrors the substrate's enhancement-track types:
+ *
+ * - Typed taxonomy ({@link Tag}, {@link TagKey}, {@link TaxonomyAxis})
+ *   with reserved-prefix enforcement at construction time.
+ * - Fluent {@link Predicate} builder (`p.*`) producing the canonical
+ *   wire IR (`PredicateWire`) consumed by `net-where` headers.
+ * - {@link diffCapabilities} returning the same `CapabilitySetDiff`
+ *   shape the cross-binding fixtures pin.
+ * - {@link requireTag} / {@link requireAxisValue} chain helpers
+ *   producing `{ tags, metadata }` directly.
+ * - {@link StandardPlacement} configuration object + the
+ *   {@link placementFilterFromFn} callback shape.
+ *
+ * All wire-format types match the JSON shape the substrate emits via
+ * `serde_json` — the cross-binding tests in
+ * `tests/cross_lang_capability/` pin the canonical bytes.
+ *
+ * @packageDocumentation
+ */
+/**
+ * Canonical capability axis. Mirrors `TaxonomyAxis` in the substrate
+ * (`adapter::net::behavior::tag::TaxonomyAxis`). The wire form is the
+ * lowercase string.
+ */
+export type TaxonomyAxis = 'hardware' | 'software' | 'devices' | 'dataforts';
+/** Every axis the substrate knows about. */
+export declare const TAXONOMY_AXES: readonly TaxonomyAxis[];
+/**
+ * Reserved cross-axis prefixes. Substrate-privileged paths
+ * (`announceChain`, fork-coordination, scope helpers) emit these;
+ * user code calling {@link tagFromUserString} is rejected.
+ */
+export declare const RESERVED_PREFIXES: readonly string[];
+/**
+ * `<axis>.<key>` identifier — the addressing pair for axis-prefixed
+ * tags and axis-keyed predicates.
+ */
+export interface TagKey {
+    axis: TaxonomyAxis;
+    /** Key within the axis namespace (e.g. `gpu`, `runtime.python`). */
+    key: string;
+}
+/**
+ * Build a {@link TagKey}. Throws on empty key — matches the substrate's
+ * `TagKey::new` contract (the constructor is fallible-by-debug-assert
+ * there; we surface as a thrown error here).
+ */
+export declare function tagKey(axis: TaxonomyAxis, key: string): TagKey;
+/** Separator between an axis-tag's key and its value. */
+export type AxisSeparator = ':' | '=';
+/**
+ * Typed tag. Mirrors `Tag` in the substrate. The wire form is the
+ * canonical Display string ({@link tagToString}).
+ *
+ * - `axisPresent` — `<axis>.<key>` (no value).
+ * - `axisValue` — `<axis>.<key>=<value>` or `<axis>.<key>:<value>`.
+ * - `reserved` — one of the {@link RESERVED_PREFIXES} cross-axis tags.
+ * - `legacy` — arbitrary string outside the typed taxonomy. The
+ *   substrate keeps these as-is for forward compatibility.
+ */
+export type Tag = {
+    kind: 'axisPresent';
+    axis: TaxonomyAxis;
+    key: string;
+} | {
+    kind: 'axisValue';
+    axis: TaxonomyAxis;
+    key: string;
+    value: string;
+    separator: AxisSeparator;
+} | {
+    kind: 'reserved';
+    prefix: string;
+    body: string;
+} | {
+    kind: 'legacy';
+    raw: string;
+};
+/** True iff `s` starts with one of the {@link RESERVED_PREFIXES}. */
+export declare function startsWithReservedPrefix(s: string): string | undefined;
+/**
+ * Render a {@link Tag} to its canonical wire string. Matches the
+ * substrate's `Display` impl for `Tag`.
+ */
+export declare function tagToString(tag: Tag): string;
+/**
+ * Parse a wire string into a {@link Tag}. Privileged path — does
+ * NOT reject reserved prefixes (substrate code that legitimately
+ * needs to round-trip e.g. `scope:tenant:foo` calls this).
+ *
+ * User code should prefer {@link tagFromUserString}, which rejects
+ * reserved prefixes.
+ */
+export declare function tagFromString(s: string): Tag;
+/**
+ * Parse a wire string from user code. Rejects the reserved
+ * cross-axis prefixes ({@link RESERVED_PREFIXES}) — application code
+ * cannot emit those by design. Mirrors the substrate's
+ * `Tag::parse_user`.
+ */
+export declare function tagFromUserString(s: string): Tag;
+/** Numeric kinds — match the substrate's wire `kind` strings exactly. */
+export type PredicateNode = {
+    kind: 'exists';
+    key: TagKey;
+} | {
+    kind: 'equals';
+    key: TagKey;
+    value: string;
+} | {
+    kind: 'numeric_at_least';
+    key: TagKey;
+    threshold: number;
+} | {
+    kind: 'numeric_at_most';
+    key: TagKey;
+    threshold: number;
+} | {
+    kind: 'numeric_in_range';
+    key: TagKey;
+    min: number;
+    max: number;
+} | {
+    kind: 'semver_at_least';
+    key: TagKey;
+    version: string;
+} | {
+    kind: 'semver_at_most';
+    key: TagKey;
+    version: string;
+} | {
+    kind: 'semver_compatible';
+    key: TagKey;
+    version: string;
+} | {
+    kind: 'string_prefix';
+    key: TagKey;
+    prefix: string;
+} | {
+    kind: 'string_matches';
+    key: TagKey;
+    pattern: string;
+} | {
+    kind: 'metadata_exists';
+    key: string;
+} | {
+    kind: 'metadata_equals';
+    key: string;
+    value: string;
+} | {
+    kind: 'metadata_matches';
+    key: string;
+    pattern: string;
+} | {
+    kind: 'metadata_numeric_at_least';
+    key: string;
+    threshold: number;
+} | {
+    kind: 'and';
+    children: number[];
+} | {
+    kind: 'or';
+    children: number[];
+} | {
+    kind: 'not';
+    child: number;
+};
+/**
+ * Wire-format predicate. The exact JSON shape the substrate's
+ * `net-where` request header carries; pinned by the
+ * `predicate_nrpc_envelope.json` cross-binding fixture.
+ */
+export interface PredicateWire {
+    nodes: PredicateNode[];
+    root_idx: number;
+}
+/**
+ * In-memory predicate AST. Sugar over {@link PredicateWire} — the
+ * fluent {@link p} builder constructs these and {@link predicateToWire}
+ * flattens them.
+ */
+export type Predicate = {
+    type: 'exists';
+    key: TagKey;
+} | {
+    type: 'equals';
+    key: TagKey;
+    value: string;
+} | {
+    type: 'numericAtLeast';
+    key: TagKey;
+    threshold: number;
+} | {
+    type: 'numericAtMost';
+    key: TagKey;
+    threshold: number;
+} | {
+    type: 'numericInRange';
+    key: TagKey;
+    min: number;
+    max: number;
+} | {
+    type: 'semverAtLeast';
+    key: TagKey;
+    version: string;
+} | {
+    type: 'semverAtMost';
+    key: TagKey;
+    version: string;
+} | {
+    type: 'semverCompatible';
+    key: TagKey;
+    version: string;
+} | {
+    type: 'stringPrefix';
+    key: TagKey;
+    prefix: string;
+} | {
+    type: 'stringMatches';
+    key: TagKey;
+    pattern: string;
+} | {
+    type: 'metadataExists';
+    key: string;
+} | {
+    type: 'metadataEquals';
+    key: string;
+    value: string;
+} | {
+    type: 'metadataMatches';
+    key: string;
+    pattern: string;
+} | {
+    type: 'metadataNumericAtLeast';
+    key: string;
+    threshold: number;
+} | {
+    type: 'and';
+    children: Predicate[];
+} | {
+    type: 'or';
+    children: Predicate[];
+} | {
+    type: 'not';
+    child: Predicate;
+};
+/**
+ * Fluent predicate constructors. Match the substrate's `Predicate::*`
+ * factory methods one-to-one.
+ *
+ * @example
+ * ```ts
+ * import { p, predicateToWire } from '@net-mesh/sdk';
+ *
+ * const pred = p.and(
+ *   p.exists({ axis: 'hardware', key: 'gpu' }),
+ *   p.numericAtLeast({ axis: 'hardware', key: 'memory_gb' }, 64),
+ *   p.metadataEquals('intent', 'ml-training'),
+ * );
+ * const wire = predicateToWire(pred);
+ * ```
+ */
+export declare const p: {
+    readonly exists: (key: TagKey) => Predicate;
+    readonly equals: (key: TagKey, value: string) => Predicate;
+    readonly numericAtLeast: (key: TagKey, threshold: number) => Predicate;
+    readonly numericAtMost: (key: TagKey, threshold: number) => Predicate;
+    readonly numericInRange: (key: TagKey, min: number, max: number) => Predicate;
+    readonly semverAtLeast: (key: TagKey, version: string) => Predicate;
+    readonly semverAtMost: (key: TagKey, version: string) => Predicate;
+    readonly semverCompatible: (key: TagKey, version: string) => Predicate;
+    readonly stringPrefix: (key: TagKey, prefix: string) => Predicate;
+    readonly stringMatches: (key: TagKey, pattern: string) => Predicate;
+    readonly metadataExists: (key: string) => Predicate;
+    readonly metadataEquals: (key: string, value: string) => Predicate;
+    readonly metadataMatches: (key: string, pattern: string) => Predicate;
+    readonly metadataNumericAtLeast: (key: string, threshold: number) => Predicate;
+    readonly and: (...children: Predicate[]) => Predicate;
+    readonly or: (...children: Predicate[]) => Predicate;
+    readonly not: (child: Predicate) => Predicate;
+};
+/** Flatten an AST into the wire IR. Children always sit at lower
+ * indices than their parents (post-order). */
+export declare function predicateToWire(pred: Predicate): PredicateWire;
+/** Inverse of {@link predicateToWire}. Rebuilds the AST from a wire
+ * IR. Throws on out-of-range indices or malformed nodes. */
+export declare function predicateFromWire(wire: PredicateWire): Predicate;
+/** Header the substrate uses to carry a predicate over nRPC. */
+export declare const RPC_WHERE_HEADER = "net-where";
+/** Encode a predicate into the request-header value. The substrate
+ * pins this as the canonical JSON-encoded {@link PredicateWire}. */
+export declare function predicateToRpcHeader(pred: Predicate): string;
+/** Decode a `net-where` header value back into an AST. Throws
+ * on malformed JSON or out-of-range indices. */
+export declare function predicateFromRpcHeader(value: string): Predicate;
+/**
+ * Build the `net-where:` request-header entry for a
+ * Phase 9b predicate-pushdown call. Drops straight into a
+ * `MeshRpc.call` `CallOptions.requestHeaders` array.
+ *
+ * @example
+ * ```ts
+ * import { p, tagKey, whereHeader } from '@net-mesh/sdk';
+ * const pred = p.exists(tagKey('hardware', 'gpu'));
+ * await rpc.call(targetNodeId, 'filter-svc', body, {
+ *   requestHeaders: [whereHeader(pred)],
+ * });
+ * ```
+ *
+ * The header value is the canonical JSON-encoded `PredicateWire`
+ * pinned by `predicate_nrpc_envelope.json`.
+ */
+export declare function whereHeader(pred: Predicate): {
+    name: string;
+    value: Buffer;
+};
+/** Wire-format capability shape — string tags + string→string metadata. */
+export interface CapabilitySetWire {
+    tags: string[];
+    metadata: Record<string, string>;
+}
+/** Per-key metadata change. Mirrors `MetadataChange` in the substrate. */
+export type MetadataChange = {
+    kind: 'added';
+    key: string;
+    value: string;
+} | {
+    kind: 'removed';
+    key: string;
+    prev_value: string;
+} | {
+    kind: 'updated';
+    key: string;
+    prev_value: string;
+    new_value: string;
+};
+/** Diff between two capability snapshots. Mirrors
+ * `CapabilitySetDiff` in the substrate. */
+export interface CapabilitySetDiff {
+    added_tags: string[];
+    removed_tags: string[];
+    metadata_changes: MetadataChange[];
+}
+/**
+ * Compute `curr.diff(prev)`. Pinned by the
+ * `capability_set_diff.json` cross-binding fixture.
+ *
+ * - Tag arrays are sorted by wire string.
+ * - Metadata changes are sorted by key (BTreeMap semantics in the
+ *   substrate).
+ * - A key rename surfaces as Removed + Added (NOT Updated). Only a
+ *   value change for the same key is Updated.
+ */
+export declare function diffCapabilities(prev: CapabilitySetWire, curr: CapabilitySetWire): CapabilitySetDiff;
+/**
+ * Add an axis-tag (no value) to the wire shape. Idempotent; no-op
+ * if the tag is already present.
+ */
+export declare function requireTag(caps: CapabilitySetWire, axis: TaxonomyAxis, key: string): CapabilitySetWire;
+/**
+ * Add an axis-value tag (`<axis>.<key>=<value>` by default) to the
+ * wire shape. Idempotent for the exact (axis, key, value, separator)
+ * triple.
+ */
+export declare function requireAxisValue(caps: CapabilitySetWire, axis: TaxonomyAxis, key: string, value: string, separator?: AxisSeparator): CapabilitySetWire;
+/** Set / overwrite a metadata entry. */
+export declare function withMetadata(caps: CapabilitySetWire, key: string, value: string): CapabilitySetWire;
+/** Empty wire-format capability set. */
+export declare function emptyCapabilities(): CapabilitySetWire;
+/**
+ * Configuration for the substrate's `StandardPlacement` filter. All
+ * fields are optional — an empty config matches every node.
+ *
+ * The wire shape is JSON-friendly (`predicate` carries a
+ * {@link PredicateWire}, not the AST). Bindings encode this object
+ * before handing it to the runtime.
+ */
+export interface StandardPlacement {
+    /**
+     * Required tags — every listed wire-string must be present. Use
+     * {@link tagToString} to turn typed {@link Tag} values into
+     * wire form.
+     */
+    requireTags?: string[];
+    /**
+     * Forbidden tags — none of these may be present. Same wire form
+     * as {@link requireTags}.
+     */
+    forbidTags?: string[];
+    /** Required metadata key/value equalities. */
+    requireMetadata?: Record<string, string>;
+    /**
+     * Free-form predicate evaluated against each candidate's tag set
+     * + metadata. Combined with the tag/metadata constraints via AND.
+     */
+    predicate?: PredicateWire;
+    /**
+     * Maximum candidates to return. The runtime picks deterministically
+     * by node id when more match.
+     */
+    limit?: number;
+    /**
+     * Custom placement filter — a string id resolved by the runtime
+     * to a registered callback (see {@link placementFilterFromFn}).
+     */
+    customFilterId?: string;
+}
+/**
+ * Builder for {@link StandardPlacement}. Returns a frozen config
+ * object suitable for handing to the runtime.
+ */
+export declare class StandardPlacementBuilder {
+    private cfg;
+    requireTag(axis: TaxonomyAxis, key: string): this;
+    requireAxisValue(axis: TaxonomyAxis, key: string, value: string, separator?: AxisSeparator): this;
+    forbidTag(axis: TaxonomyAxis, key: string): this;
+    requireMetadata(key: string, value: string): this;
+    withPredicate(pred: Predicate | PredicateWire): this;
+    withLimit(n: number): this;
+    withCustomFilterId(id: string): this;
+    build(): StandardPlacement;
+}
+/** Convenience constructor for a {@link StandardPlacementBuilder}. */
+export declare function standardPlacement(): StandardPlacementBuilder;
+/**
+ * Candidate handed to a custom placement-filter callback. The
+ * runtime materializes one of these per candidate before evaluating
+ * the user predicate.
+ */
+export interface PlacementCandidate {
+    nodeId: bigint;
+    tags: string[];
+    metadata: Record<string, string>;
+}
+/**
+ * Synchronous predicate: `true` to keep, `false` to drop.
+ *
+ * Custom filters run under the placement hot path — keep them tight
+ * and avoid I/O. The runtime registers them by id; the daemon's
+ * {@link StandardPlacement} references that id via
+ * {@link StandardPlacement.customFilterId}.
+ */
+export type PlacementFilterFn = (candidate: PlacementCandidate) => boolean;
+/**
+ * Wrap a user-supplied predicate as a placement filter. Returns a
+ * `{ id, fn }` pair the binding can register with the runtime —
+ * future `StandardPlacement.customFilterId = id` uses route through
+ * the wrapped function.
+ *
+ * The default id generator uses a counter; callers can supply an
+ * explicit id when they want stable identity (e.g. for hot-reload).
+ */
+export interface RegisteredPlacementFilter {
+    id: string;
+    fn: PlacementFilterFn;
+}
+export declare function placementFilterFromFn(fn: PlacementFilterFn, explicitId?: string): RegisteredPlacementFilter;
+/**
+ * Evaluate a {@link Predicate} against a wire-format `(tags, metadata)`
+ * context. Mirrors the substrate's `Predicate::evaluate_unplanned`
+ * — children of `and` / `or` evaluate in declaration order with
+ * standard short-circuit semantics.
+ *
+ * Pinned across bindings by `predicate_eval.json`. Use this for local
+ * pre-filtering of result sets before sending an nRPC `where:`
+ * predicate over the wire, or for client-side validation of a
+ * predicate against a known capability set.
+ */
+export declare function evaluatePredicate(pred: Predicate, tags: readonly string[], metadata: Readonly<Record<string, string>>): boolean;
+/**
+ * Per-clause trace entry. Mirrors the substrate's `ClauseTrace`:
+ * each leaf carries a one-line `label` + the boolean `result`;
+ * composites carry the planner-ordered subset of children that
+ * actually ran.
+ */
+export interface ClauseTrace {
+    label: string;
+    result: boolean;
+    children: ClauseTrace[];
+}
+/**
+ * Evaluate a predicate against `(tags, metadata)` and produce a
+ * trace tree.
+ *
+ * Mirrors the substrate's `Predicate::evaluate_with_trace`:
+ * - `And` / `Or` children evaluated in cost-ascending order.
+ * - Short-circuited siblings DON'T appear in the trace — operators
+ *   see "the metadata clause failed; we never got to the GPU
+ *   check."
+ * - `Not`'s child carries the pre-negation result; `Not`'s own node
+ *   carries the post-negation result.
+ *
+ * Pinned across bindings by `predicate_trace.json`. Useful for
+ * client-side debugging of why a candidate did / didn't match
+ * before hitting the wire.
+ */
+export declare function evaluatePredicateWithTrace(pred: Predicate, tags: readonly string[], metadata: Readonly<Record<string, string>>): {
+    result: boolean;
+    trace: ClauseTrace;
+};
+/**
+ * Per-clause aggregated stats. Mirrors the substrate's `ClauseStats`.
+ */
+export interface ClauseStats {
+    /** Clause label — same string as `ClauseTrace.label`. */
+    label: string;
+    /** Number of candidates that reached this clause (not short-circuited). */
+    evaluated: number;
+    /** Number of those evaluations that returned `true`. */
+    matched: number;
+}
+/**
+ * Wire-format debug report. The `clause_stats` array is sorted by
+ * label (BTreeMap semantics in the substrate); bindings produce that
+ * canonical order.
+ */
+export interface PredicateDebugReport {
+    total_candidates: number;
+    matched: number;
+    clause_stats: ClauseStats[];
+}
+/** Wire-format evaluation context — what `evaluate*` consumes. */
+export interface EvalContextWire {
+    tags: string[];
+    metadata: Record<string, string>;
+}
+/**
+ * Run `pred` against each context in `contexts`, accumulating
+ * per-clause hit / miss stats. Mirrors the substrate's
+ * `PredicateDebugReport::from_evaluations`.
+ *
+ * The returned report's `clause_stats` is sorted by label
+ * (BTreeMap semantics) so bindings produce byte-identical output
+ * for the same input corpus.
+ */
+export declare function predicateDebugReport(pred: Predicate, contexts: readonly EvalContextWire[]): PredicateDebugReport;
+/**
+ * Redact metadata-clause values in a {@link PredicateDebugReport}.
+ *
+ * Walks the report's `clause_stats` and rewrites any label whose
+ * metadata key is in the supplied `keys` list:
+ *
+ * - `MetadataEquals(<key>=<value>)` → `MetadataEquals(<key>=<redacted>)`
+ * - `MetadataMatches(<key> contains "<pattern>")` → `MetadataMatches(<key> contains "<redacted>")`
+ * - `MetadataNumericAtLeast(<key> >= <threshold>)` → `MetadataNumericAtLeast(<key> >= <redacted>)`
+ * - `MetadataExists(<key>)` — unchanged (no value to redact)
+ * - All non-metadata labels (Exists, Equals, Numeric*, Semver*,
+ *   String*, And, Or, Not on tags) unchanged.
+ *
+ * After rewriting, stats with the same redacted label are merged
+ * (`evaluated` and `matched` summed). Output is sorted by label.
+ *
+ * Use this before persisting a debug report to disk or sharing with
+ * a teammate when the predicate's authored metadata values are
+ * sensitive (PII, secrets, internal classifications).
+ *
+ * Pinned across bindings by `predicate_debug_report_redacted.json`.
+ */
+export declare function redactMetadataKeys(report: PredicateDebugReport, keys: readonly string[]): PredicateDebugReport;
+/**
+ * Reconstruct a {@link PredicateDebugReport} from its wire JSON form
+ * (the shape produced by JSON-stringifying the report). Validates
+ * required fields; on malformed input throws a descriptive error.
+ *
+ * Symmetric inverse of `JSON.stringify(report)` — call
+ * `predicateDebugReportFromWire(JSON.parse(text))` to round-trip a
+ * report through disk.
+ */
+export declare function predicateDebugReportFromWire(wire: unknown): PredicateDebugReport;
+/** Render a one-line-per-clause text summary suitable for CLI output. */
+export declare function renderDebugReport(report: PredicateDebugReport): string;