@net-mesh/sdk 0.19.0

package/dist/capability-enhancements.js

@@ -0,0 +1,1324 @@
+"use strict";
+/**
+ * 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
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.StandardPlacementBuilder = exports.RPC_WHERE_HEADER = exports.p = exports.RESERVED_PREFIXES = exports.TAXONOMY_AXES = void 0;
+exports.tagKey = tagKey;
+exports.startsWithReservedPrefix = startsWithReservedPrefix;
+exports.tagToString = tagToString;
+exports.tagFromString = tagFromString;
+exports.tagFromUserString = tagFromUserString;
+exports.predicateToWire = predicateToWire;
+exports.predicateFromWire = predicateFromWire;
+exports.predicateToRpcHeader = predicateToRpcHeader;
+exports.predicateFromRpcHeader = predicateFromRpcHeader;
+exports.whereHeader = whereHeader;
+exports.diffCapabilities = diffCapabilities;
+exports.requireTag = requireTag;
+exports.requireAxisValue = requireAxisValue;
+exports.withMetadata = withMetadata;
+exports.emptyCapabilities = emptyCapabilities;
+exports.standardPlacement = standardPlacement;
+exports.placementFilterFromFn = placementFilterFromFn;
+exports.evaluatePredicate = evaluatePredicate;
+exports.evaluatePredicateWithTrace = evaluatePredicateWithTrace;
+exports.predicateDebugReport = predicateDebugReport;
+exports.redactMetadataKeys = redactMetadataKeys;
+exports.predicateDebugReportFromWire = predicateDebugReportFromWire;
+exports.renderDebugReport = renderDebugReport;
+/** Every axis the substrate knows about. */
+exports.TAXONOMY_AXES = [
+    'hardware',
+    'software',
+    'devices',
+    'dataforts',
+];
+/**
+ * Reserved cross-axis prefixes. Substrate-privileged paths
+ * (`announceChain`, fork-coordination, scope helpers) emit these;
+ * user code calling {@link tagFromUserString} is rejected.
+ */
+exports.RESERVED_PREFIXES = [
+    'causal:',
+    'fork-of:',
+    'heat:',
+    'scope:',
+];
+/**
+ * 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).
+ */
+function tagKey(axis, key) {
+    if (!key) {
+        throw new Error(`tagKey: key must be non-empty (axis=${axis})`);
+    }
+    return { axis, key };
+}
+/** True iff `s` starts with one of the {@link RESERVED_PREFIXES}. */
+function startsWithReservedPrefix(s) {
+    return exports.RESERVED_PREFIXES.find((p) => s.startsWith(p));
+}
+/**
+ * Render a {@link Tag} to its canonical wire string. Matches the
+ * substrate's `Display` impl for `Tag`.
+ */
+function tagToString(tag) {
+    switch (tag.kind) {
+        case 'axisPresent':
+            return `${tag.axis}.${tag.key}`;
+        case 'axisValue':
+            return `${tag.axis}.${tag.key}${tag.separator}${tag.value}`;
+        case 'reserved':
+            return `${tag.prefix}${tag.body}`;
+        case 'legacy':
+            return tag.raw;
+    }
+}
+function axisFromPrefix(prefix) {
+    return exports.TAXONOMY_AXES.includes(prefix)
+        ? prefix
+        : undefined;
+}
+/**
+ * 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.
+ */
+function tagFromString(s) {
+    if (!s) {
+        throw new Error('tagFromString: tag must be non-empty');
+    }
+    const reserved = startsWithReservedPrefix(s);
+    if (reserved !== undefined) {
+        return { kind: 'reserved', prefix: reserved, body: s.slice(reserved.length) };
+    }
+    const dot = s.indexOf('.');
+    if (dot < 0) {
+        return { kind: 'legacy', raw: s };
+    }
+    const axis = axisFromPrefix(s.slice(0, dot));
+    if (!axis) {
+        return { kind: 'legacy', raw: s };
+    }
+    const body = s.slice(dot + 1);
+    if (!body) {
+        return { kind: 'legacy', raw: s };
+    }
+    // Pick the earliest of `=` / `:` so `key=value` wins over a
+    // later `:`. Mirrors the substrate's `parse_axis_body`.
+    const eq = body.indexOf('=');
+    const colon = body.indexOf(':');
+    let sep;
+    let sepIdx = -1;
+    if (eq >= 0 && colon >= 0) {
+        if (eq < colon) {
+            sep = '=';
+            sepIdx = eq;
+        }
+        else {
+            sep = ':';
+            sepIdx = colon;
+        }
+    }
+    else if (eq >= 0) {
+        sep = '=';
+        sepIdx = eq;
+    }
+    else if (colon >= 0) {
+        sep = ':';
+        sepIdx = colon;
+    }
+    if (sep === undefined) {
+        return { kind: 'axisPresent', axis, key: body };
+    }
+    const key = body.slice(0, sepIdx);
+    const value = body.slice(sepIdx + 1);
+    if (!key || !value) {
+        // Empty key or value — fall back to legacy so the substrate's
+        // round-trip stays lossless.
+        return { kind: 'legacy', raw: s };
+    }
+    return { kind: 'axisValue', axis, key, value, separator: sep };
+}
+/**
+ * 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`.
+ */
+function tagFromUserString(s) {
+    if (!s) {
+        throw new Error('tagFromUserString: tag must be non-empty');
+    }
+    const reserved = startsWithReservedPrefix(s);
+    if (reserved !== undefined) {
+        throw new Error(`tag ${JSON.stringify(s)} starts with reserved prefix ${JSON.stringify(reserved)}; user code cannot emit reserved-prefix tags`);
+    }
+    return tagFromString(s);
+}
+/**
+ * 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);
+ * ```
+ */
+exports.p = {
+    exists(key) {
+        return { type: 'exists', key };
+    },
+    equals(key, value) {
+        return { type: 'equals', key, value };
+    },
+    numericAtLeast(key, threshold) {
+        return { type: 'numericAtLeast', key, threshold };
+    },
+    numericAtMost(key, threshold) {
+        return { type: 'numericAtMost', key, threshold };
+    },
+    numericInRange(key, min, max) {
+        return { type: 'numericInRange', key, min, max };
+    },
+    semverAtLeast(key, version) {
+        return { type: 'semverAtLeast', key, version };
+    },
+    semverAtMost(key, version) {
+        return { type: 'semverAtMost', key, version };
+    },
+    semverCompatible(key, version) {
+        return { type: 'semverCompatible', key, version };
+    },
+    stringPrefix(key, prefix) {
+        return { type: 'stringPrefix', key, prefix };
+    },
+    stringMatches(key, pattern) {
+        return { type: 'stringMatches', key, pattern };
+    },
+    metadataExists(key) {
+        return { type: 'metadataExists', key };
+    },
+    metadataEquals(key, value) {
+        return { type: 'metadataEquals', key, value };
+    },
+    metadataMatches(key, pattern) {
+        return { type: 'metadataMatches', key, pattern };
+    },
+    metadataNumericAtLeast(key, threshold) {
+        return { type: 'metadataNumericAtLeast', key, threshold };
+    },
+    and(...children) {
+        return { type: 'and', children };
+    },
+    or(...children) {
+        return { type: 'or', children };
+    },
+    not(child) {
+        return { type: 'not', child };
+    },
+};
+function emit(node, out) {
+    switch (node.type) {
+        case 'exists':
+            out.push({ kind: 'exists', key: node.key });
+            return out.length - 1;
+        case 'equals':
+            out.push({ kind: 'equals', key: node.key, value: node.value });
+            return out.length - 1;
+        case 'numericAtLeast':
+            out.push({
+                kind: 'numeric_at_least',
+                key: node.key,
+                threshold: node.threshold,
+            });
+            return out.length - 1;
+        case 'numericAtMost':
+            out.push({
+                kind: 'numeric_at_most',
+                key: node.key,
+                threshold: node.threshold,
+            });
+            return out.length - 1;
+        case 'numericInRange':
+            out.push({
+                kind: 'numeric_in_range',
+                key: node.key,
+                min: node.min,
+                max: node.max,
+            });
+            return out.length - 1;
+        case 'semverAtLeast':
+            out.push({
+                kind: 'semver_at_least',
+                key: node.key,
+                version: node.version,
+            });
+            return out.length - 1;
+        case 'semverAtMost':
+            out.push({
+                kind: 'semver_at_most',
+                key: node.key,
+                version: node.version,
+            });
+            return out.length - 1;
+        case 'semverCompatible':
+            out.push({
+                kind: 'semver_compatible',
+                key: node.key,
+                version: node.version,
+            });
+            return out.length - 1;
+        case 'stringPrefix':
+            out.push({ kind: 'string_prefix', key: node.key, prefix: node.prefix });
+            return out.length - 1;
+        case 'stringMatches':
+            out.push({
+                kind: 'string_matches',
+                key: node.key,
+                pattern: node.pattern,
+            });
+            return out.length - 1;
+        case 'metadataExists':
+            out.push({ kind: 'metadata_exists', key: node.key });
+            return out.length - 1;
+        case 'metadataEquals':
+            out.push({
+                kind: 'metadata_equals',
+                key: node.key,
+                value: node.value,
+            });
+            return out.length - 1;
+        case 'metadataMatches':
+            out.push({
+                kind: 'metadata_matches',
+                key: node.key,
+                pattern: node.pattern,
+            });
+            return out.length - 1;
+        case 'metadataNumericAtLeast':
+            out.push({
+                kind: 'metadata_numeric_at_least',
+                key: node.key,
+                threshold: node.threshold,
+            });
+            return out.length - 1;
+        case 'and': {
+            const childIdxs = node.children.map((c) => emit(c, out));
+            out.push({ kind: 'and', children: childIdxs });
+            return out.length - 1;
+        }
+        case 'or': {
+            const childIdxs = node.children.map((c) => emit(c, out));
+            out.push({ kind: 'or', children: childIdxs });
+            return out.length - 1;
+        }
+        case 'not': {
+            const childIdx = emit(node.child, out);
+            out.push({ kind: 'not', child: childIdx });
+            return out.length - 1;
+        }
+    }
+}
+/** Flatten an AST into the wire IR. Children always sit at lower
+ * indices than their parents (post-order). */
+function predicateToWire(pred) {
+    const nodes = [];
+    const root_idx = emit(pred, nodes);
+    return { nodes, root_idx };
+}
+/** Inverse of {@link predicateToWire}. Rebuilds the AST from a wire
+ * IR. Throws on out-of-range indices or malformed nodes. */
+function predicateFromWire(wire) {
+    const built = new Array(wire.nodes.length);
+    // Post-order — every child has a strictly smaller index than its
+    // parent, so a left-to-right walk is sufficient.
+    for (let i = 0; i < wire.nodes.length; i++) {
+        const n = wire.nodes[i];
+        built[i] = nodeFromWire(n, built, i);
+    }
+    // Q6: validate root_idx is an integer. Pre-fix only the
+    // numeric range was checked, so a non-integer (e.g. `1.5`,
+    // `NaN`, `Infinity`) would compare against `built.length`,
+    // pass the bounds check, and `built[wire.root_idx]` would
+    // return `undefined` instead of throwing — masking malformed
+    // wire input as a silent missing-root.
+    if (!Number.isInteger(wire.root_idx) ||
+        wire.root_idx < 0 ||
+        wire.root_idx >= built.length) {
+        throw new Error(`predicateFromWire: root_idx ${wire.root_idx} out of range [0, ${built.length})`);
+    }
+    return built[wire.root_idx];
+}
+function nodeFromWire(n, prior, selfIdx) {
+    const checkChild = (idx) => {
+        // Q5: validate `idx` is an integer. Pre-fix only the
+        // numeric range was checked, so a non-integer index in the
+        // child array (e.g. `1.5`, `NaN`) would index `prior` and
+        // return `undefined` — yielding a malformed AST that
+        // crashes on later evaluation rather than failing here at
+        // decode time.
+        if (!Number.isInteger(idx) || idx < 0 || idx >= selfIdx) {
+            throw new Error(`predicateFromWire: child index ${idx} not strictly less than self ${selfIdx}`);
+        }
+        return prior[idx];
+    };
+    switch (n.kind) {
+        case 'exists':
+            return { type: 'exists', key: n.key };
+        case 'equals':
+            return { type: 'equals', key: n.key, value: n.value };
+        case 'numeric_at_least':
+            return { type: 'numericAtLeast', key: n.key, threshold: n.threshold };
+        case 'numeric_at_most':
+            return { type: 'numericAtMost', key: n.key, threshold: n.threshold };
+        case 'numeric_in_range':
+            return {
+                type: 'numericInRange',
+                key: n.key,
+                min: n.min,
+                max: n.max,
+            };
+        case 'semver_at_least':
+            return { type: 'semverAtLeast', key: n.key, version: n.version };
+        case 'semver_at_most':
+            return { type: 'semverAtMost', key: n.key, version: n.version };
+        case 'semver_compatible':
+            return { type: 'semverCompatible', key: n.key, version: n.version };
+        case 'string_prefix':
+            return { type: 'stringPrefix', key: n.key, prefix: n.prefix };
+        case 'string_matches':
+            return { type: 'stringMatches', key: n.key, pattern: n.pattern };
+        case 'metadata_exists':
+            return { type: 'metadataExists', key: n.key };
+        case 'metadata_equals':
+            return { type: 'metadataEquals', key: n.key, value: n.value };
+        case 'metadata_matches':
+            return { type: 'metadataMatches', key: n.key, pattern: n.pattern };
+        case 'metadata_numeric_at_least':
+            return {
+                type: 'metadataNumericAtLeast',
+                key: n.key,
+                threshold: n.threshold,
+            };
+        case 'and':
+            return {
+                type: 'and',
+                children: n.children.map(checkChild),
+            };
+        case 'or':
+            return {
+                type: 'or',
+                children: n.children.map(checkChild),
+            };
+        case 'not':
+            return { type: 'not', child: checkChild(n.child) };
+    }
+}
+// ============================================================================
+// nRPC envelope helpers — mirror `predicate_to_rpc_header` /
+// `predicate_from_rpc_headers` in the substrate.
+// ============================================================================
+/** Header the substrate uses to carry a predicate over nRPC. */
+exports.RPC_WHERE_HEADER = 'net-where';
+/** Encode a predicate into the request-header value. The substrate
+ * pins this as the canonical JSON-encoded {@link PredicateWire}. */
+function predicateToRpcHeader(pred) {
+    return JSON.stringify(predicateToWire(pred));
+}
+/** Decode a `net-where` header value back into an AST. Throws
+ * on malformed JSON or out-of-range indices. */
+function predicateFromRpcHeader(value) {
+    const wire = JSON.parse(value);
+    return predicateFromWire(wire);
+}
+/**
+ * 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`.
+ */
+function whereHeader(pred) {
+    return {
+        name: exports.RPC_WHERE_HEADER,
+        value: Buffer.from(predicateToRpcHeader(pred), 'utf-8'),
+    };
+}
+/**
+ * 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.
+ */
+function diffCapabilities(prev, curr) {
+    // N-3: compare semantically rather than over raw wire strings.
+    // Two `AxisValue` tags differing only in separator form
+    // (`hardware.k=v` vs `hardware.k:v`) carry identical semantics;
+    // the substrate's `CapabilitySet::diff` uses
+    // `Tag::semantic_eq` for exactly this reason (CR-3 fix at
+    // `capability.rs:1395-1414`). A raw set-difference over wire
+    // strings emits phantom Removed+Added pairs whenever a peer
+    // normalizes separator form between announcements.
+    //
+    // Build a semantic key per parsed tag and compare on that. Keep
+    // the original wire string (current side first, falling back to
+    // prev) so the emitted op preserves what the caller actually
+    // sent.
+    const tagSemanticKey = (s) => {
+        const t = tagFromString(s);
+        switch (t.kind) {
+            case 'axisValue':
+                // Drop separator from the key — `=` and `:` are
+                // semantically identical at the wire layer.
+                return `axisValue:${t.axis}.${t.key}=${t.value}`;
+            case 'axisPresent':
+                return `axisPresent:${t.axis}.${t.key}`;
+            case 'reserved':
+                return `reserved:${t.prefix}${t.body}`;
+            case 'legacy':
+                return `legacy:${t.raw}`;
+        }
+    };
+    const prevByKey = new Map();
+    for (const t of prev.tags)
+        prevByKey.set(tagSemanticKey(t), t);
+    const currByKey = new Map();
+    for (const t of curr.tags)
+        currByKey.set(tagSemanticKey(t), t);
+    const added_tags = [];
+    const removed_tags = [];
+    for (const [k, wire] of currByKey) {
+        if (!prevByKey.has(k))
+            added_tags.push(wire);
+    }
+    for (const [k, wire] of prevByKey) {
+        if (!currByKey.has(k))
+            removed_tags.push(wire);
+    }
+    added_tags.sort();
+    removed_tags.sort();
+    const metadata_changes = [];
+    const allKeys = new Set([
+        ...Object.keys(prev.metadata),
+        ...Object.keys(curr.metadata),
+    ]);
+    const sortedKeys = Array.from(allKeys).sort();
+    for (const key of sortedKeys) {
+        const inPrev = Object.prototype.hasOwnProperty.call(prev.metadata, key);
+        const inCurr = Object.prototype.hasOwnProperty.call(curr.metadata, key);
+        if (inPrev && inCurr) {
+            const prev_value = prev.metadata[key];
+            const new_value = curr.metadata[key];
+            if (prev_value !== new_value) {
+                metadata_changes.push({
+                    kind: 'updated',
+                    key,
+                    prev_value,
+                    new_value,
+                });
+            }
+        }
+        else if (inCurr) {
+            metadata_changes.push({
+                kind: 'added',
+                key,
+                value: curr.metadata[key],
+            });
+        }
+        else if (inPrev) {
+            metadata_changes.push({
+                kind: 'removed',
+                key,
+                prev_value: prev.metadata[key],
+            });
+        }
+    }
+    return { added_tags, removed_tags, metadata_changes };
+}
+// ============================================================================
+// Chain composition helpers — `requireTag`, `requireAxisValue`, and
+// metadata setters operating on the wire `{ tags, metadata }` shape.
+//
+// These are the user-facing builders for the typed-tag taxonomy. Each
+// one returns a NEW object — the inputs are not mutated, so chains
+// can be composed left-to-right without aliasing surprises.
+// ============================================================================
+function freshTags(caps) {
+    // Use a Set to keep tag membership unique, then return as a stable
+    // array. Insertion order is preserved unless the tag was already
+    // present.
+    return Array.from(new Set(caps.tags));
+}
+/**
+ * Add an axis-tag (no value) to the wire shape. Idempotent; no-op
+ * if the tag is already present.
+ */
+function requireTag(caps, axis, key) {
+    if (!key) {
+        throw new Error('requireTag: key must be non-empty');
+    }
+    const wire = tagToString({ kind: 'axisPresent', axis, key });
+    const tags = freshTags(caps);
+    if (!tags.includes(wire))
+        tags.push(wire);
+    return { tags, metadata: { ...caps.metadata } };
+}
+/**
+ * Add an axis-value tag (`<axis>.<key>=<value>` by default) to the
+ * wire shape. Idempotent for the exact (axis, key, value, separator)
+ * triple.
+ */
+function requireAxisValue(caps, axis, key, value, separator = '=') {
+    if (!key) {
+        throw new Error('requireAxisValue: key must be non-empty');
+    }
+    if (!value) {
+        throw new Error('requireAxisValue: value must be non-empty');
+    }
+    const wire = tagToString({
+        kind: 'axisValue',
+        axis,
+        key,
+        value,
+        separator,
+    });
+    const tags = freshTags(caps);
+    if (!tags.includes(wire))
+        tags.push(wire);
+    return { tags, metadata: { ...caps.metadata } };
+}
+/** Set / overwrite a metadata entry. */
+function withMetadata(caps, key, value) {
+    if (!key)
+        throw new Error('withMetadata: key must be non-empty');
+    return {
+        tags: [...caps.tags],
+        metadata: { ...caps.metadata, [key]: value },
+    };
+}
+/** Empty wire-format capability set. */
+function emptyCapabilities() {
+    return { tags: [], metadata: {} };
+}
+/**
+ * Builder for {@link StandardPlacement}. Returns a frozen config
+ * object suitable for handing to the runtime.
+ */
+class StandardPlacementBuilder {
+    cfg = {};
+    requireTag(axis, key) {
+        const wire = tagToString({ kind: 'axisPresent', axis, key });
+        this.cfg.requireTags = [...(this.cfg.requireTags ?? []), wire];
+        return this;
+    }
+    requireAxisValue(axis, key, value, separator = '=') {
+        const wire = tagToString({
+            kind: 'axisValue',
+            axis,
+            key,
+            value,
+            separator,
+        });
+        this.cfg.requireTags = [...(this.cfg.requireTags ?? []), wire];
+        return this;
+    }
+    forbidTag(axis, key) {
+        const wire = tagToString({ kind: 'axisPresent', axis, key });
+        this.cfg.forbidTags = [...(this.cfg.forbidTags ?? []), wire];
+        return this;
+    }
+    requireMetadata(key, value) {
+        this.cfg.requireMetadata = { ...(this.cfg.requireMetadata ?? {}), [key]: value };
+        return this;
+    }
+    withPredicate(pred) {
+        this.cfg.predicate = isPredicateWire(pred) ? pred : predicateToWire(pred);
+        return this;
+    }
+    withLimit(n) {
+        if (!Number.isFinite(n) || n < 0) {
+            throw new Error('StandardPlacementBuilder.withLimit: n must be non-negative finite');
+        }
+        this.cfg.limit = Math.floor(n);
+        return this;
+    }
+    withCustomFilterId(id) {
+        if (!id)
+            throw new Error('StandardPlacementBuilder.withCustomFilterId: id must be non-empty');
+        this.cfg.customFilterId = id;
+        return this;
+    }
+    build() {
+        // Defensive copy + freeze. The builder retains its own state so
+        // a chain like `b.build(); b.requireTag(...).build()` works.
+        return Object.freeze({
+            ...this.cfg,
+            requireTags: this.cfg.requireTags
+                ? [...this.cfg.requireTags]
+                : undefined,
+            forbidTags: this.cfg.forbidTags ? [...this.cfg.forbidTags] : undefined,
+            requireMetadata: this.cfg.requireMetadata
+                ? { ...this.cfg.requireMetadata }
+                : undefined,
+            predicate: this.cfg.predicate
+                ? {
+                    nodes: [...this.cfg.predicate.nodes],
+                    root_idx: this.cfg.predicate.root_idx,
+                }
+                : undefined,
+        });
+    }
+}
+exports.StandardPlacementBuilder = StandardPlacementBuilder;
+function isPredicateWire(v) {
+    return (typeof v === 'object' &&
+        v !== null &&
+        Array.isArray(v.nodes) &&
+        typeof v.root_idx === 'number');
+}
+/** Convenience constructor for a {@link StandardPlacementBuilder}. */
+function standardPlacement() {
+    return new StandardPlacementBuilder();
+}
+let placementFilterCounter = 0;
+function placementFilterFromFn(fn, explicitId) {
+    const id = explicitId ?? `pf-${++placementFilterCounter}`;
+    return { id, fn };
+}
+function parseSemver(s) {
+    // Drop pre-release / build suffix.
+    const dash = s.indexOf('-');
+    const plus = s.indexOf('+');
+    let core;
+    if (dash >= 0 && plus >= 0) {
+        core = s.slice(0, Math.min(dash, plus));
+    }
+    else if (dash >= 0) {
+        core = s.slice(0, dash);
+    }
+    else if (plus >= 0) {
+        core = s.slice(0, plus);
+    }
+    else {
+        core = s;
+    }
+    const parts = core.split('.').map((p) => p.trim());
+    if (parts.length === 0 || parts.length > 3)
+        return undefined;
+    const major = Number.parseInt(parts[0], 10);
+    if (!Number.isFinite(major) || parts[0] === '' || /[^0-9]/.test(parts[0])) {
+        return undefined;
+    }
+    const parsePart = (s) => {
+        if (s === undefined)
+            return 0;
+        if (s === '' || /[^0-9]/.test(s))
+            return undefined;
+        const n = Number.parseInt(s, 10);
+        return Number.isFinite(n) ? n : undefined;
+    };
+    const minor = parsePart(parts[1]);
+    const patch = parsePart(parts[2]);
+    if (minor === undefined || patch === undefined)
+        return undefined;
+    return [major, minor, patch];
+}
+function semverCmp(a, b) {
+    if (a[0] !== b[0])
+        return a[0] - b[0];
+    if (a[1] !== b[1])
+        return a[1] - b[1];
+    return a[2] - b[2];
+}
+function semverCompatible(lhs, rhs) {
+    if (semverCmp(lhs, rhs) < 0)
+        return false;
+    if (rhs[0] === 0) {
+        if (rhs[1] === 0) {
+            // P2-F: 0.0.x — patch is the compatibility band; anything
+            // other than the exact tuple is a breaking change. Combined
+            // with the `lhs >= rhs` guard above this collapses to
+            // `lhs === rhs`.
+            return lhs[0] === rhs[0] && lhs[1] === rhs[1] && lhs[2] === rhs[2];
+        }
+        // Q1: 0.x.y — minor is the compatibility band, AND the major
+        // must also be 0. Pre-fix `rhs[1] === lhs[1]` alone admitted
+        // `lhs = 1.2.5` as compatible with `rhs = 0.2.3` (the
+        // `lhs >= rhs` guard passes since 1 > 0, then minors match).
+        // 1.x.y is NOT `^0.2.3`-compatible per Cargo: 0.x.y treats
+        // minor as the band IFF the band itself is 0.x.y.
+        return lhs[0] === 0 && rhs[1] === lhs[1];
+    }
+    return rhs[0] === lhs[0];
+}
+/**
+ * Find the value of an `AxisValue` tag in the wire-format tag list,
+ * if any. Mirrors the substrate's `match_axis_tag`
+ * (`predicate.rs:1749-1757`), which explicitly skips `AxisPresent`
+ * tags for value predicates: feeding `""` through `value_pred` would
+ * let an empty-string `Equals` / `StringPrefix` / `StringMatches`
+ * predicate spuriously match a presence-only tag. Use
+ * {@link axisTagPresent} for the `exists` predicate path.
+ *
+ * Returns the matched value string for AxisValue tags, or
+ * `undefined` if no AxisValue tag matches (including the case where
+ * only an AxisPresent tag for the same key exists).
+ */
+function axisTagValue(tags, key) {
+    const prefix = `${key.axis}.${key.key}`;
+    for (const wire of tags) {
+        // Match `<axis>.<key>=<value>` or `<axis>.<key>:<value>`. Reject
+        // longer key-prefixes (`hardware.gpu` should NOT match
+        // `hardware.gpu.vendor=nvidia` — that's a different key) and
+        // skip the AxisPresent form (`<axis>.<key>` with no separator).
+        if (wire.length <= prefix.length)
+            continue;
+        if (!wire.startsWith(prefix))
+            continue;
+        const sep = wire.charAt(prefix.length);
+        if (sep === '=' || sep === ':') {
+            return wire.slice(prefix.length + 1);
+        }
+    }
+    return undefined;
+}
+/**
+ * Parse a string the way Rust's `f64::from_str` does: accepts
+ * decimal forms (`1`, `1.5`, `.5`, `1.`), scientific notation
+ * (`1e10`, `1.5e-3`), an optional leading `+` or `-`, and the
+ * special-case literals `inf` / `infinity` / `nan` (all
+ * case-insensitive). Rejects empty / whitespace-padded inputs
+ * (Rust's `f64::from_str` is whitespace-strict). Returns `undefined`
+ * when Rust would also reject — letting callers funnel the result
+ * through IEEE comparison so `Inf >= threshold` and
+ * `NaN >= threshold` agree across bindings (matches R1's reasoning
+ * for the Go path).
+ *
+ * N-2: prior shape applied a `/^-?\d+(\.\d+)?$/` regex pre-filter
+ * that rejected scientific notation, leading `+`, `inf`, and `NaN`
+ * — all of which Rust's `f64::from_str` accepts. A tag value
+ * `software.model.context_length=1e6` evaluated `>= 1000000` as
+ * `true` in Rust and `false` in TS pre-fix.
+ */
+function parseRustF64(s) {
+    if (s.length === 0)
+        return undefined;
+    if (s !== s.trim())
+        return undefined;
+    const lower = s.toLowerCase();
+    const stripped = lower.startsWith('+') || lower.startsWith('-') ? lower.slice(1) : lower;
+    if (stripped === 'inf' || stripped === 'infinity') {
+        return lower.startsWith('-') ? -Infinity : Infinity;
+    }
+    if (stripped === 'nan')
+        return Number.NaN;
+    // `Number()` accepts the rest of f64::from_str's grammar (decimal,
+    // scientific, leading `+`/`-`, `.5`, `1.`). It also accepts `""`
+    // and whitespace-only as `0` — both already rejected above. Any
+    // other input that Rust's parse rejects falls through to NaN here
+    // (e.g. `"abc"`, `"1abc"`, `"0x1p3"`).
+    const n = Number(s);
+    return Number.isNaN(n) ? undefined : n;
+}
+/**
+ * Test whether the wire-format tag list carries any tag for `key` —
+ * either an `AxisValue` (`<axis>.<key>=<value>`) or an `AxisPresent`
+ * (`<axis>.<key>`). Mirrors the substrate's `Predicate::Exists` leaf,
+ * which routes through `evaluate_leaf`'s presence-aware path and
+ * accepts both forms.
+ */
+function axisTagPresent(tags, key) {
+    const prefix = `${key.axis}.${key.key}`;
+    for (const wire of tags) {
+        if (wire === prefix)
+            return true;
+        if (wire.length <= prefix.length)
+            continue;
+        if (!wire.startsWith(prefix))
+            continue;
+        const sep = wire.charAt(prefix.length);
+        if (sep === '=' || sep === ':')
+            return true;
+    }
+    return false;
+}
+function evalLeaf(pred, tags, metadata) {
+    switch (pred.type) {
+        case 'exists': {
+            return axisTagPresent(tags, pred.key);
+        }
+        case 'equals': {
+            const v = axisTagValue(tags, pred.key);
+            return v !== undefined && v === pred.value;
+        }
+        case 'numericAtLeast': {
+            const v = axisTagValue(tags, pred.key);
+            if (v === undefined)
+                return false;
+            const n = parseRustF64(v);
+            return n !== undefined && n >= pred.threshold;
+        }
+        case 'numericAtMost': {
+            const v = axisTagValue(tags, pred.key);
+            if (v === undefined)
+                return false;
+            const n = parseRustF64(v);
+            return n !== undefined && n <= pred.threshold;
+        }
+        case 'numericInRange': {
+            const v = axisTagValue(tags, pred.key);
+            if (v === undefined)
+                return false;
+            const n = parseRustF64(v);
+            return n !== undefined && n >= pred.min && n <= pred.max;
+        }
+        case 'semverAtLeast': {
+            const rhs = parseSemver(pred.version);
+            if (rhs === undefined)
+                return false;
+            const v = axisTagValue(tags, pred.key);
+            if (v === undefined)
+                return false;
+            const lhs = parseSemver(v);
+            return lhs !== undefined && semverCmp(lhs, rhs) >= 0;
+        }
+        case 'semverAtMost': {
+            const rhs = parseSemver(pred.version);
+            if (rhs === undefined)
+                return false;
+            const v = axisTagValue(tags, pred.key);
+            if (v === undefined)
+                return false;
+            const lhs = parseSemver(v);
+            return lhs !== undefined && semverCmp(lhs, rhs) <= 0;
+        }
+        case 'semverCompatible': {
+            const rhs = parseSemver(pred.version);
+            if (rhs === undefined)
+                return false;
+            const v = axisTagValue(tags, pred.key);
+            if (v === undefined)
+                return false;
+            const lhs = parseSemver(v);
+            return lhs !== undefined && semverCompatible(lhs, rhs);
+        }
+        case 'stringPrefix': {
+            const v = axisTagValue(tags, pred.key);
+            return v !== undefined && v.startsWith(pred.prefix);
+        }
+        case 'stringMatches': {
+            const v = axisTagValue(tags, pred.key);
+            return v !== undefined && v.includes(pred.pattern);
+        }
+        case 'metadataExists': {
+            return Object.prototype.hasOwnProperty.call(metadata, pred.key);
+        }
+        case 'metadataEquals': {
+            return (Object.prototype.hasOwnProperty.call(metadata, pred.key) &&
+                metadata[pred.key] === pred.value);
+        }
+        case 'metadataMatches': {
+            // `hasOwnProperty` parity with `metadataExists` /
+            // `metadataEquals`. Direct `metadata[pred.key]` access reads
+            // through the prototype chain — a metadata object inheriting
+            // an `Object.prototype` member named the same as `pred.key`
+            // could spuriously match here while `metadataExists` reports
+            // `false`. The two predicates must stay in lockstep.
+            if (!Object.prototype.hasOwnProperty.call(metadata, pred.key))
+                return false;
+            const v = metadata[pred.key];
+            return v !== undefined && v.includes(pred.pattern);
+        }
+        case 'metadataNumericAtLeast': {
+            // Same `hasOwnProperty` parity reasoning as `metadataMatches`.
+            if (!Object.prototype.hasOwnProperty.call(metadata, pred.key))
+                return false;
+            const v = metadata[pred.key];
+            if (v === undefined)
+                return false;
+            const n = parseRustF64(v);
+            return n !== undefined && n >= pred.threshold;
+        }
+        case 'and':
+        case 'or':
+        case 'not':
+            throw new Error(`evalLeaf: composite predicate ${pred.type} routed through leaf evaluator (internal bug)`);
+    }
+}
+/**
+ * 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.
+ */
+function evaluatePredicate(pred, tags, metadata) {
+    switch (pred.type) {
+        case 'and':
+            return pred.children.every((c) => evaluatePredicate(c, tags, metadata));
+        case 'or':
+            return pred.children.some((c) => evaluatePredicate(c, tags, metadata));
+        case 'not':
+            return !evaluatePredicate(pred.child, tags, metadata);
+        default:
+            return evalLeaf(pred, tags, metadata);
+    }
+}
+/**
+ * Static per-variant cost — matches the substrate's `static_cost`.
+ * Lower = cheaper; planner sorts children ascending. Composites sum
+ * their children's costs.
+ */
+function predStaticCost(p) {
+    switch (p.type) {
+        case 'metadataExists':
+            return 10;
+        case 'metadataEquals':
+            return 11;
+        case 'exists':
+            return 20;
+        case 'equals':
+            return 21;
+        case 'metadataNumericAtLeast':
+            return 25;
+        case 'numericAtLeast':
+        case 'numericAtMost':
+        case 'numericInRange':
+            return 30;
+        case 'stringPrefix':
+            return 40;
+        case 'metadataMatches':
+            return 45;
+        case 'stringMatches':
+            return 50;
+        case 'semverAtLeast':
+        case 'semverAtMost':
+        case 'semverCompatible':
+            return 60;
+        case 'and':
+        case 'or':
+            return p.children.reduce((acc, c) => Math.min(acc + predStaticCost(c), 0xffffffff), 0);
+        case 'not':
+            return predStaticCost(p.child);
+    }
+}
+function predDebugLabel(p) {
+    // Rust's `{:?}` on a string adds quotes + escapes. We match that
+    // for string-bearing leaves so labels round-trip with the
+    // substrate's `debug_label`.
+    const dbg = (s) => JSON.stringify(s);
+    const tk = (k) => `${k.axis}.${k.key}`;
+    switch (p.type) {
+        case 'exists':
+            return `Exists(${tk(p.key)})`;
+        case 'equals':
+            return `Equals(${tk(p.key)}=${p.value})`;
+        case 'numericAtLeast':
+            return `NumericAtLeast(${tk(p.key)} >= ${p.threshold})`;
+        case 'numericAtMost':
+            return `NumericAtMost(${tk(p.key)} <= ${p.threshold})`;
+        case 'numericInRange':
+            return `NumericInRange(${tk(p.key)} in [${p.min}, ${p.max}])`;
+        case 'semverAtLeast':
+            return `SemverAtLeast(${tk(p.key)} >= ${p.version})`;
+        case 'semverAtMost':
+            return `SemverAtMost(${tk(p.key)} <= ${p.version})`;
+        case 'semverCompatible':
+            return `SemverCompatible(${tk(p.key)} ~= ${p.version})`;
+        case 'stringPrefix':
+            return `StringPrefix(${tk(p.key)} starts with ${dbg(p.prefix)})`;
+        case 'stringMatches':
+            return `StringMatches(${tk(p.key)} contains ${dbg(p.pattern)})`;
+        case 'metadataExists':
+            return `MetadataExists(${p.key})`;
+        case 'metadataEquals':
+            return `MetadataEquals(${p.key}=${p.value})`;
+        case 'metadataMatches':
+            return `MetadataMatches(${p.key} contains ${dbg(p.pattern)})`;
+        case 'metadataNumericAtLeast':
+            return `MetadataNumericAtLeast(${p.key} >= ${p.threshold})`;
+        case 'and':
+            return `And(${p.children.length} clauses)`;
+        case 'or':
+            return `Or(${p.children.length} clauses)`;
+        case 'not':
+            return 'Not';
+    }
+}
+/**
+ * Stable sort by `static_cost` ascending. Mirrors Rust's
+ * `sort_by_key` (stable). Children with equal cost preserve their
+ * declaration order.
+ */
+function planChildren(children) {
+    const indexed = children.map((c, i) => ({
+        child: c,
+        cost: predStaticCost(c),
+        i,
+    }));
+    indexed.sort((a, b) => a.cost - b.cost || a.i - b.i);
+    return indexed.map((x) => x.child);
+}
+/**
+ * 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.
+ */
+function evaluatePredicateWithTrace(pred, tags, metadata) {
+    const label = predDebugLabel(pred);
+    if (pred.type === 'and') {
+        const ordered = planChildren(pred.children);
+        const traces = [];
+        let result = true;
+        for (const c of ordered) {
+            const { result: r, trace } = evaluatePredicateWithTrace(c, tags, metadata);
+            traces.push(trace);
+            if (!r) {
+                result = false;
+                break;
+            }
+        }
+        return { result, trace: { label, result, children: traces } };
+    }
+    if (pred.type === 'or') {
+        const ordered = planChildren(pred.children);
+        const traces = [];
+        let result = false;
+        for (const c of ordered) {
+            const { result: r, trace } = evaluatePredicateWithTrace(c, tags, metadata);
+            traces.push(trace);
+            if (r) {
+                result = true;
+                break;
+            }
+        }
+        return { result, trace: { label, result, children: traces } };
+    }
+    if (pred.type === 'not') {
+        const { result: r, trace } = evaluatePredicateWithTrace(pred.child, tags, metadata);
+        return {
+            result: !r,
+            trace: { label, result: !r, children: [trace] },
+        };
+    }
+    const r = evalLeaf(pred, tags, metadata);
+    return { result: r, trace: { label, result: r, children: [] } };
+}
+function accumulateTrace(trace, stats) {
+    const entry = stats.get(trace.label) ?? {
+        label: trace.label,
+        evaluated: 0,
+        matched: 0,
+    };
+    entry.evaluated += 1;
+    if (trace.result)
+        entry.matched += 1;
+    stats.set(trace.label, entry);
+    for (const child of trace.children) {
+        accumulateTrace(child, stats);
+    }
+}
+/**
+ * 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.
+ */
+function predicateDebugReport(pred, contexts) {
+    const stats = new Map();
+    let matched = 0;
+    for (const ctx of contexts) {
+        const { result, trace } = evaluatePredicateWithTrace(pred, ctx.tags, ctx.metadata);
+        if (result)
+            matched += 1;
+        accumulateTrace(trace, stats);
+    }
+    const sortedLabels = Array.from(stats.keys()).sort();
+    return {
+        total_candidates: contexts.length,
+        matched,
+        clause_stats: sortedLabels.map((l) => stats.get(l)),
+    };
+}
+/**
+ * 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`.
+ */
+function redactMetadataKeys(report, keys) {
+    const keySet = new Set(keys);
+    const merged = new Map();
+    for (const stat of report.clause_stats) {
+        const newLabel = redactLabel(stat.label, keySet);
+        const existing = merged.get(newLabel) ?? {
+            label: newLabel,
+            evaluated: 0,
+            matched: 0,
+        };
+        existing.evaluated += stat.evaluated;
+        existing.matched += stat.matched;
+        merged.set(newLabel, existing);
+    }
+    const sortedLabels = Array.from(merged.keys()).sort();
+    return {
+        total_candidates: report.total_candidates,
+        matched: report.matched,
+        clause_stats: sortedLabels.map((l) => merged.get(l)),
+    };
+}
+/**
+ * Pre-compiled regexes for the three redactable metadata-clause
+ * label shapes. The `^` / `$` anchors prevent accidental matches in
+ * pathological clause values.
+ */
+const META_EQUALS_RE = /^MetadataEquals\(([^=]+)=(.+)\)$/;
+const META_MATCHES_RE = /^MetadataMatches\((.+) contains "(.*)"\)$/;
+const META_NUMERIC_RE = /^MetadataNumericAtLeast\((.+) >= (.+)\)$/;
+function redactLabel(label, keys) {
+    let m;
+    if ((m = label.match(META_EQUALS_RE))) {
+        if (keys.has(m[1]))
+            return `MetadataEquals(${m[1]}=<redacted>)`;
+    }
+    else if ((m = label.match(META_MATCHES_RE))) {
+        if (keys.has(m[1]))
+            return `MetadataMatches(${m[1]} contains "<redacted>")`;
+    }
+    else if ((m = label.match(META_NUMERIC_RE))) {
+        if (keys.has(m[1]))
+            return `MetadataNumericAtLeast(${m[1]} >= <redacted>)`;
+    }
+    return label;
+}
+/**
+ * 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.
+ */
+function predicateDebugReportFromWire(wire) {
+    if (typeof wire !== 'object' ||
+        wire === null ||
+        typeof wire.total_candidates !== 'number' ||
+        typeof wire.matched !== 'number' ||
+        !Array.isArray(wire.clause_stats)) {
+        throw new Error('predicateDebugReportFromWire: expected { total_candidates: number, matched: number, clause_stats: array }');
+    }
+    const w = wire;
+    for (const s of w.clause_stats) {
+        if (typeof s.label !== 'string' ||
+            typeof s.evaluated !== 'number' ||
+            typeof s.matched !== 'number') {
+            throw new Error(`predicateDebugReportFromWire: bad clause_stats entry ${JSON.stringify(s)}`);
+        }
+    }
+    return {
+        total_candidates: w.total_candidates,
+        matched: w.matched,
+        clause_stats: w.clause_stats.map((s) => ({
+            label: s.label,
+            evaluated: s.evaluated,
+            matched: s.matched,
+        })),
+    };
+}
+/** Render a one-line-per-clause text summary suitable for CLI output. */
+function renderDebugReport(report) {
+    const pct = (num, denom) => denom === 0 ? '0.0%' : `${((100 * num) / denom).toFixed(1)}%`;
+    const lines = [];
+    lines.push('Predicate evaluation report');
+    lines.push('─────────────────────────────────────────');
+    lines.push(`Total candidates: ${report.total_candidates}`);
+    lines.push(`Matched:          ${report.matched} (${pct(report.matched, report.total_candidates)})`);
+    lines.push('');
+    lines.push('Per-clause stats (alphabetical):');
+    for (const s of report.clause_stats) {
+        lines.push(`  ${s.label.padEnd(60)} evaluated ${String(s.evaluated).padStart(5)}, ` +
+            `matched ${String(s.matched).padStart(5)} (${pct(s.matched, s.evaluated)})`);
+    }
+    return lines.join('\n') + '\n';
+}