@lensmcp/cluster 1.0.0

package/executors/gateway/manifest.d.ts

@@ -0,0 +1,275 @@
+/**
+ * Route manifests + the provider seams that make the gateway ONE library
+ * across dev and prod.
+ *
+ * The dev gateway and the production gateway share this routing core. A
+ * service DESCRIBES itself with a `RouteManifest` (in dev, synthesized from
+ * the project.json `cluster` field; in prod, published by the service to a
+ * registry / served at `/.well-known/lensmcp-routes`). The gateway builds a
+ * flat `Route[]` from the manifests and matches requests against it — the
+ * SAME `matchRoute` in both environments, so routing can never drift.
+ *
+ * What differs between dev and prod is supplied through two interfaces:
+ *   - ManifestProvider — WHERE the manifests come from (workspace scan vs
+ *     registry watch) and how changes arrive.
+ *   - PodProvider — HOW a service name resolves to a concrete upstream
+ *     (unix-socket pool with scale-from-zero vs a TCP endpoint).
+ *
+ * This module is PURE (no IO, no process, no http) so it is exhaustively
+ * unit-testable; the providers carry the environment-specific machinery.
+ */
+/** A host[+path] a service is mounted at (e.g. `api.tetros.ai` + `/crm`). */
+export interface RouteMount {
+    host: string;
+    /** Path prefix under the host; omit for the host root. */
+    path?: string;
+}
+/** How the edge guards a route. `jwt` runs the configured authenticator
+ *  (dev middleware seam / prod JWKS); `internal` requires a valid x-api-key;
+ *  `public` is unguarded. */
+export type AuthMode = 'jwt' | 'public' | 'internal';
+/**
+ * A per-path auth refinement. `mode` overrides the service default for paths under
+ * `path` (longest / first match wins — callers emit most-specific-first). For `jwt`
+ * paths an optional ABAC requirement gates the request at the edge:
+ *   - `permission` is sugar for "the verified token's `perms` claim contains it"
+ *     (→ `{ attr:'perms', op:'contains', value }`).
+ *   - `rule` is the full predicate over the request {@link Attrs} (verified claims + ip/headers).
+ *   - `methods` scopes the override to specific HTTP methods — permissions are per-handler
+ *     (POST needs `campaigns.write`, GET needs `campaigns.read`). Omit = all methods.
+ * (`RuleNode`/`Attrs` are declared with the targeting engine below.)
+ */
+export interface AuthOverride {
+    path: string;
+    mode: AuthMode;
+    methods?: string[];
+    permission?: string;
+    rule?: RuleNode;
+}
+export interface AuthPolicy {
+    default?: AuthMode;
+    overrides?: AuthOverride[];
+}
+/** Per-route rate limit (carried on the manifest; enforced by the prod
+ *  provider's Redis token buckets — the core just transports it). */
+export interface RateLimit {
+    /** Path prefix this limit applies to; omit for the whole service. */
+    path?: string;
+    /** Bucket key dimension, e.g. `ip` | `tenant` | `user`. */
+    key: string;
+    points: number;
+    duration: number;
+}
+/**
+ * A service's self-description — the canonical thing the gateway routes from.
+ * In dev this is synthesized from project.json; in prod the service publishes
+ * it. One manifest per service, with one or more mounts.
+ */
+export interface RouteManifest {
+    service: string;
+    /** Build/image version — lets a gateway log/track which manifest it serves. */
+    version?: string;
+    mounts: RouteMount[];
+    /** Default auth for the service + per-path overrides (incl. edge permission rules). */
+    auth?: AuthPolicy;
+    /** Expose `internal.<host>` (east-west, x-api-key) for this service. */
+    internal?: boolean;
+    /** Override the auto `internal.<host>` name, or `false` to disable it. */
+    internalHost?: string | false;
+    /** This service is the catch-all for unclaimed hostnames. */
+    default?: boolean;
+    /** Rewrite forwarded URLs (e.g. mount at root in dev, `/api` downstream). */
+    prependPrefix?: string;
+    /** TCP upstream URL (apps/vite, or a prod service addressed directly).
+     *  When absent, the PodProvider resolves `service` to an upstream. */
+    upstream?: string;
+    rateLimits?: RateLimit[];
+}
+/** Where a request is forwarded: a unix socket (dev pods) or a TCP url.
+ *  `version` (when set) is the rollout cohort that served it — surfaced on the
+ *  trace + `x-lensmcp-version` so a canary's traffic is visible. */
+export type Upstream = ({
+    socketPath: string;
+} | {
+    url: string;
+}) & {
+    version?: string;
+};
+/** A discovered version of a service + the endpoints serving it. The unit of
+ *  progressive rollout: weights across cohorts split traffic (canary 90/10,
+ *  blue/green 0→100). */
+export interface VersionCohort {
+    version: string;
+    /** Relative traffic share. 0 = drain (receive no new traffic). */
+    weight: number;
+    urls: string[];
+}
+/** Supplies + watches the manifest source. */
+export interface ManifestProvider {
+    /** The current manifests (synchronously). */
+    list(): RouteManifest[];
+    /** Subscribe to changes; returns an unsubscribe. Optional (static sources). */
+    watch?(cb: (manifests: RouteManifest[]) => void): () => void;
+}
+/** Resolves a service to a concrete upstream, with optional scale-from-zero. */
+export interface PodProvider {
+    /** Pick an upstream for this service. `opts.version` pins a rollout cohort
+     *  (sticky canary / debugging); otherwise traffic is split by cohort weight. */
+    pick(service: string, opts?: {
+        version?: string;
+    }): Upstream | undefined;
+    /** Bring a scaled-to-zero service up (dev). Prod returns true (always on). */
+    ensureUp?(service: string): Promise<boolean>;
+    /** Drop a dead upstream so the next pick avoids it (refused socket / 502). */
+    drop?(service: string, upstream: Upstream): void;
+    /** Evaluate this service's targeting rules against a request's attributes;
+     *  the first matching rule's version (sticky-by-attribute). */
+    resolveVersion?(service: string, attrs: Attrs): {
+        version: string;
+        rule?: string;
+    } | undefined;
+    /** Consistent-hash a stable device/user key to a cohort version — the
+     *  sticky weighted split (same key → same version across requests + ramps). */
+    bucket?(service: string, key: string): {
+        version: string;
+    } | undefined;
+}
+/**
+ * Smooth weighted round-robin (nginx-style). Returns a stateful selector that,
+ * over time, hands out indices in proportion to `weights` — but INTERLEAVED
+ * (90/10 yields the rare cohort roughly every tenth pick, not in a burst at
+ * the end). Deterministic given the weights, so rollout splits are testable.
+ * A zero/negative total (all cohorts drained) falls back to index 0.
+ */
+export declare function smoothWeightedSelector(weights: readonly number[]): () => number;
+/** A flat routing entry built from manifests — provider-agnostic. The pod
+ *  resolution happens at request time via the PodProvider, keyed by `service`. */
+export interface Route {
+    service: string;
+    host?: string;
+    prefix?: string;
+    prependPrefix?: string;
+    internal?: boolean;
+    default?: boolean;
+    /** Direct TCP upstream (app/vite/prod-direct) — bypasses pod resolution. */
+    upstream?: string;
+    /** Resolved auth for the route root (overrides refine per-path at match). */
+    auth: AuthMode;
+}
+/** Exact hostname or `*.suffix` wildcard (the bare suffix also matches). */
+export declare function hostMatches(pattern: string, host: string): boolean;
+/**
+ * THE matcher — shared by dev and prod. Generic over the route shape so the
+ * dev gateway can pass its pod-rich routes and prod its upstream routes; only
+ * `host`/`prefix` are read here.
+ *
+ * Rules (each one a fixed bug):
+ *  - A host CLAIMED by any declaration never falls through to the catch-all
+ *    default; its unmatched paths belong to the gateway's own infra.
+ *  - An UNCLAIMED host may only reach the host-less `default` route — never a
+ *    host route by accident of sort order (unknown host → default or 404).
+ *  - An EXACT host match beats a wildcard (`internal.api.x` is served by its
+ *    own route, not a co-existing `*.x` app).
+ *  - Within the candidates, the most specific path prefix wins (callers sort
+ *    routes by specificity: host+path before host before catch-all).
+ */
+export declare function matchRoute<R extends {
+    host?: string;
+    prefix?: string;
+}>(routes: readonly R[], host: string, url: string): R | undefined;
+/** Specificity sort: host+path beats host-only beats catch-all. Mutates+returns. */
+export declare function sortBySpecificity<R extends {
+    host?: string;
+    prefix?: string;
+}>(routes: R[]): R[];
+/** Resolve the auth mode for a concrete request path against a manifest. */
+export declare function authForPath(manifest: RouteManifest, path: string, internal: boolean): AuthMode;
+/** The auth mode for a request + the ABAC predicate (if any) to enforce at the edge. */
+export interface ResolvedAuth {
+    mode: AuthMode;
+    rule?: RuleNode;
+}
+/**
+ * Resolve the auth mode + any edge ABAC rule for a concrete (path, method) against an
+ * {@link AuthPolicy} — the shared core both gateways use. First override whose `path` is a
+ * prefix and whose `methods` include the method wins (callers emit most-specific-first);
+ * `permission` is compiled to a `perms contains` condition.
+ */
+/**
+ * Segment-prefix match where a pattern segment of `*` or `:param` matches ANY one path segment —
+ * so a route override like `/engage/tenants/:companyId/campaigns` matches the real request
+ * `/engage/tenants/abc-123/campaigns` (and anything deeper). Stricter than `startsWith` (it won't
+ * cross a segment boundary), which is also more correct. Lets `@RequirePermission` enforce on
+ * tenant-scoped (`:param`) routes, not just static prefixes.
+ */
+export declare function authPathMatches(pattern: string, path: string): boolean;
+export declare function authRuleFor(policy: AuthPolicy | undefined, path: string, method: string): ResolvedAuth;
+/**
+ * Resolve the auth mode AND any edge ABAC rule for a concrete (path, method) on a manifest —
+ * the permission-aware companion to {@link authForPath}. Internal routes are always `internal`;
+ * otherwise delegates to {@link authRuleFor}. The gateway verifies the JWT for `jwt` mode and,
+ * when a `rule` is present, requires `evalRule(rule, attrs)` (else 403).
+ */
+export declare function authRuleForPath(manifest: RouteManifest, path: string, method: string, internal: boolean): ResolvedAuth;
+/**
+ * Build the flat route table from manifests. Each mount becomes a host route;
+ * a service flagged `internal` also gets an `internal.<host>` route per mount;
+ * a `default` service contributes the host-less catch-all. Sorted by
+ * specificity so `matchRoute` picks the most specific.
+ */
+export declare function buildRouteTable(manifests: readonly RouteManifest[]): Route[];
+/** Synthesize a manifest from a dev project.json `cluster` declaration —
+ *  the dev ManifestProvider's adapter, and the seed for `lensmcp`-generated
+ *  prod manifests (same fields, prod adds version/rateLimits). */
+export declare function manifestFromClusterDecl(project: string, decl: {
+    host?: string;
+    path?: string;
+    service?: string;
+    upstream?: string;
+    port?: number;
+    prependPrefix?: string;
+    default?: boolean;
+    internalHost?: string | false;
+    auth?: AuthPolicy;
+}): RouteManifest | undefined;
+/** A flat, read-only attribute bag assembled per request: verified JWT claims,
+ *  `ip`, `header.<name>`, `device` (sticky key), `path`, `method`. */
+export type Attrs = Record<string, unknown>;
+export type RuleOp = 'eq' | 'ne' | 'in' | 'nin' | 'prefix' | 'suffix' | 'contains' | 'regex' | 'exists' | 'gt' | 'lt' | 'cidr';
+export interface Condition {
+    attr: string;
+    op: RuleOp;
+    value?: unknown;
+}
+export interface RuleGroup {
+    all?: RuleNode[];
+    any?: RuleNode[];
+    not?: RuleNode;
+}
+export type RuleNode = Condition | RuleGroup;
+/** A targeting rule: when the predicate matches the request attributes, pin `version`. */
+export interface TargetRule {
+    name?: string;
+    when: RuleNode;
+    version: string;
+}
+/** `ip ∈ cidr` for IPv4 (handles IPv4-mapped IPv6). False for IPv6/malformed. */
+export declare function matchCidr(ip: string, cidr: string): boolean;
+/** Evaluate a rule node (condition or all/any/not group) against attributes. Pure. */
+export declare function evalRule(node: RuleNode, attrs: Attrs): boolean;
+/** First matching rule's version (top-to-bottom), or undefined. */
+export declare function pickTargetedVersion(rules: readonly TargetRule[], attrs: Attrs): {
+    version: string;
+    rule?: string;
+} | undefined;
+/** 32-bit FNV-1a hash → unsigned int. Stable across processes (no seed). */
+export declare function fnv1a(s: string): number;
+/**
+ * Consistent-hash a stable key to a cohort INDEX by weight. The hash point uses
+ * a FIXED modulus (10000) so it is stable per key regardless of the weights;
+ * only the cohort thresholds move when weights change — so ramping a weight
+ * moves a key across the boundary AT MOST ONCE (no reshuffle/flapping). Fixed
+ * cohort order. All-zero weights → 0.
+ */
+export declare function bucketByWeight(key: string, weights: readonly number[]): number;
+//# sourceMappingURL=manifest.d.ts.map

package/executors/gateway/manifest.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"manifest.d.ts","sourceRoot":"","sources":["../../../../../libs/cluster/src/executors/gateway/manifest.ts"],"names":[],"mappings":"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"}

package/executors/gateway/manifest.js

@@ -0,0 +1,344 @@
+"use strict";
+/**
+ * Route manifests + the provider seams that make the gateway ONE library
+ * across dev and prod.
+ *
+ * The dev gateway and the production gateway share this routing core. A
+ * service DESCRIBES itself with a `RouteManifest` (in dev, synthesized from
+ * the project.json `cluster` field; in prod, published by the service to a
+ * registry / served at `/.well-known/lensmcp-routes`). The gateway builds a
+ * flat `Route[]` from the manifests and matches requests against it — the
+ * SAME `matchRoute` in both environments, so routing can never drift.
+ *
+ * What differs between dev and prod is supplied through two interfaces:
+ *   - ManifestProvider — WHERE the manifests come from (workspace scan vs
+ *     registry watch) and how changes arrive.
+ *   - PodProvider — HOW a service name resolves to a concrete upstream
+ *     (unix-socket pool with scale-from-zero vs a TCP endpoint).
+ *
+ * This module is PURE (no IO, no process, no http) so it is exhaustively
+ * unit-testable; the providers carry the environment-specific machinery.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.smoothWeightedSelector = smoothWeightedSelector;
+exports.hostMatches = hostMatches;
+exports.matchRoute = matchRoute;
+exports.sortBySpecificity = sortBySpecificity;
+exports.authForPath = authForPath;
+exports.authPathMatches = authPathMatches;
+exports.authRuleFor = authRuleFor;
+exports.authRuleForPath = authRuleForPath;
+exports.buildRouteTable = buildRouteTable;
+exports.manifestFromClusterDecl = manifestFromClusterDecl;
+exports.matchCidr = matchCidr;
+exports.evalRule = evalRule;
+exports.pickTargetedVersion = pickTargetedVersion;
+exports.fnv1a = fnv1a;
+exports.bucketByWeight = bucketByWeight;
+/**
+ * Smooth weighted round-robin (nginx-style). Returns a stateful selector that,
+ * over time, hands out indices in proportion to `weights` — but INTERLEAVED
+ * (90/10 yields the rare cohort roughly every tenth pick, not in a burst at
+ * the end). Deterministic given the weights, so rollout splits are testable.
+ * A zero/negative total (all cohorts drained) falls back to index 0.
+ */
+function smoothWeightedSelector(weights) {
+    const cur = weights.map(() => 0);
+    const total = weights.reduce((s, w) => s + Math.max(0, w), 0);
+    return () => {
+        if (total <= 0 || weights.length === 0)
+            return 0;
+        let best = 0;
+        for (let i = 0; i < weights.length; i++) {
+            cur[i] += Math.max(0, weights[i]);
+            if (cur[i] > cur[best])
+                best = i;
+        }
+        cur[best] -= total;
+        return best;
+    };
+}
+/** Exact hostname or `*.suffix` wildcard (the bare suffix also matches). */
+function hostMatches(pattern, host) {
+    return pattern.startsWith('*.')
+        ? host.endsWith(pattern.slice(1)) || host === pattern.slice(2)
+        : host === pattern;
+}
+/**
+ * THE matcher — shared by dev and prod. Generic over the route shape so the
+ * dev gateway can pass its pod-rich routes and prod its upstream routes; only
+ * `host`/`prefix` are read here.
+ *
+ * Rules (each one a fixed bug):
+ *  - A host CLAIMED by any declaration never falls through to the catch-all
+ *    default; its unmatched paths belong to the gateway's own infra.
+ *  - An UNCLAIMED host may only reach the host-less `default` route — never a
+ *    host route by accident of sort order (unknown host → default or 404).
+ *  - An EXACT host match beats a wildcard (`internal.api.x` is served by its
+ *    own route, not a co-existing `*.x` app).
+ *  - Within the candidates, the most specific path prefix wins (callers sort
+ *    routes by specificity: host+path before host before catch-all).
+ */
+function matchRoute(routes, host, url) {
+    const claimed = routes.some((r) => r.host && hostMatches(r.host, host));
+    let candidates = claimed
+        ? routes.filter((r) => r.host && hostMatches(r.host, host))
+        : routes.filter((r) => !r.host);
+    if (candidates.some((r) => r.host === host)) {
+        candidates = candidates.filter((r) => r.host === host);
+    }
+    return candidates.find((r) => !r.prefix || url.startsWith(r.prefix));
+}
+/** Specificity sort: host+path beats host-only beats catch-all. Mutates+returns. */
+function sortBySpecificity(routes) {
+    routes.sort((a, b) => ((b.host ? 2 : 0) + (b.prefix ? 1 : 0)) - ((a.host ? 2 : 0) + (a.prefix ? 1 : 0)));
+    return routes;
+}
+/** Resolve the auth mode for a concrete request path against a manifest. */
+function authForPath(manifest, path, internal) {
+    if (internal)
+        return 'internal';
+    const overrides = manifest.auth?.overrides ?? [];
+    for (const o of overrides)
+        if (path.startsWith(o.path))
+            return o.mode;
+    return manifest.auth?.default ?? 'jwt';
+}
+/**
+ * Resolve the auth mode + any edge ABAC rule for a concrete (path, method) against an
+ * {@link AuthPolicy} — the shared core both gateways use. First override whose `path` is a
+ * prefix and whose `methods` include the method wins (callers emit most-specific-first);
+ * `permission` is compiled to a `perms contains` condition.
+ */
+/**
+ * Segment-prefix match where a pattern segment of `*` or `:param` matches ANY one path segment —
+ * so a route override like `/engage/tenants/:companyId/campaigns` matches the real request
+ * `/engage/tenants/abc-123/campaigns` (and anything deeper). Stricter than `startsWith` (it won't
+ * cross a segment boundary), which is also more correct. Lets `@RequirePermission` enforce on
+ * tenant-scoped (`:param`) routes, not just static prefixes.
+ */
+function authPathMatches(pattern, path) {
+    const ps = pattern.split('/').filter(Boolean);
+    const xs = (path.split('?')[0] ?? '').split('/').filter(Boolean);
+    if (xs.length < ps.length)
+        return false;
+    for (let i = 0; i < ps.length; i++) {
+        const seg = ps[i];
+        if (seg === '*' || seg.startsWith(':'))
+            continue;
+        if (seg !== xs[i])
+            return false;
+    }
+    return true;
+}
+function authRuleFor(policy, path, method) {
+    const m = method.toUpperCase();
+    for (const o of policy?.overrides ?? []) {
+        if (!authPathMatches(o.path, path))
+            continue;
+        if (o.methods && !o.methods.some((x) => x.toUpperCase() === m))
+            continue;
+        const rule = o.rule ?? (o.permission ? { attr: 'perms', op: 'contains', value: o.permission } : undefined);
+        return { mode: o.mode, ...(rule ? { rule } : {}) };
+    }
+    return { mode: policy?.default ?? 'jwt' };
+}
+/**
+ * Resolve the auth mode AND any edge ABAC rule for a concrete (path, method) on a manifest —
+ * the permission-aware companion to {@link authForPath}. Internal routes are always `internal`;
+ * otherwise delegates to {@link authRuleFor}. The gateway verifies the JWT for `jwt` mode and,
+ * when a `rule` is present, requires `evalRule(rule, attrs)` (else 403).
+ */
+function authRuleForPath(manifest, path, method, internal) {
+    if (internal)
+        return { mode: 'internal' };
+    return authRuleFor(manifest.auth, path, method);
+}
+/**
+ * Build the flat route table from manifests. Each mount becomes a host route;
+ * a service flagged `internal` also gets an `internal.<host>` route per mount;
+ * a `default` service contributes the host-less catch-all. Sorted by
+ * specificity so `matchRoute` picks the most specific.
+ */
+function buildRouteTable(manifests) {
+    const routes = [];
+    for (const m of manifests) {
+        const baseAuth = m.auth?.default ?? 'jwt';
+        for (const mount of m.mounts) {
+            const base = {
+                service: m.service,
+                ...(mount.path ? { prefix: mount.path } : {}),
+                ...(m.prependPrefix ? { prependPrefix: m.prependPrefix } : {}),
+                ...(m.upstream ? { upstream: m.upstream } : {}),
+            };
+            routes.push({ ...base, host: mount.host, auth: baseAuth });
+            if (m.internal && m.internalHost !== false) {
+                routes.push({
+                    ...base,
+                    host: typeof m.internalHost === 'string' ? m.internalHost : `internal.${mount.host}`,
+                    internal: true,
+                    auth: 'internal',
+                });
+            }
+        }
+        if (m.default) {
+            routes.push({
+                service: m.service,
+                ...(m.prependPrefix ? { prependPrefix: m.prependPrefix } : {}),
+                ...(m.upstream ? { upstream: m.upstream } : {}),
+                default: true,
+                auth: baseAuth,
+            });
+        }
+    }
+    return sortBySpecificity(routes);
+}
+/** Synthesize a manifest from a dev project.json `cluster` declaration —
+ *  the dev ManifestProvider's adapter, and the seed for `lensmcp`-generated
+ *  prod manifests (same fields, prod adds version/rateLimits). */
+function manifestFromClusterDecl(project, decl) {
+    const upstream = decl.upstream ?? (decl.port ? `http://localhost:${decl.port}` : undefined);
+    // A service must route SOMEWHERE: either a pod service name or a TCP upstream.
+    if (!decl.service && !upstream)
+        return undefined;
+    return {
+        service: decl.service ?? project,
+        mounts: decl.host ? [{ host: decl.host, ...(decl.path ? { path: decl.path } : {}) }] : [],
+        // pod services get an internal east-west host by default; TCP upstreams don't.
+        internal: !!decl.service,
+        ...(decl.internalHost !== undefined ? { internalHost: decl.internalHost } : {}),
+        ...(decl.default ? { default: true } : {}),
+        ...(decl.prependPrefix ? { prependPrefix: decl.prependPrefix } : {}),
+        ...(decl.auth ? { auth: decl.auth } : {}),
+        ...(upstream ? { upstream } : {}),
+    };
+}
+const isGroup = (n) => 'all' in n || 'any' in n || 'not' in n;
+const reCache = new Map();
+const compileRe = (src) => {
+    if (src.length > 512)
+        return null; // ReDoS guard — bound pattern length
+    if (reCache.has(src))
+        return reCache.get(src);
+    let re;
+    try {
+        re = new RegExp(src);
+    }
+    catch {
+        re = null;
+    }
+    reCache.set(src, re);
+    return re;
+};
+/** IPv4 dotted-quad → uint32, or null if malformed. */
+function ipToInt(ip) {
+    const v4 = ip.startsWith('::ffff:') ? ip.slice(7) : ip; // IPv4-mapped IPv6
+    const parts = v4.split('.');
+    if (parts.length !== 4)
+        return null;
+    let n = 0;
+    for (const p of parts) {
+        const o = Number(p);
+        if (!Number.isInteger(o) || o < 0 || o > 255 || (p.length > 1 && p[0] === '0'))
+            return null;
+        n = n * 256 + o;
+    }
+    return n >>> 0;
+}
+/** `ip ∈ cidr` for IPv4 (handles IPv4-mapped IPv6). False for IPv6/malformed. */
+function matchCidr(ip, cidr) {
+    const slash = cidr.indexOf('/');
+    if (slash < 0)
+        return false;
+    const bits = Number(cidr.slice(slash + 1));
+    if (!Number.isInteger(bits) || bits < 0 || bits > 32)
+        return false;
+    const ipN = ipToInt(ip);
+    const rangeN = ipToInt(cidr.slice(0, slash));
+    if (ipN === null || rangeN === null)
+        return false;
+    if (bits === 0)
+        return true;
+    const mask = (bits === 32 ? 0xffffffff : ~((1 << (32 - bits)) - 1)) >>> 0;
+    return ((ipN & mask) >>> 0) === ((rangeN & mask) >>> 0);
+}
+const str = (v) => (v === null || v === undefined ? '' : String(v));
+const eq = (a, b) => str(a) === str(b);
+/** Evaluate one condition against the attributes. Undefined attribute → false
+ *  for every op except `ne` (absent ≠ value → true) and `exists` (→ false). */
+function evalCondition(c, attrs) {
+    const v = attrs[c.attr];
+    const present = v !== undefined && v !== null;
+    switch (c.op) {
+        case 'exists': return present;
+        case 'ne': return !present || !eq(v, c.value);
+    }
+    if (!present)
+        return false;
+    switch (c.op) {
+        case 'eq': return eq(v, c.value);
+        case 'in': return Array.isArray(c.value) && c.value.some((x) => Array.isArray(v) ? v.some((vv) => eq(vv, x)) : eq(v, x));
+        case 'nin': return !(Array.isArray(c.value) && c.value.some((x) => Array.isArray(v) ? v.some((vv) => eq(vv, x)) : eq(v, x)));
+        case 'prefix': return str(v).startsWith(str(c.value));
+        case 'suffix': return str(v).endsWith(str(c.value));
+        case 'contains': return Array.isArray(v) ? v.some((vv) => eq(vv, c.value)) : str(v).includes(str(c.value));
+        case 'regex': {
+            const re = compileRe(str(c.value));
+            return re ? re.test(str(v)) : false;
+        }
+        case 'gt': return Number(v) > Number(c.value);
+        case 'lt': return Number(v) < Number(c.value);
+        case 'cidr': return matchCidr(str(v), str(c.value));
+        default: return false;
+    }
+}
+/** Evaluate a rule node (condition or all/any/not group) against attributes. Pure. */
+function evalRule(node, attrs) {
+    if (!isGroup(node))
+        return evalCondition(node, attrs);
+    if (node.all && !node.all.every((n) => evalRule(n, attrs)))
+        return false;
+    if (node.any && !node.any.some((n) => evalRule(n, attrs)))
+        return false;
+    if (node.not && evalRule(node.not, attrs))
+        return false;
+    // an empty group ({}) matches nothing meaningful → treat as no-match
+    return !!(node.all || node.any || node.not);
+}
+/** First matching rule's version (top-to-bottom), or undefined. */
+function pickTargetedVersion(rules, attrs) {
+    for (const r of rules) {
+        if (evalRule(r.when, attrs))
+            return { version: r.version, ...(r.name ? { rule: r.name } : {}) };
+    }
+    return undefined;
+}
+/** 32-bit FNV-1a hash → unsigned int. Stable across processes (no seed). */
+function fnv1a(s) {
+    let h = 0x811c9dc5;
+    for (let i = 0; i < s.length; i++) {
+        h ^= s.charCodeAt(i);
+        h = Math.imul(h, 0x01000193);
+    }
+    return h >>> 0;
+}
+/**
+ * Consistent-hash a stable key to a cohort INDEX by weight. The hash point uses
+ * a FIXED modulus (10000) so it is stable per key regardless of the weights;
+ * only the cohort thresholds move when weights change — so ramping a weight
+ * moves a key across the boundary AT MOST ONCE (no reshuffle/flapping). Fixed
+ * cohort order. All-zero weights → 0.
+ */
+function bucketByWeight(key, weights) {
+    const total = weights.reduce((a, w) => a + Math.max(0, w), 0);
+    if (total <= 0 || weights.length === 0)
+        return 0;
+    const point = fnv1a(key) % 10000;
+    let acc = 0;
+    for (let i = 0; i < weights.length; i++) {
+        acc += (Math.max(0, weights[i]) / total) * 10000;
+        if (point < acc)
+            return i;
+    }
+    return weights.length - 1;
+}