@mikrojs/native 0.18.2 → 0.18.3-next.20260829153835

package/dist/runtime/schema/shared.js

@@ -3,8 +3,265 @@
  * schema AST (its manifest copy was written by the CLI) and never derives an
  * overlay. Imports core.ts only, so hosts load it without resolving mikro/*
  * builtins; results are plain {ok} shapes for the same reason. */
-import { applyDefaults, SchemaError, validate } from './core.js';
+import { applyDefaults, SchemaError, validate, } from './core.js';
+/* The format expressions live here, not in core.ts, because core.ts is bundled
+ * into the device and a config schema is never validated there. Not a
+ * caller-supplied `pattern`: a registry runs these against operator input, so a
+ * publisher-supplied regular expression would be a denial-of-service vector. */
+const FORMAT_PATTERNS = {
+    url: /^[a-zA-Z][a-zA-Z0-9+.-]*:\/\/[^\s/?#]+\S*$/,
+    hostname: /^[a-zA-Z0-9]([a-zA-Z0-9-]{0,61}[a-zA-Z0-9])?(\.[a-zA-Z0-9]([a-zA-Z0-9-]{0,61}[a-zA-Z0-9])?)*$/,
+    ipv4: /^(25[0-5]|2[0-4]\d|1\d\d|[1-9]?\d)(\.(25[0-5]|2[0-4]\d|1\d\d|[1-9]?\d)){3}$/,
+    // Separators do not mix: aa:bb-cc:dd:ee:ff is not an address.
+    mac: /^([0-9a-fA-F]{2}:){5}[0-9a-fA-F]{2}$|^([0-9a-fA-F]{2}-){5}[0-9a-fA-F]{2}$/,
+    email: /^[^\s@]+@[^\s@]+\.[^\s@]+$/,
+};
+export const FORMATS = Object.keys(FORMAT_PATTERNS);
+/**
+ * Validates a value against a config schema, constraints included. `validate()`
+ * in core.ts checks structure only, because it ships to the device and a config
+ * schema never does; every host-side path that validates an operator's value
+ * goes through this instead.
+ */
+export function validateConfig(schema, value) {
+    const structural = validate(schema, value, '');
+    if (structural !== null)
+        return { ok: false, error: structural.error };
+    const constraint = checkValueConstraints(schema, value, '');
+    if (constraint !== null)
+        return constraint;
+    return { ok: true, value };
+}
+/* Mirrors validate()'s walk, applying only the constraint checks. Runs after
+ * the structural pass, so every value here is already the right shape. */
+function checkValueConstraints(schema, value, path) {
+    switch (schema.kind) {
+        case 'string': {
+            const text = value;
+            const { minLength, maxLength, format } = schema;
+            if (minLength !== undefined && text.length < minLength) {
+                return fail(`shorter than ${minLength} characters`, path);
+            }
+            if (maxLength !== undefined && text.length > maxLength) {
+                return fail(`longer than ${maxLength} characters`, path);
+            }
+            if (format !== undefined && !FORMAT_PATTERNS[format].test(text)) {
+                return fail(`not a valid ${format}`, path);
+            }
+            // The pattern bounds each label at 63 characters; the whole name has its
+            // own limit that no per-label rule can express.
+            if (format === 'hostname' && text.length > 253) {
+                return fail('not a valid hostname', path);
+            }
+            return null;
+        }
+        case 'number': {
+            const num = value;
+            const { min, max } = schema;
+            if (schema.integer === true && !Number.isInteger(num)) {
+                return fail(`expected a whole number, got ${num}`, path);
+            }
+            if (min !== undefined && num < min)
+                return fail(`below the minimum of ${min}`, path);
+            if (max !== undefined && num > max)
+                return fail(`above the maximum of ${max}`, path);
+            return null;
+        }
+        case 'array': {
+            const items = value;
+            const { minItems, maxItems } = schema;
+            if (minItems !== undefined && items.length < minItems) {
+                return fail(`fewer than ${minItems} items`, path);
+            }
+            if (maxItems !== undefined && items.length > maxItems) {
+                return fail(`more than ${maxItems} items`, path);
+            }
+            for (let i = 0; i < items.length; i++) {
+                const result = checkValueConstraints(schema.element, items[i], `${path}[${i}]`);
+                if (result !== null)
+                    return result;
+            }
+            return null;
+        }
+        case 'object': {
+            const obj = value;
+            for (const key of Object.keys(schema.shape)) {
+                if (!Object.hasOwn(obj, key))
+                    continue;
+                const result = checkValueConstraints(schema.shape[key], obj[key], `${path}.${key}`);
+                if (result !== null)
+                    return result;
+            }
+            return null;
+        }
+        case 'optional':
+            return value === undefined ? null : checkValueConstraints(schema.inner, value, path);
+        case 'tuple': {
+            const items = value;
+            for (let i = 0; i < schema.elements.length; i++) {
+                const result = checkValueConstraints(schema.elements[i], items[i], `${path}[${i}]`);
+                if (result !== null)
+                    return result;
+            }
+            return null;
+        }
+        case 'union': {
+            /* A union accepts what ANY member accepts, so the constraint pass has to
+             * agree with the structural one. Applying only the first structurally
+             * matching member's constraints would reject a value a later member
+             * allows: in union([number({max: 10}), number({min: 100})]), 150 matches
+             * the first member's shape, fails its bound, and would be refused even
+             * though the second member exists for exactly that value.
+             *
+             * When nothing passes, report the first member's constraint failure
+             * rather than a generic "no member matched": for the ordinary union whose
+             * members differ in shape, that is the specific and useful message. */
+            let firstFailure = null;
+            for (const member of schema.members) {
+                if (validate(member, value, '') !== null)
+                    continue;
+                const result = checkValueConstraints(member, value, path);
+                if (result === null)
+                    return null;
+                firstFailure ??= result;
+            }
+            return firstFailure;
+        }
+        case 'taggedUnion': {
+            const obj = value;
+            const branch = schema.branches[obj[schema.key]];
+            return branch === undefined ? null : checkValueConstraints(branch, value, path);
+        }
+        default:
+            return null;
+    }
+}
+/* Declared as Record<Unit, ...> on purpose: the compiler then refuses a table
+ * that is missing a member of the union or carries one that is not in it, so
+ * the names are declared once in core.ts and cannot drift from this. */
+export const UNITS = {
+    m: { primary: 'm', scale: 1, offset: 0 },
+    kg: { primary: 'kg', scale: 1, offset: 0 },
+    s: { primary: 's', scale: 1, offset: 0 },
+    A: { primary: 'A', scale: 1, offset: 0 },
+    K: { primary: 'K', scale: 1, offset: 0 },
+    cd: { primary: 'cd', scale: 1, offset: 0 },
+    mol: { primary: 'mol', scale: 1, offset: 0 },
+    Hz: { primary: 'Hz', scale: 1, offset: 0 },
+    rad: { primary: 'rad', scale: 1, offset: 0 },
+    sr: { primary: 'sr', scale: 1, offset: 0 },
+    N: { primary: 'N', scale: 1, offset: 0 },
+    Pa: { primary: 'Pa', scale: 1, offset: 0 },
+    J: { primary: 'J', scale: 1, offset: 0 },
+    W: { primary: 'W', scale: 1, offset: 0 },
+    C: { primary: 'C', scale: 1, offset: 0 },
+    V: { primary: 'V', scale: 1, offset: 0 },
+    F: { primary: 'F', scale: 1, offset: 0 },
+    Ohm: { primary: 'Ohm', scale: 1, offset: 0, symbol: 'Ω' },
+    S: { primary: 'S', scale: 1, offset: 0 },
+    Wb: { primary: 'Wb', scale: 1, offset: 0 },
+    T: { primary: 'T', scale: 1, offset: 0 },
+    H: { primary: 'H', scale: 1, offset: 0 },
+    Cel: { primary: 'Cel', scale: 1, offset: 0, symbol: '°C' },
+    lm: { primary: 'lm', scale: 1, offset: 0 },
+    lx: { primary: 'lx', scale: 1, offset: 0 },
+    Bq: { primary: 'Bq', scale: 1, offset: 0 },
+    Gy: { primary: 'Gy', scale: 1, offset: 0 },
+    Sv: { primary: 'Sv', scale: 1, offset: 0 },
+    kat: { primary: 'kat', scale: 1, offset: 0 },
+    m2: { primary: 'm2', scale: 1, offset: 0, symbol: 'm²' },
+    m3: { primary: 'm3', scale: 1, offset: 0, symbol: 'm³' },
+    'm/s': { primary: 'm/s', scale: 1, offset: 0 },
+    'm/s2': { primary: 'm/s2', scale: 1, offset: 0, symbol: 'm/s²' },
+    'm3/s': { primary: 'm3/s', scale: 1, offset: 0, symbol: 'm³/s' },
+    'W/m2': { primary: 'W/m2', scale: 1, offset: 0, symbol: 'W/m²' },
+    'cd/m2': { primary: 'cd/m2', scale: 1, offset: 0, symbol: 'cd/m²' },
+    bit: { primary: 'bit', scale: 1, offset: 0 },
+    'bit/s': { primary: 'bit/s', scale: 1, offset: 0 },
+    lat: { primary: 'lat', scale: 1, offset: 0 },
+    lon: { primary: 'lon', scale: 1, offset: 0 },
+    pH: { primary: 'pH', scale: 1, offset: 0 },
+    dB: { primary: 'dB', scale: 1, offset: 0 },
+    dBW: { primary: 'dBW', scale: 1, offset: 0 },
+    count: { primary: 'count', scale: 1, offset: 0, symbol: '' },
+    '/': { primary: '/', scale: 1, offset: 0, symbol: '' },
+    '%RH': { primary: '%RH', scale: 1, offset: 0 },
+    '%EL': { primary: '%EL', scale: 1, offset: 0 },
+    EL: { primary: 'EL', scale: 1, offset: 0 },
+    '1/s': { primary: '1/s', scale: 1, offset: 0 },
+    'S/m': { primary: 'S/m', scale: 1, offset: 0 },
+    B: { primary: 'B', scale: 1, offset: 0 },
+    VA: { primary: 'VA', scale: 1, offset: 0 },
+    VAs: { primary: 'VAs', scale: 1, offset: 0 },
+    var: { primary: 'var', scale: 1, offset: 0 },
+    vars: { primary: 'vars', scale: 1, offset: 0 },
+    'J/m': { primary: 'J/m', scale: 1, offset: 0 },
+    'kg/m3': { primary: 'kg/m3', scale: 1, offset: 0, symbol: 'kg/m³' },
+    deg: { primary: 'deg', scale: 1, offset: 0, symbol: '°' },
+    NTU: { primary: 'NTU', scale: 1, offset: 0 },
+    ms: { primary: 's', scale: 1 / 1000, offset: 0 },
+    min: { primary: 's', scale: 60, offset: 0 },
+    h: { primary: 's', scale: 3600, offset: 0 },
+    MHz: { primary: 'Hz', scale: 1000000, offset: 0 },
+    kW: { primary: 'W', scale: 1000, offset: 0 },
+    kVA: { primary: 'VA', scale: 1000, offset: 0 },
+    kvar: { primary: 'var', scale: 1000, offset: 0 },
+    Ah: { primary: 'C', scale: 3600, offset: 0 },
+    Wh: { primary: 'J', scale: 3600, offset: 0 },
+    kWh: { primary: 'J', scale: 3600000, offset: 0 },
+    varh: { primary: 'vars', scale: 3600, offset: 0 },
+    kvarh: { primary: 'vars', scale: 3600000, offset: 0 },
+    kVAh: { primary: 'VAs', scale: 3600000, offset: 0 },
+    'Wh/km': { primary: 'J/m', scale: 3.6, offset: 0 },
+    KiB: { primary: 'B', scale: 1024, offset: 0 },
+    GB: { primary: 'B', scale: 1e9, offset: 0 },
+    'Mbit/s': { primary: 'bit/s', scale: 1000000, offset: 0 },
+    'B/s': { primary: 'bit/s', scale: 8, offset: 0 },
+    'MB/s': { primary: 'bit/s', scale: 8000000, offset: 0 },
+    mV: { primary: 'V', scale: 1 / 1000, offset: 0 },
+    mA: { primary: 'A', scale: 1 / 1000, offset: 0 },
+    dBm: { primary: 'dBW', scale: 1, offset: -30 },
+    'ug/m3': { primary: 'kg/m3', scale: 1e-9, offset: 0, symbol: 'µg/m³' },
+    'mm/h': { primary: 'm/s', scale: 1 / 3600000, offset: 0 },
+    'm/h': { primary: 'm/s', scale: 1 / 3600, offset: 0 },
+    ppm: { primary: '/', scale: 1e-6, offset: 0 },
+    '/100': { primary: '/', scale: 1 / 100, offset: 0, symbol: '%' },
+    '/1000': { primary: '/', scale: 1 / 1000, offset: 0, symbol: '‰' },
+    hPa: { primary: 'Pa', scale: 100, offset: 0 },
+    mm: { primary: 'm', scale: 1 / 1000, offset: 0 },
+    cm: { primary: 'm', scale: 1 / 100, offset: 0 },
+    km: { primary: 'm', scale: 1000, offset: 0 },
+    'km/h': { primary: 'm/s', scale: 1 / 3.6, offset: 0 },
+    ppb: { primary: '/', scale: 1e-9, offset: 0 },
+    ppt: { primary: '/', scale: 1e-12, offset: 0 },
+    VAh: { primary: 'VAs', scale: 3600, offset: 0 },
+    'mg/l': { primary: 'kg/m3', scale: 1 / 1000, offset: 0 },
+    'ug/l': { primary: 'kg/m3', scale: 1e-6, offset: 0, symbol: 'µg/l' },
+    'g/l': { primary: 'kg/m3', scale: 1, offset: 0 },
+    us: { primary: 's', scale: 1 / 1000000, offset: 0, symbol: 'µs' },
+    kHz: { primary: 'Hz', scale: 1000, offset: 0 },
+    GHz: { primary: 'Hz', scale: 1000000000, offset: 0 },
+    mW: { primary: 'W', scale: 1 / 1000, offset: 0 },
+    uA: { primary: 'A', scale: 1 / 1000000, offset: 0, symbol: 'µA' },
+    uV: { primary: 'V', scale: 1 / 1000000, offset: 0, symbol: 'µV' },
+    mAh: { primary: 'C', scale: 3.6, offset: 0 },
+    MiB: { primary: 'B', scale: 1048576, offset: 0 },
+    kB: { primary: 'B', scale: 1000, offset: 0 },
+    MB: { primary: 'B', scale: 1000000, offset: 0 },
+    'kbit/s': { primary: 'bit/s', scale: 1000, offset: 0 },
+    'KiB/s': { primary: 'bit/s', scale: 8192, offset: 0 },
+    kohm: { primary: 'Ohm', scale: 1000, offset: 0, symbol: 'kΩ' },
+    Mohm: { primary: 'Ohm', scale: 1000000, offset: 0, symbol: 'MΩ' },
+    kPa: { primary: 'Pa', scale: 1000, offset: 0 },
+    bar: { primary: 'Pa', scale: 100000, offset: 0 },
+    Bd: { primary: '1/s', scale: 1, offset: 0 },
+};
 const MAX_DEPTH = 8;
+/* Caps on operator-visible annotation strings. A title is a field label and a
+ * description a sentence or two; both count toward the caller's encoded-size
+ * cap, so bound them here rather than letting one field crowd out a schema. */
+const MAX_TITLE_LENGTH = 80;
+const MAX_DESCRIPTION_LENGTH = 500;
 const KINDS = new Set([
     'string',
     'number',
@@ -193,14 +450,121 @@ function walk(value, path, depth) {
             break;
         }
     }
+    const annotations = checkAnnotations(node, kind, path);
+    if (annotations !== null)
+        return annotations;
     if (node.default !== undefined) {
-        const check = validate(node, node.default, '');
-        if (check !== null) {
+        // Constraint-aware on purpose: the constructors cannot do this any more,
+        // since core.ts no longer carries the checks, so a default that breaks its
+        // own bound must be caught here, at pack, which is moments later.
+        const check = validateConfig(node, node.default);
+        if (!check.ok) {
             return fail(`default does not match the schema: ${check.error.message}`, path);
         }
     }
     return null;
 }
+/* The constructors' own TypeErrors never run against a JSON-sourced AST, so
+ * every annotation the constructors accept is re-checked here. optional() is
+ * the wrapper the annotations do not belong on: it expresses absence, the node
+ * it wraps expresses identity. */
+function checkAnnotations(node, kind, path) {
+    const onWrapper = kind === 'optional' || kind === 'unknown';
+    const text = (key, max) => {
+        const value = node[key];
+        if (value === undefined)
+            return null;
+        if (onWrapper)
+            return fail(`${kind}() cannot carry a ${key}; annotate what it wraps`, path);
+        if (typeof value !== 'string')
+            return fail(`${key} must be a string`, path);
+        if (value.length === 0)
+            return fail(`${key} must not be empty; omit it instead`, path);
+        if (value.length > max)
+            return fail(`${key} is longer than ${max} characters`, path);
+        return null;
+    };
+    const title = text('title', MAX_TITLE_LENGTH);
+    if (title !== null)
+        return title;
+    const description = text('description', MAX_DESCRIPTION_LENGTH);
+    if (description !== null)
+        return description;
+    if (node.mask !== undefined) {
+        if (kind !== 'string' && kind !== 'number') {
+            return fail(`mask is only allowed on string() and number()`, path);
+        }
+        if (typeof node.mask !== 'boolean')
+            return fail('mask must be a boolean', path);
+        if (node.mask === true && node.default !== undefined) {
+            // A masked field with a default ships the same placeholder credential to
+            // every device, which is the opposite of what masking is for. Only when
+            // it is actually masked: `mask: false` is the ordinary state and says
+            // nothing about defaults.
+            return fail('a masked field cannot carry a default', path);
+        }
+    }
+    return checkConstraints(node, kind, path);
+}
+/* Which constraints each kind accepts, and whether the value must be a
+ * non-negative whole number (a count) or merely finite (a bound). */
+const CONSTRAINTS_BY_KIND = {
+    string: ['minLength', 'maxLength'],
+    number: ['min', 'max'],
+    array: ['minItems', 'maxItems'],
+};
+const COUNT_CONSTRAINTS = ['minLength', 'maxLength', 'minItems', 'maxItems'];
+const ALL_CONSTRAINTS = ['minLength', 'maxLength', 'min', 'max', 'minItems', 'maxItems'];
+function checkConstraints(node, kind, path) {
+    const allowed = CONSTRAINTS_BY_KIND[kind];
+    for (const key of ALL_CONSTRAINTS) {
+        const value = node[key];
+        if (value === undefined)
+            continue;
+        if (allowed === undefined || !allowed.includes(key)) {
+            return fail(`${key} is not allowed on ${kind}()`, path);
+        }
+        if (typeof value !== 'number' || !Number.isFinite(value)) {
+            return fail(`${key} must be a finite number`, path);
+        }
+        if (COUNT_CONSTRAINTS.includes(key) && (!Number.isInteger(value) || value < 0)) {
+            return fail(`${key} must be a non-negative whole number`, path);
+        }
+    }
+    if (allowed !== undefined) {
+        const [lower, upper] = allowed;
+        const low = node[lower];
+        const high = node[upper];
+        if (typeof low === 'number' && typeof high === 'number' && low > high) {
+            return fail(`${lower} is greater than ${upper}`, path);
+        }
+    }
+    if (node.integer !== undefined) {
+        if (kind !== 'number')
+            return fail('integer is not allowed on ' + kind + '()', path);
+        if (typeof node.integer !== 'boolean')
+            return fail('integer must be a boolean', path);
+    }
+    if (node.unit !== undefined) {
+        if (kind !== 'number')
+            return fail(`unit is not allowed on ${kind}()`, path);
+        if (typeof node.unit !== 'string' || !Object.hasOwn(UNITS, node.unit)) {
+            return fail(`unknown unit ${JSON.stringify(node.unit)}`, path);
+        }
+    }
+    if (node.format !== undefined) {
+        if (kind !== 'string')
+            return fail(`format is not allowed on ${kind}()`, path);
+        // Fail closed. An unrecognised display annotation may be ignored; an
+        // unrecognised constraint may not, since ignoring it means accepting a
+        // value the author ruled out. Rejecting at publish puts it in front of the
+        // one person who can fix it.
+        if (typeof node.format !== 'string' || !FORMATS.includes(node.format)) {
+            return fail(`unknown format ${JSON.stringify(node.format)} (known: ${FORMATS.join(', ')})`, path);
+        }
+    }
+    return null;
+}
 /**
  * Derives the overlay to store or serve from operator-supplied values: drops
  * keys the schema does not know, strips values structurally equal to the
@@ -303,8 +667,10 @@ export function structuralEquals(a, b) {
  */
 export function parseEffective(schema, overlay) {
     const effective = applyDefaults(schema, overlay);
-    const result = validate(schema, effective, '');
-    return result !== null ? result : { ok: true, value: effective };
+    // validateConfig, not validate: this is the gate an operator's config passes
+    // through, and constraints only bind if they are checked here.
+    const result = validateConfig(schema, effective);
+    return result.ok ? { ok: true, value: effective } : result;
 }
 /**
  * The partial defaults a schema materializes with no overrides: every field a
@@ -350,25 +716,47 @@ function fillField(node) {
 }
 /** A node with its annotations removed, recursively, so two schemas can be
  *  compared on structure alone. */
-function stripAnnotations(node) {
+/* Cosmetic: a change to one of these must never read as a structural change. */
+const DISPLAY_KEYS = ['default', 'title', 'description', 'mask'];
+/* Semantic, so they survive stripAnnotations and are reported on their own
+ * terms. Stripped only for the type comparison, where a tightened bound must
+ * not masquerade as a changed type. */
+const CONSTRAINT_KEYS = [
+    'minLength',
+    'maxLength',
+    'min',
+    'max',
+    'integer',
+    'minItems',
+    'maxItems',
+    'format',
+];
+/* `unit` renders as a suffix, but it is not cosmetic: it reinterprets every
+ * stored value, since `interval: 30` means one thing under `s` and another
+ * under `ms`. Nothing fails validation, the device just behaves differently. So
+ * it survives stripAnnotations and is reported on its own terms, and is
+ * stripped only for the type comparison. */
+const SHAPE_KEYS = [...DISPLAY_KEYS, ...CONSTRAINT_KEYS, 'unit'];
+function stripKeys(node, keys) {
     if (!isPlainObject(node))
         return node;
-    const { default: _default, ...rest } = node;
     const out = {};
-    for (const key of Object.keys(rest)) {
-        const value = rest[key];
+    for (const key of Object.keys(node)) {
+        if (keys.includes(key))
+            continue;
+        const value = node[key];
         if (key === 'shape' || key === 'branches') {
             const map = value;
             const stripped = {};
             for (const k of Object.keys(map))
-                stripped[k] = stripAnnotations(map[k]);
+                stripped[k] = stripKeys(map[k], keys);
             out[key] = stripped;
         }
         else if (key === 'element' || key === 'inner') {
-            out[key] = stripAnnotations(value);
+            out[key] = stripKeys(value, keys);
         }
         else if (key === 'elements' || key === 'members') {
-            out[key] = value.map(stripAnnotations);
+            out[key] = value.map((item) => stripKeys(item, keys));
         }
         else {
             out[key] = value;
@@ -376,6 +764,100 @@ function stripAnnotations(node) {
     }
     return out;
 }
+/** A node reduced to its shape alone, for asking "did the type change?" without
+ *  a tightened bound answering yes.
+ *
+ *  This is now the only comparison the diff makes. Constraints used to be kept
+ *  in some comparisons so that a change to one registered as a difference, but
+ *  every constraint is reported explicitly by constraintWarnings, and keeping
+ *  them here only made a changed bound masquerade as a changed type. */
+function stripToShape(node) {
+    return stripKeys(node, SHAPE_KEYS);
+}
+/* Tightening a bound can invalidate a value an operator already stored, so it
+ * gates the same way a removed union member does. Loosening cannot, and is
+ * silent. Reported at release time on the schemas alone; rule 5 catches which
+ * devices are actually affected when an offer is considered. */
+function constraintWarnings(prev, curr, path, out) {
+    if (!isPlainObject(prev) || !isPlainObject(curr))
+        return;
+    const report = (key, lowerIsLooser) => {
+        const before = prev[key];
+        const after = curr[key];
+        if (after === undefined)
+            return;
+        const gate = (how) => {
+            out.push(`requires an operator: ${path} ${how} ${key} (stored overrides may no longer validate)`);
+        };
+        if (before === undefined)
+            return gate('added');
+        if (typeof before !== 'number' || typeof after !== 'number')
+            return;
+        if (lowerIsLooser ? after > before : after < before)
+            gate(lowerIsLooser ? 'raised' : 'lowered');
+    };
+    for (const key of ['min', 'minLength', 'minItems'])
+        report(key, true);
+    for (const key of ['max', 'maxLength', 'maxItems'])
+        report(key, false);
+    if (curr.integer === true && prev.integer !== true) {
+        out.push(`requires an operator: ${path} now requires a whole number ` +
+            `(stored overrides may no longer validate)`);
+    }
+    if (curr.format !== undefined && prev.format !== curr.format) {
+        out.push(`requires an operator: ${path} now requires format ${JSON.stringify(curr.format)} ` +
+            `(stored overrides may no longer validate)`);
+    }
+    if (prev.unit !== curr.unit) {
+        out.push(`requires an operator: ${path} changed unit from ${JSON.stringify(prev.unit ?? null)} ` +
+            `to ${JSON.stringify(curr.unit ?? null)} (stored values are reinterpreted)`);
+    }
+    /* Descend where the outer walk does not. It recurses through object shapes
+     * only, so without this a tightened bound on an array element or a tuple
+     * position is silent: stripToShape removes constraints recursively, so the
+     * type comparison sees no change, and the checks above only read this node's
+     * own keys. A stranded override with no operator gate is exactly what the
+     * taxonomy exists to prevent. */
+    if (prev.kind === 'array' && curr.kind === 'array') {
+        constraintWarnings(prev.element, curr.element, `${path}[]`, out);
+    }
+    else if (prev.kind === 'tuple' && curr.kind === 'tuple') {
+        const elements = curr.elements;
+        const previous = prev.elements;
+        for (let i = 0; i < Math.min(previous.length, elements.length); i++) {
+            constraintWarnings(previous[i], elements[i], `${path}[${i}]`, out);
+        }
+    }
+    else if (prev.kind === 'optional' && curr.kind === 'optional') {
+        constraintWarnings(prev.inner, curr.inner, path, out);
+    }
+    else if (prev.kind === 'object' && curr.kind === 'object') {
+        /* array(object({port: number({max: 65535})})) is an ordinary config shape,
+         * and without this the port's tightened bound is silent: the outer walk
+         * hands the array to stripToShape, which is equal, and the descent above
+         * reaches the element object and stops.
+         *
+         * No double-reporting with the outer walk: its object branch recurses per
+         * field and returns before reaching constraintWarnings, so an object is
+         * either walked or descended here, never both. */
+        const prevShape = prev.shape;
+        const currShape = curr.shape;
+        for (const key of Object.keys(currShape)) {
+            if (Object.hasOwn(prevShape, key)) {
+                constraintWarnings(prevShape[key], currShape[key], `${path}.${key}`, out);
+            }
+        }
+    }
+    else if (prev.kind === 'taggedUnion' && curr.kind === 'taggedUnion') {
+        const prevBranches = prev.branches;
+        const currBranches = curr.branches;
+        for (const tag of Object.keys(currBranches)) {
+            if (Object.hasOwn(prevBranches, tag)) {
+                constraintWarnings(prevBranches[tag], currBranches[tag], `${path}.${tag}`, out);
+            }
+        }
+    }
+}
 /** required / defaulted / optional, per the spec's scalar-leaf classes.
  *  Containers have no class; objects report 'object' so the walk descends. */
 function leafClass(node) {
@@ -441,11 +923,41 @@ export function diffConfigSchemas(previous, next) {
             // Member sets, not wholesale structure: adding a member (the common
             // safe widening) must not read as a type change. Only removals can
             // invalidate a stored override.
-            const removed = prevInner.members.filter((prevMember) => !currInner.members.some((currMember) => structuralEquals(stripAnnotations(prevMember), stripAnnotations(currMember))));
-            if (removed.length > 0) {
-                warnings.push(`requires an operator: ${path} removed ${removed.length} union member(s) ` +
+            /* Counted by shape group, not tested for membership. Comparing on shape
+             * is what stops a merely loosened bound reading as a removal, but it also
+             * makes two differently bounded members of the same kind indistinguishable
+             * here: asking "does a member of this shape still exist?" answers yes when
+             * one of the two has gone. Dropping one of
+             * union([number({max: 10}), number({min: 100})]) would then be silent,
+             * stranding any override only the removed range accepted.
+             *
+             * A group whose count fell has lost a member. Counting keeps the loosened
+             * bound safe, since that leaves the count unchanged. */
+            const countOfShape = (members, shape) => members.filter((member) => structuralEquals(stripToShape(member), shape)).length;
+            let removed = 0;
+            const groups = [];
+            for (const prevMember of prevInner.members) {
+                const shape = stripToShape(prevMember);
+                if (groups.some((seen) => structuralEquals(seen, shape)))
+                    continue;
+                groups.push(shape);
+                const before = countOfShape(prevInner.members, shape);
+                const after = countOfShape(currInner.members, shape);
+                if (after < before)
+                    removed += before - after;
+            }
+            if (removed > 0) {
+                warnings.push(`requires an operator: ${path} removed ${removed} union member(s) ` +
                     `(stored overrides using them no longer validate)`);
             }
+            // Constraint changes within members, index-wise. Members are ordered and
+            // an edit that also reorders them is not something this can attribute, so
+            // only compare when the lists still line up.
+            if (prevInner.members.length === currInner.members.length) {
+                for (let i = 0; i < prevInner.members.length; i++) {
+                    constraintWarnings(prevInner.members[i], currInner.members[i], `${path}|${i}`, warnings);
+                }
+            }
         }
         else if (prevInner.kind === 'taggedUnion' &&
             currInner.kind === 'taggedUnion' &&
@@ -459,16 +971,20 @@ export function diffConfigSchemas(previous, next) {
                     warnings.push(`requires an operator: ${path} removed branch ${JSON.stringify(tag)} ` +
                         `(stored overrides using it no longer validate)`);
                 }
-                else if (!structuralEquals(stripAnnotations(prevBranch), stripAnnotations(currBranch))) {
+                else if (!structuralEquals(stripToShape(prevBranch), stripToShape(currBranch))) {
+                    // Shape, not constraints: a branch whose bound merely changed has not
+                    // changed type, and the descent in constraintWarnings reports it on
+                    // its own terms rather than as a reshaped branch.
                     warnings.push(`requires an operator: ${path}.${tag} changed type ` +
                         `(stored overrides may no longer validate)`);
                 }
             }
         }
-        else if (!structuralEquals(stripAnnotations(prevInner), stripAnnotations(currInner))) {
+        else if (!structuralEquals(stripToShape(prevInner), stripToShape(currInner))) {
             warnings.push(`requires an operator: ${path} changed type (stored overrides may no longer validate)`);
             return;
         }
+        constraintWarnings(prevInner, currInner, path, warnings);
         const prevClass = leafClass(prev);
         const currClass = leafClass(curr);
         if (currClass === 'required' && prevClass !== 'required') {