@spotto/semantic-query 1.0.70-alpha.33 → 1.0.70-alpha.34

package/dist/validate.js

@@ -1,796 +1,796 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.queryUsesCustomFields = exports.validateSemanticQuery = exports.assertSemanticQuery = exports.coerceSemanticValue = exports.findSemanticField = exports.SEMANTIC_TIMESTAMP_FIELD = exports.SEMANTIC_VALUE_SLOT = void 0;
-const contract_1 = require("@spotto/contract");
-const suggest_1 = require("./suggest");
-const resolve_name_1 = require("./resolve-name");
-const dates_1 = require("./dates");
-const types_1 = require("./types");
-/**
- * Every rule of the semantic query language, in one place.
- *
- * This is the gate both back-ends stand behind: nothing executes a query that
- * has not passed through here, so a rule fixed here is fixed for the client's
- * offline evaluation and the server's Mongo read at the same time. Before this
- * package existed the rules lived inside the Mongo compiler — which meant the
- * only way to ask "is this query valid?" was to try to compile it to MongoDB,
- * and a client could not ask at all.
- *
- * Every rule below was paid for with a query that RAN and returned the wrong
- * rows. None of them throw in the ordinary case; all of them exist because the
- * failure they prevent is silent.
- *
- * Fail-fast: the FIRST problem is the answer. The issues array exists because
- * the wire shape has always carried one, not because more than one is ever
- * reported.
- */
-const LIMITS = contract_1.SEMANTIC_QUERY_LIMITS;
-/** The live storage slots. `valueBool` does not exist; the live key is `valueBoolean`. */
-exports.SEMANTIC_VALUE_SLOT = {
-    STRING: 'valueString',
-    INTEGER: 'valueInteger',
-    DECIMAL: 'valueDecimal',
-    BOOLEAN: 'valueBoolean',
-    DATE: 'valueDate',
-};
-/** Millisecond-timestamp fields, by condition type. `createdDate` uses the ObjectId. */
-exports.SEMANTIC_TIMESTAMP_FIELD = {
-    lastUpdated: 'lastUpdated',
-    lastChanged: 'lastChanged',
-    lastSeen: 'state.lastSeen',
-    firstSeen: 'state.firstSeen',
-};
-/**
- * The complete property vocabulary, per condition type. Closed at the
- * PROPERTY level, not just types and operators: a generated
- * `{"type":"and","conditions":[…],"negate":true}` once compiled as a plain
- * AND — the description said "NOT IN" while the query matched exactly the
- * opposite set, with no error anywhere.
- */
-const TIMESTAMP_KEYS = ['type', 'operator', 'value', 'includeNeverSet'];
-const ALLOWED_KEYS = {
-    and: ['type', 'conditions'],
-    or: ['type', 'conditions'],
-    assetType: ['type', 'path', 'includeSubtypes'],
-    location: ['type', 'path', 'includeSublocations'],
-    homeLocation: ['type', 'path', 'includeSublocations'],
-    withAsset: ['type', 'assetId', 'hasAny'],
-    customField: ['type', 'fieldName', 'dataType', 'operator', 'value', 'includeUnset'],
-    createdDate: TIMESTAMP_KEYS,
-    lastUpdated: TIMESTAMP_KEYS,
-    lastChanged: TIMESTAMP_KEYS,
-    lastSeen: TIMESTAMP_KEYS,
-    firstSeen: TIMESTAMP_KEYS,
-    geolocation: ['type', 'exists'],
-    tags: ['type', 'operator', 'values'],
-    telemetry: ['type', 'field', 'operator', 'value'],
-    readiness: ['type', 'level', 'levels'],
-    kit: ['type', 'isKit', 'isMember', 'satisfied', 'manifest', 'parentAssetId'],
-    locationStatus: ['type', 'values'],
-    // Location vocabulary. `tags`, `geolocation`, the timestamps and `telemetry`
-    // are shared with assets above — same word, same fact, one entry.
-    path: ['type', 'path', 'includeSublocations'],
-    locationType: ['type', 'values'],
-    hasReaders: ['type', 'value'],
-    geofence: ['type', 'exists'],
-    // One word, two vocabularies: the location condition takes only
-    // `manifestId`; the snapshot fork adds `satisfied`. This table is per-WORD,
-    // so `satisfied` is admitted here for both — the `case 'manifest'` branch
-    // is what refuses it on a location query.
-    manifest: ['type', 'manifestId', 'satisfied'],
-    // Event vocabulary. `location` reuses the ASSET entry above (the location
-    // entity's own word is `path`) — the two happen to declare the same
-    // PROPERTIES, which is all this table checks, but they are NOT the same
-    // fact: an asset's `location` is where it is now, an event's is where it
-    // happened. `occurred` does NOT reuse TIMESTAMP_KEYS:
-    // `includeNeverSet` is meaningless when every event has a timestamp, and
-    // accepting a property that can never apply is how a query comes to say
-    // something the compiler ignores.
-    occurred: ['type', 'operator', 'value'],
-    eventType: ['type', 'values'],
-    reader: ['type', 'name'],
-    user: ['type', 'name'],
-    action: ['type', 'name'],
-    // Snapshot vocabulary. `occurred`, `location`, `assetType`, `manifest`,
-    // `user` and `reader` are all shared with the entries above — same word,
-    // same properties, one entry. Only these two are the snapshot's own.
-    //
-    // `asset` takes an id and nothing else. It does NOT get `withAsset`'s
-    // `hasAny`: every snapshot has a subject, so "any asset at all" is not a
-    // question, and accepting a property that can never discriminate is how a
-    // query comes to say something the compiler ignores.
-    snapshotType: ['type', 'values'],
-    asset: ['type', 'assetId'],
-    // Reader vocabulary. `location` is shared with the entries above.
-    deviceType: ['type', 'values'],
-    readerType: ['type', 'values'],
-    attachedAsset: ['type', 'assetId'],
-    online: ['type', 'value'],
-    hasReported: ['type', 'value'],
-    hasGeolocation: ['type', 'value'],
-};
-const HEX24 = /^[0-9a-fA-F]{24}$/;
-/** The kit.manifest vocabulary (SemanticManifestState in the contract). */
-const MANIFEST_STATES = [
-    'satisfied',
-    'needsRecheck',
-    'notSatisfied',
-    'neverChecked',
-];
-function checkProperties(cond, path) {
-    // The table is typed against the contract's vocabulary (a new condition type
-    // is a compile error until it is listed); the lookup itself takes whatever
-    // arbitrary string arrived on the wire.
-    const allowed = ALLOWED_KEYS[String(cond.type)];
-    if (!allowed)
-        return; // unknown type gets its own, better message
-    const extra = Object.keys(cond).filter((k) => !allowed.includes(k));
-    if (extra.length) {
-        (0, types_1.failSemanticValidation)(path, 'UNKNOWN_PROPERTY', `'${cond.type}' does not support ${extra.map((k) => `'${k}'`).join(', ')}` +
-            ` (allowed: ${allowed.filter((k) => k !== 'type').join(', ') || 'none'})`, extra.includes('negate') || extra.includes('not')
-            ? 'The query language has no negation. Express the opposite directly, ' +
-                'or use notExists for an unset field.'
-            : undefined);
-    }
-}
-/**
- * A non-empty values array drawn from a closed platform set. The three
- * enum-valued conditions (`eventType`, `snapshotType`, `deviceType`,
- * `readerType`) all want exactly this, and an unknown value must be a loud
- * failure with a suggestion rather than an arm that matches nothing.
- */
-function requireEnumValues(values, universe, label, path) {
-    if (!Array.isArray(values) || values.length === 0) {
-        (0, types_1.failSemanticValidation)(path, 'BAD_SHAPE', `${label} needs a non-empty values array`);
-    }
-    const unknown = values.filter((v) => !universe.includes(v));
-    if (unknown.length) {
-        (0, types_1.failSemanticValidation)(path, 'BAD_VALUE', `Unknown ${label} ${unknown.map((v) => `'${v}'`).join(', ')}`, (0, suggest_1.nearest)(universe, String(unknown[0])));
-    }
-}
-function requireString(v, path, field) {
-    if (typeof v !== 'string' || v === '') {
-        (0, types_1.failSemanticValidation)(path, 'BAD_SHAPE', `'${field}' must be a non-empty string`);
-    }
-}
-/**
- * Mutually-exclusive properties, enforced here and not only at the wire
- * boundary.
- *
- * Closing key NAMES is not enough. A back-end that merely picked one branch
- * would silently IGNORE the other — a query that runs and returns rows
- * unrelated to half of what it says. Same failure class as the invented
- * `negate` property, one level down.
- */
-function requireExactlyOne(cond, keys, path, label) {
-    const set = keys.filter((k) => cond[k] !== undefined);
-    if (set.length !== 1) {
-        (0, types_1.failSemanticValidation)(path, 'BAD_SHAPE', set.length === 0
-            ? `${label} needs exactly one of ${keys.join(', ')}`
-            : `${label} takes exactly one of ${keys.join(', ')} — got ${set.join(' and ')}`);
-    }
-}
-/**
- * Boolean-typed properties must be REAL booleans, not truthy stand-ins. This
- * is an axis where the two back-ends part company: the Mongo compiler branches
- * on truthiness while the evaluator compares with `===`, so `isKit: null`
- * matches every non-kit in Mongo and nothing in memory. Worst is
- * `satisfied: null`, which compiles to `{groupSatisfiesManifest: null}` — Mongo
- * reads that as "missing OR null", i.e. the whole non-kit fleet: the exact
- * wrong-rows bug the exact-match ruling closed, back through a side door. And
- * even where the engines agree (`includeSubtypes: "false"` reads as true on
- * both sides), the query silently means the opposite of what was written.
- */
-function requireBooleansIfSet(cond, keys, path) {
-    for (const k of keys) {
-        const v = cond[k];
-        if (v !== undefined && typeof v !== 'boolean') {
-            (0, types_1.failSemanticValidation)(path, 'BAD_VALUE', `'${k}' must be true or false — got ${JSON.stringify(v)}`);
-        }
-    }
-}
-/**
- * Find a field by name, case-insensitively — the one lookup both back-ends
- * use, so neither can resolve a name to a different field than the other.
- */
-function findSemanticField(catalogue, fieldName) {
-    return catalogue.fields.find((f) => f.name.toLowerCase() === String(fieldName).toLowerCase());
-}
-exports.findSemanticField = findSemanticField;
-// ---------------------------------------------------------------------------
-// Leaves
-// ---------------------------------------------------------------------------
-/**
- * Is this word in the queried entity's vocabulary?
- *
- * A condition can be perfectly well-formed and still be nonsense for the thing
- * being queried — `readiness` on a location, `snapshotType` on an asset. Left
- * unchecked that is not a syntax error, it is a query that runs and answers
- * the wrong question, so it is refused here with the entity named.
- *
- * When the word belongs to a DIFFERENT entity, say which. That is the
- * generator's likeliest mistake — it has seen the whole language somewhere —
- * and "'readiness' is an asset condition" sends it to the right place, where
- * "not a location condition" only says no.
- */
-function checkEntityVocabulary(type, ctx, path) {
-    var _a;
-    const allowed = (_a = contract_1.semanticConditionTypesByEntity[ctx.entityType]) !== null && _a !== void 0 ? _a : [];
-    if (allowed.includes(type))
-        return;
-    // An entity with no vocabulary is one the language does not speak yet, and
-    // that is the real reason nothing will work — a per-condition complaint here
-    // would send the caller looking for a word that does not exist.
-    if (!allowed.length) {
-        (0, types_1.failSemanticValidation)(path, 'UNSUPPORTED_ENTITY', `'${ctx.entityType}' queries are not supported yet`);
-    }
-    const owner = Object.keys(contract_1.semanticConditionTypesByEntity).find((e) => e !== ctx.entityType && contract_1.semanticConditionTypesByEntity[e].includes(type));
-    if (owner) {
-        (0, types_1.failSemanticValidation)(path, 'WRONG_ENTITY', `'${type}' is a ${owner} condition — this is a ${ctx.entityType} query`);
-    }
-    // Reuses the language's existing "that is not a condition type" code — this
-    // gate now reaches that case before the leaf switch does, and one meaning
-    // should not have two codes.
-    (0, types_1.failSemanticValidation)(path, 'UNKNOWN_TYPE', `'${type}' is not a ${ctx.entityType} condition`, (0, suggest_1.nearest)([...allowed], type));
-}
-function checkLeaf(cond, ctx, path) {
-    // Also checked here, not only in the tree walk: leaves nested inside an
-    // `or` reach this function directly.
-    checkProperties(cond, path);
-    checkEntityVocabulary(cond.type, ctx, path);
-    switch (cond.type) {
-        case 'assetType':
-            requireString(cond.path, path, 'path');
-            requireBooleansIfSet(cond, ['includeSubtypes'], path);
-            return;
-        case 'location':
-        case 'homeLocation':
-            requireString(cond.path, path, 'path');
-            requireBooleansIfSet(cond, ['includeSublocations'], path);
-            return;
-        case 'withAsset': {
-            requireExactlyOne(cond, ['assetId', 'hasAny'], path, 'withAsset');
-            requireBooleansIfSet(cond, ['hasAny'], path);
-            if (cond.hasAny !== undefined)
-                return;
-            if (!cond.assetId || !HEX24.test(cond.assetId)) {
-                (0, types_1.failSemanticValidation)(path, 'BAD_ASSET_ID', 'withAsset needs a valid assetId (24-hex) or hasAny');
-            }
-            return;
-        }
-        case 'geolocation':
-            requireBooleansIfSet(cond, ['exists'], path);
-            return;
-        case 'tags':
-            // Both back-ends read anything that is not 'all' as 'any', so an
-            // unchecked operator is a typo silently widening all-of to any-of —
-            // with the two engines agreeing and both wrong about the intent.
-            if (cond.operator !== undefined &&
-                !contract_1.semanticSetOperators.includes(cond.operator)) {
-                (0, types_1.failSemanticValidation)(path, 'BAD_OPERATOR', `tags operator must be one of ${contract_1.semanticSetOperators.join(', ')} — got '${cond.operator}'`, (0, suggest_1.nearest)(contract_1.semanticSetOperators, String(cond.operator)));
-            }
-            if (!Array.isArray(cond.values) || cond.values.length === 0) {
-                (0, types_1.failSemanticValidation)(path, 'BAD_TAGS', 'tags condition needs a non-empty values array');
-            }
-            return;
-        case 'telemetry': {
-            // Re-checked here, not only at the wire boundary: this value becomes part
-            // of a document PATH downstream, so an unchecked field name would build a
-            // query over an arbitrary key.
-            if (!contract_1.semanticTelemetryFields.includes(cond.field)) {
-                (0, types_1.failSemanticValidation)(path, 'BAD_VALUE', `Unknown telemetry field '${cond.field}' (allowed: ${contract_1.semanticTelemetryFields.join(', ')})`, (0, suggest_1.nearest)(contract_1.semanticTelemetryFields, String(cond.field)));
-            }
-            if (!['eq', 'ne', 'gt', 'gte', 'lt', 'lte'].includes(cond.operator)) {
-                (0, types_1.failSemanticValidation)(path, 'BAD_OPERATOR', `Unknown telemetry operator '${cond.operator}'`);
-            }
-            if (typeof cond.value !== 'number') {
-                (0, types_1.failSemanticValidation)(path, 'BAD_VALUE', `telemetry '${cond.field}' needs a numeric value`);
-            }
-            return;
-        }
-        case 'readiness':
-            checkReadiness(cond, path);
-            return;
-        case 'kit': {
-            requireExactlyOne(cond, ['isKit', 'isMember', 'satisfied', 'manifest', 'parentAssetId'], path, 'kit');
-            requireBooleansIfSet(cond, ['isKit', 'isMember', 'satisfied'], path);
-            if (cond.manifest !== undefined &&
-                !MANIFEST_STATES.includes(cond.manifest)) {
-                (0, types_1.failSemanticValidation)(path, 'BAD_VALUE', `kit.manifest must be one of ${MANIFEST_STATES.join(', ')}`);
-            }
-            if (cond.parentAssetId !== undefined && !HEX24.test(cond.parentAssetId)) {
-                (0, types_1.failSemanticValidation)(path, 'BAD_ASSET_ID', 'kit.parentAssetId must be a 24-hex asset id');
-            }
-            return;
-        }
-        case 'locationStatus': {
-            if (!Array.isArray(cond.values) || cond.values.length === 0) {
-                (0, types_1.failSemanticValidation)(path, 'BAD_SHAPE', 'locationStatus needs a non-empty values array');
-            }
-            const unknown = cond.values.filter((v) => !contract_1.LOCATION_STATUS.includes(v));
-            if (unknown.length) {
-                (0, types_1.failSemanticValidation)(path, 'BAD_VALUE', `Unknown location status ${unknown.map((v) => `'${v}'`).join(', ')}`, (0, suggest_1.nearest)(contract_1.LOCATION_STATUS, String(unknown[0])));
-            }
-            return;
-        }
-        case 'createdDate':
-        case 'lastUpdated':
-        case 'lastChanged':
-        case 'lastSeen':
-        case 'firstSeen':
-            checkTimestamp(cond, ctx, path);
-            return;
-        case 'customField':
-            checkCustomField(cond, ctx, path);
-            return;
-        // --- Location vocabulary ---------------------------------------------
-        case 'path':
-            requireString(cond.path, path, 'path');
-            requireBooleansIfSet(cond, ['includeSublocations'], path);
-            return;
-        case 'locationType': {
-            if (!Array.isArray(cond.values) || cond.values.length === 0) {
-                (0, types_1.failSemanticValidation)(path, 'BAD_SHAPE', 'locationType needs a non-empty values array');
-            }
-            const unknown = cond.values.filter((v) => !contract_1.LOCATION_TYPES.includes(v));
-            if (unknown.length) {
-                (0, types_1.failSemanticValidation)(path, 'BAD_VALUE', `Unknown location type ${unknown.map((v) => `'${v}'`).join(', ')}`, (0, suggest_1.nearest)(contract_1.LOCATION_TYPES, String(unknown[0])));
-            }
-            return;
-        }
-        case 'hasReaders':
-            requireBooleansIfSet(cond, ['value'], path);
-            if (cond.value === undefined) {
-                (0, types_1.failSemanticValidation)(path, 'BAD_SHAPE', "hasReaders needs 'value' (true or false)");
-            }
-            return;
-        case 'geofence':
-            requireBooleansIfSet(cond, ['exists'], path);
-            if (cond.exists === undefined) {
-                (0, types_1.failSemanticValidation)(path, 'BAD_SHAPE', "geofence needs 'exists' (true or false)");
-            }
-            return;
-        case 'manifest': {
-            // Read through a widened local: `satisfied` exists only on the snapshot
-            // fork of this word, so the union type does not carry it.
-            const satisfied = cond.satisfied;
-            if (ctx.entityType === 'snapshot') {
-                // Snapshot fork: the id becomes optional and `satisfied` joins it —
-                // either alone ("all failed checks") or together, at least one
-                // present. Boolean-strict: the flag it reads is exact-match, and a
-                // truthy string would silently match nothing.
-                if (cond.manifestId === undefined && satisfied === undefined) {
-                    (0, types_1.failSemanticValidation)(path, 'BAD_SHAPE', "manifest needs 'manifestId', 'satisfied', or both");
-                }
-                if (satisfied !== undefined && typeof satisfied !== 'boolean') {
-                    (0, types_1.failSemanticValidation)(path, 'BAD_VALUE', 'manifest.satisfied must be true or false');
-                }
-                if (cond.manifestId !== undefined && !HEX24.test(String(cond.manifestId))) {
-                    (0, types_1.failSemanticValidation)(path, 'BAD_MANIFEST_ID', 'manifest.manifestId must be a 24-hex manifest id');
-                }
-                return;
-            }
-            // Location: exactly the historical shape. The shared key table admits
-            // `satisfied` for both entities, so this is where a location query is
-            // refused it.
-            if (satisfied !== undefined) {
-                (0, types_1.failSemanticValidation)(path, 'BAD_SHAPE', "'satisfied' is a snapshot manifest property — a location manifest condition takes only 'manifestId'");
-            }
-            // Ids point. A name would have to be resolved, and a resolution that
-            // missed would run and match nothing.
-            if (!HEX24.test(String(cond.manifestId))) {
-                (0, types_1.failSemanticValidation)(path, 'BAD_MANIFEST_ID', 'manifest.manifestId must be a 24-hex manifest id');
-            }
-            return;
-        }
-        // --- Event vocabulary -------------------------------------------------
-        case 'occurred':
-            // Deliberately NOT `checkTimestamp`: that helper also permits
-            // `includeNeverSet`, which is meaningless when every event has a
-            // timestamp by construction.
-            if (!contract_1.semanticTimestampOperators.includes(cond.operator)) {
-                (0, types_1.failSemanticValidation)(path, 'BAD_OPERATOR', `occurred operator must be one of ${contract_1.semanticTimestampOperators.join(', ')}` +
-                    ` — got '${cond.operator}'`, (0, suggest_1.nearest)(contract_1.semanticTimestampOperators, String(cond.operator)));
-            }
-            // Read through a widened local: `value` is non-optional in the
-            // contract, so comparing it to `undefined` narrows `cond` to `never` and
-            // every later reference stops compiling. The wire can still omit it.
-            {
-                const raw = cond.value;
-                if (raw === undefined) {
-                    (0, types_1.failSemanticValidation)(path, 'BAD_SHAPE', `occurred ${cond.operator} needs a value`);
-                }
-                try {
-                    (0, dates_1.semanticDateBoundaryMs)(raw, cond.operator, ctx.now, ctx.tz);
-                }
-                catch (e) {
-                    return (0, types_1.failSemanticValidation)(path, 'BAD_DATE', e.message);
-                }
-            }
-            return;
-        case 'eventType': {
-            if (!Array.isArray(cond.values) || cond.values.length === 0) {
-                (0, types_1.failSemanticValidation)(path, 'BAD_SHAPE', 'eventType needs a non-empty values array');
-            }
-            const unknown = cond.values.filter((v) => !contract_1.EVENT_TYPES.includes(v));
-            if (unknown.length) {
-                (0, types_1.failSemanticValidation)(path, 'BAD_VALUE', `Unknown event type ${unknown.map((v) => `'${v}'`).join(', ')}`, (0, suggest_1.nearest)(contract_1.EVENT_TYPES, String(unknown[0])));
-            }
-            return;
-        }
-        // The three name-resolved words. Resolution happens HERE rather than in
-        // the compiler so both engines see the same ids, and so an unknown or
-        // ambiguous name is a validation issue with a suggestion — the shape the
-        // AI repair loop and the wire both already understand.
-        case 'reader':
-            resolveOrFail(ctx.catalogue.readers, cond.name, path, 'reader');
-            return;
-        case 'user':
-            resolveOrFail(ctx.catalogue.users, cond.name, path, 'user');
-            return;
-        case 'action':
-            resolveOrFail(ctx.catalogue.actions, cond.name, path, 'action');
-            return;
-        // --- Snapshot vocabulary ----------------------------------------------
-        case 'snapshotType': {
-            if (!Array.isArray(cond.values) || cond.values.length === 0) {
-                (0, types_1.failSemanticValidation)(path, 'BAD_SHAPE', 'snapshotType needs a non-empty values array');
-            }
-            const unknown = cond.values.filter((v) => !contract_1.SNAPSHOT_TYPES.includes(v));
-            if (unknown.length) {
-                (0, types_1.failSemanticValidation)(path, 'BAD_VALUE', `Unknown snapshot type ${unknown.map((v) => `'${v}'`).join(', ')}` +
-                    ` (${contract_1.SNAPSHOT_TYPES.join(', ')})`, (0, suggest_1.nearest)(contract_1.SNAPSHOT_TYPES, String(unknown[0])));
-            }
-            return;
-        }
-        case 'asset':
-            // An id, never a name — the refusal the event vocabulary is built on.
-            // A name here would be a substring regex, and "BC-A1" would quietly
-            // bring back "BC-A10".
-            if (!HEX24.test(String(cond.assetId))) {
-                (0, types_1.failSemanticValidation)(path, 'BAD_ASSET_ID', 'asset.assetId must be a 24-hex asset id');
-            }
-            return;
-        // --- Reader vocabulary ------------------------------------------------
-        case 'deviceType':
-            requireEnumValues(cond.values, contract_1.DEVICE_TYPES, 'deviceType', path);
-            return;
-        case 'readerType':
-            requireEnumValues(cond.values, contract_1.READER_TYPES, 'readerType', path);
-            return;
-        case 'attachedAsset':
-            if (!HEX24.test(String(cond.assetId))) {
-                (0, types_1.failSemanticValidation)(path, 'BAD_ASSET_ID', 'attachedAsset.assetId must be a 24-hex asset id');
-            }
-            return;
-        case 'online':
-        case 'hasReported':
-        case 'hasGeolocation':
-            // Required, not optional. A boolean condition with no value has no
-            // meaning to fall back to — defaulting it either way would answer a
-            // question the caller did not ask.
-            if (typeof cond.value !== 'boolean') {
-                (0, types_1.failSemanticValidation)(path, 'BAD_SHAPE', `${cond.type} needs 'value' (true or false)`);
-            }
-            return;
-        default:
-            (0, types_1.failSemanticValidation)(path, 'UNKNOWN_TYPE', `Unknown condition type '${cond.type}'`);
-    }
-}
-/**
- * Resolve a name or fail with the resolver's own issue. The compiler resolves
- * again from the same catalogue to get the ids it emits; this pass exists so
- * the FAILURE happens at validation time, where it becomes a repairable issue
- * rather than a query that ran against nothing.
- */
-function resolveOrFail(catalogue, name, path, noun) {
-    const { issue } = (0, resolve_name_1.resolveName)(catalogue, name, { path, noun });
-    if (issue)
-        (0, types_1.failSemanticValidation)(path, issue.code, issue.message, issue.suggestion);
-}
-function checkReadiness(cond, path) {
-    var _a;
-    if (cond.level !== undefined && cond.levels !== undefined) {
-        (0, types_1.failSemanticValidation)(path, 'BAD_SHAPE', "readiness takes 'level' or 'levels', not both");
-    }
-    const levels = (_a = cond.levels) !== null && _a !== void 0 ? _a : (cond.level === undefined ? undefined : [cond.level]);
-    if (!levels)
-        (0, types_1.failSemanticValidation)(path, 'BAD_SHAPE', "readiness needs 'level' or 'levels'");
-    if (!Array.isArray(levels))
-        (0, types_1.failSemanticValidation)(path, 'BAD_SHAPE', "'levels' must be an array");
-    if (levels.length === 0)
-        (0, types_1.failSemanticValidation)(path, 'BAD_SHAPE', "'levels' must be non-empty");
-    for (const l of levels) {
-        if (l !== 0 && l !== 1 && l !== 2) {
-            (0, types_1.failSemanticValidation)(path, 'BAD_VALUE', `readiness level must be 0 (ready), 1 (conditional) or 2 (not ready) — got ${l}`);
-        }
-    }
-}
-function checkTimestamp(cond, ctx, path) {
-    const op = cond.operator;
-    if (!['gt', 'gte', 'lt', 'lte'].includes(op)) {
-        (0, types_1.failSemanticValidation)(path, 'BAD_OPERATOR', `'${cond.type}' supports gt, gte, lt, lte — got '${op}'`);
-    }
-    if (cond.value === undefined) {
-        (0, types_1.failSemanticValidation)(path, 'BAD_SHAPE', `'${cond.type}' ${op} needs a value`);
-    }
-    if (cond.includeNeverSet !== undefined && op !== 'lt' && op !== 'lte') {
-        (0, types_1.failSemanticValidation)(path, 'BAD_SHAPE', `'includeNeverSet' applies to lt/lte only — a missing timestamp correctly fails ${op}`);
-    }
-    requireBooleansIfSet(cond, ['includeNeverSet'], path);
-    let ms;
-    try {
-        ms = (0, dates_1.semanticDateBoundaryMs)(cond.value, op, ctx.now, ctx.tz);
-    }
-    catch (e) {
-        return (0, types_1.failSemanticValidation)(path, 'BAD_DATE', e.message);
-    }
-    if (cond.type === 'createdDate') {
-        // Creation time is carried by the ObjectId, whose 4-byte timestamp is
-        // unsigned: dates before 1970 or past 2106 have no id to compare against,
-        // and must fail as a validation issue rather than as an exception escaping
-        // from a back-end. `+1` because the inclusive forms step a second (see the
-        // compiler's boundary-second note).
-        const second = Math.floor(ms / 1000) + 1;
-        if (second < 0 || second > 0xffffffff) {
-            (0, types_1.failSemanticValidation)(path, 'BAD_DATE', `'${cond.type}': date is outside the representable range (1970–2106)`);
-        }
-    }
-}
-function checkCustomField(cond, ctx, path) {
-    var _a;
-    const fdef = findSemanticField(ctx.catalogue, cond.fieldName);
-    if (!fdef) {
-        (0, types_1.failSemanticValidation)(path, 'UNKNOWN_FIELD', `No custom field named '${cond.fieldName}'`, (0, suggest_1.nearest)(ctx.catalogue.fields.map((f) => f.name), String(cond.fieldName)));
-    }
-    if (cond.operator === 'exists' || cond.operator === 'notExists') {
-        if (cond.value !== undefined) {
-            (0, types_1.failSemanticValidation)(path, 'BAD_SHAPE', `'${cond.fieldName}' ${cond.operator} takes no value`);
-        }
-    }
-    else if (cond.value === undefined) {
-        (0, types_1.failSemanticValidation)(path, 'BAD_SHAPE', `'${cond.fieldName}' ${cond.operator} needs a value`);
-    }
-    if (cond.includeUnset !== undefined && cond.operator !== 'ne') {
-        (0, types_1.failSemanticValidation)(path, 'BAD_SHAPE', "'includeUnset' applies to the ne operator only — it is what decides " +
-            'whether an unset field counts as "not equal"');
-    }
-    requireBooleansIfSet(cond, ['includeUnset'], path);
-    // Honest refusal until the DATETIME ruling lands: matching against the wrong
-    // slot is a valid query that returns nothing.
-    if (fdef.dataType === 'DATETIME') {
-        (0, types_1.failSemanticValidation)(path, 'UNSUPPORTED_DATATYPE', `'${fdef.name}' is a date-and-time field, which semantic queries do not support yet`);
-    }
-    // A dropdown value must match an option exactly, or the query silently
-    // returns nothing. Reject with the nearest option instead.
-    if (((_a = fdef.options) === null || _a === void 0 ? void 0 : _a.length) && cond.operator === 'eq' && typeof cond.value === 'string') {
-        if (!fdef.options.includes(cond.value)) {
-            (0, types_1.failSemanticValidation)(path, 'BAD_OPTION', `'${cond.value}' is not an option for '${fdef.name}'`, (0, suggest_1.nearest)(fdef.options, cond.value));
-        }
-    }
-    if (cond.operator === 'contains') {
-        if (fdef.dataType !== 'STRING') {
-            (0, types_1.failSemanticValidation)(path, 'BAD_OPERATOR', `'contains' applies to STRING fields only ('${fdef.name}' is ${fdef.dataType})`);
-        }
-        return;
-    }
-    if (cond.operator === 'exists' || cond.operator === 'notExists')
-        return;
-    if (!['eq', 'ne', 'gt', 'gte', 'lt', 'lte'].includes(cond.operator)) {
-        (0, types_1.failSemanticValidation)(path, 'BAD_OPERATOR', `Unknown operator '${cond.operator}' on '${fdef.name}'`);
-    }
-    // The value must be expressible in the slot it will be compared against.
-    checkValue(cond, fdef, ctx, path);
-}
-/**
- * Turn a written value into the form its storage slot actually holds.
- *
- * Shared deliberately: the Mongo compiler and the in-memory evaluator must
- * compare against the SAME value, and this is where a numeric literal for a
- * text field, or a relative date for a DATE field, becomes one concrete thing.
- * Two copies of this would classify the same document differently.
- *
- * Throws a plain Error — the caller decides whether that is a validation issue
- * (it is, at the gate) or an impossible state (it is, after the gate).
- */
-function coerceSemanticValue(value, dataType, now, tz) {
-    switch (dataType) {
-        case 'DATE':
-            // Confirmed encoding: YYYYMMDD integer, e.g. 20260815.
-            return (0, dates_1.semanticCivilToYyyymmdd)((0, dates_1.resolveSemanticDate)(value, now, tz));
-        case 'INTEGER':
-        case 'DECIMAL': {
-            const n = typeof value === 'number' ? value : Number(value);
-            if (!Number.isFinite(n)) {
-                throw new Error(`is ${dataType} but got '${String(value)}'`);
-            }
-            return n;
-        }
-        case 'BOOLEAN': {
-            if (typeof value === 'boolean')
-                return value;
-            if (value === 'true' || value === 'false')
-                return value === 'true';
-            throw new Error(`is BOOLEAN but got '${String(value)}'`);
-        }
-        default:
-            return typeof value === 'string' ? value : String(value !== null && value !== void 0 ? value : '');
-    }
-}
-exports.coerceSemanticValue = coerceSemanticValue;
-function checkValue(cond, fdef, ctx, path) {
-    try {
-        coerceSemanticValue(cond.value, fdef.dataType, ctx.now, ctx.tz);
-    }
-    catch (e) {
-        const message = e.message;
-        fdef.dataType === 'DATE'
-            ? (0, types_1.failSemanticValidation)(path, 'BAD_DATE', `'${fdef.name}': ${message}`)
-            : (0, types_1.failSemanticValidation)(path, 'BAD_VALUE', `'${fdef.name}' ${message}`);
-    }
-}
-// ---------------------------------------------------------------------------
-// Tree
-// ---------------------------------------------------------------------------
-function checkConditions(conds, ctx, depth, budget, path) {
-    if (!Array.isArray(conds))
-        (0, types_1.failSemanticValidation)(path, 'BAD_SHAPE', 'conditions must be an array');
-    if (depth > LIMITS.maxDepth) {
-        (0, types_1.failSemanticValidation)(path, 'TOO_DEEP', `Nesting exceeds maximum depth ${LIMITS.maxDepth}`);
-    }
-    conds.forEach((cond, i) => {
-        if (++budget.n > LIMITS.maxConditions) {
-            (0, types_1.failSemanticValidation)(path, 'TOO_MANY', `Query exceeds maximum of ${LIMITS.maxConditions} conditions`);
-        }
-        const p = `${path}[${i}]`;
-        if (!cond || typeof cond !== 'object')
-            (0, types_1.failSemanticValidation)(p, 'BAD_SHAPE', 'condition must be an object');
-        if (cond.type === 'and' || cond.type === 'or') {
-            // Leaves are checked inside checkLeaf (the only path an or-branch leaf
-            // takes), so groups are checked here and nowhere twice.
-            checkProperties(cond, p);
-            if (!Array.isArray(cond.conditions) || cond.conditions.length === 0) {
-                // An empty group means "always true" — quietly widening the query to
-                // everything.
-                (0, types_1.failSemanticValidation)(p, 'BAD_SHAPE', `'${cond.type}' needs a non-empty conditions array`);
-            }
-        }
-        if (cond.type === 'and') {
-            checkConditions(cond.conditions, ctx, depth + 1, budget, p);
-        }
-        else if (cond.type === 'or') {
-            cond.conditions.forEach((c, j) => {
-                const bp = `${p}[${j}]`;
-                // Or-branches bypass the top of this walk, so its object guard must
-                // run here too — a null branch is a validation issue, not a TypeError
-                // out of the property check.
-                if (!c || typeof c !== 'object')
-                    (0, types_1.failSemanticValidation)(bp, 'BAD_SHAPE', 'condition must be an object');
-                if (c.type === 'and' || c.type === 'or') {
-                    // The recursive walk counts the group itself against the budget —
-                    // counting it here as well double-charged every nested group.
-                    checkConditions([c], ctx, depth + 1, budget, bp);
-                }
-                else {
-                    // Leaves never pass through the walk above, so they are counted
-                    // here. Uncounted branches were a stored query that a 60-byte GET
-                    // could replay as tens of thousands of regex arms over the whole
-                    // collection.
-                    if (++budget.n > LIMITS.maxConditions) {
-                        (0, types_1.failSemanticValidation)(p, 'TOO_MANY', `Query exceeds maximum of ${LIMITS.maxConditions} conditions`);
-                    }
-                    checkLeaf(c, ctx, bp);
-                }
-            });
-        }
-        else {
-            checkLeaf(cond, ctx, p);
-        }
-    });
-}
-// ---------------------------------------------------------------------------
-// Entry points
-// ---------------------------------------------------------------------------
-/**
- * Assert a query is valid, throwing `SemanticQueryValidationError` on the
- * first problem. This is the gate: a back-end may assume anything that passed
- * through it is safe to execute.
- */
-function assertSemanticQuery(semanticQuery, catalogue, opts = {}) {
-    var _a, _b, _c;
-    const ctx = {
-        catalogue,
-        now: (_a = opts.now) !== null && _a !== void 0 ? _a : new Date(),
-        tz: (_b = opts.timeZone) !== null && _b !== void 0 ? _b : 'UTC',
-        entityType: (_c = opts.entityType) !== null && _c !== void 0 ? _c : 'asset',
-    };
-    if (!semanticQuery || !Array.isArray(semanticQuery.conditions)) {
-        (0, types_1.failSemanticValidation)('conditions', 'BAD_SHAPE', 'semanticQuery.conditions must be an array');
-    }
-    // The closed vocabulary applies to the ENVELOPE too. Without this a top-level
-    // `{conditions:[…], negate:true}` passes cleanly — the original
-    // invented-property failure, one level up from the conditions it guards.
-    const envelopeExtra = Object.keys(semanticQuery).filter((k) => k !== 'version' && k !== 'conditions');
-    if (envelopeExtra.length) {
-        (0, types_1.failSemanticValidation)('', 'UNKNOWN_PROPERTY', `A semantic query has only 'version' and 'conditions' — got ${envelopeExtra
-            .map((k) => `'${k}'`)
-            .join(', ')}`);
-    }
-    if (semanticQuery.version !== undefined &&
-        semanticQuery.version !== contract_1.SEMANTIC_QUERY_VERSION) {
-        (0, types_1.failSemanticValidation)('version', 'BAD_VERSION', `Unsupported semantic query version ${semanticQuery.version} ` +
-            `(this build understands version ${contract_1.SEMANTIC_QUERY_VERSION})`);
-    }
-    checkConditions(semanticQuery.conditions, ctx, 1, { n: 0 }, 'conditions');
-    checkEventAssetTypeScope(semanticQuery.conditions, ctx);
-}
-exports.assertSemanticQuery = assertSemanticQuery;
-/**
- * Every condition ANDed with the rest at the top level — descending through
- * `and` groups, never through `or`, because an or-branch is an alternative
- * rather than a further constraint.
- */
-function conjuncts(conditions) {
-    return conditions.flatMap((c) => c.type === 'and' && Array.isArray(c.conditions)
-        ? conjuncts(c.conditions)
-        : [c]);
-}
-/**
- * `assetType` beside an `eventType` that names no asset-CRUD event.
- *
- * The condition already scopes itself to `ASSET_CRUD_EVENT_TYPES` at the leaf,
- * so this conjunction is not WRONG — it is provably empty, which is worse:
- * "movements of forklifts" would render as an ordinary filter over an ordinary
- * empty feed, the exact silent-nothing that kept `assetType` out of the event
- * vocabulary in the first place. Refusing it with a reason is what lets the
- * word exist at all.
- *
- * Only conjuncts are considered — `(forklift creations) OR (any movement)` is
- * a legitimate question, and leaf scoping already answers it correctly.
- */
-function checkEventAssetTypeScope(conditions, ctx) {
-    var _a;
-    if (ctx.entityType !== 'event')
-        return;
-    const flat = conjuncts(conditions);
-    if (!flat.some((c) => c.type === 'assetType'))
-        return;
-    for (const cond of flat) {
-        if (cond.type !== 'eventType')
-            continue;
-        const values = (_a = cond.values) !== null && _a !== void 0 ? _a : [];
-        if (!values.length)
-            continue;
-        if (values.some((v) => contract_1.ASSET_CRUD_EVENT_TYPES.includes(v))) {
-            continue;
-        }
-        (0, types_1.failSemanticValidation)('conditions', 'CONFLICTING_CONDITIONS', `An asset type can only narrow ${contract_1.ASSET_CRUD_EVENT_TYPES.join(', ')} — ` +
-            `the other event kinds do not record the asset's type, so pairing it ` +
-            `with ${values.join(', ')} matches nothing`, `Drop the asset type, or ask about ${contract_1.ASSET_CRUD_EVENT_TYPES.join(', ')}`);
-    }
-}
-/** Validate without throwing. Empty array = valid. */
-function validateSemanticQuery(semanticQuery, catalogue, opts = {}) {
-    try {
-        assertSemanticQuery(semanticQuery, catalogue, opts);
-        return [];
-    }
-    catch (e) {
-        if (e instanceof types_1.SemanticQueryValidationError)
-            return e.issues;
-        throw e;
-    }
-}
-exports.validateSemanticQuery = validateSemanticQuery;
-/** True when any condition touches a custom field — both back-ends need to know. */
-function queryUsesCustomFields(semanticQuery) {
-    var _a;
-    const walk = (conds) => conds.some((c) => {
-        var _a;
-        return (c === null || c === void 0 ? void 0 : c.type) === 'customField' ||
-            (((c === null || c === void 0 ? void 0 : c.type) === 'and' || (c === null || c === void 0 ? void 0 : c.type) === 'or') && walk((_a = c.conditions) !== null && _a !== void 0 ? _a : []));
-    });
-    return walk((_a = semanticQuery === null || semanticQuery === void 0 ? void 0 : semanticQuery.conditions) !== null && _a !== void 0 ? _a : []);
-}
-exports.queryUsesCustomFields = queryUsesCustomFields;
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.queryUsesCustomFields = exports.validateSemanticQuery = exports.assertSemanticQuery = exports.coerceSemanticValue = exports.findSemanticField = exports.SEMANTIC_TIMESTAMP_FIELD = exports.SEMANTIC_VALUE_SLOT = void 0;
+const contract_1 = require("@spotto/contract");
+const suggest_1 = require("./suggest");
+const resolve_name_1 = require("./resolve-name");
+const dates_1 = require("./dates");
+const types_1 = require("./types");
+/**
+ * Every rule of the semantic query language, in one place.
+ *
+ * This is the gate both back-ends stand behind: nothing executes a query that
+ * has not passed through here, so a rule fixed here is fixed for the client's
+ * offline evaluation and the server's Mongo read at the same time. Before this
+ * package existed the rules lived inside the Mongo compiler — which meant the
+ * only way to ask "is this query valid?" was to try to compile it to MongoDB,
+ * and a client could not ask at all.
+ *
+ * Every rule below was paid for with a query that RAN and returned the wrong
+ * rows. None of them throw in the ordinary case; all of them exist because the
+ * failure they prevent is silent.
+ *
+ * Fail-fast: the FIRST problem is the answer. The issues array exists because
+ * the wire shape has always carried one, not because more than one is ever
+ * reported.
+ */
+const LIMITS = contract_1.SEMANTIC_QUERY_LIMITS;
+/** The live storage slots. `valueBool` does not exist; the live key is `valueBoolean`. */
+exports.SEMANTIC_VALUE_SLOT = {
+    STRING: 'valueString',
+    INTEGER: 'valueInteger',
+    DECIMAL: 'valueDecimal',
+    BOOLEAN: 'valueBoolean',
+    DATE: 'valueDate',
+};
+/** Millisecond-timestamp fields, by condition type. `createdDate` uses the ObjectId. */
+exports.SEMANTIC_TIMESTAMP_FIELD = {
+    lastUpdated: 'lastUpdated',
+    lastChanged: 'lastChanged',
+    lastSeen: 'state.lastSeen',
+    firstSeen: 'state.firstSeen',
+};
+/**
+ * The complete property vocabulary, per condition type. Closed at the
+ * PROPERTY level, not just types and operators: a generated
+ * `{"type":"and","conditions":[…],"negate":true}` once compiled as a plain
+ * AND — the description said "NOT IN" while the query matched exactly the
+ * opposite set, with no error anywhere.
+ */
+const TIMESTAMP_KEYS = ['type', 'operator', 'value', 'includeNeverSet'];
+const ALLOWED_KEYS = {
+    and: ['type', 'conditions'],
+    or: ['type', 'conditions'],
+    assetType: ['type', 'path', 'includeSubtypes'],
+    location: ['type', 'path', 'includeSublocations'],
+    homeLocation: ['type', 'path', 'includeSublocations'],
+    withAsset: ['type', 'assetId', 'hasAny'],
+    customField: ['type', 'fieldName', 'dataType', 'operator', 'value', 'includeUnset'],
+    createdDate: TIMESTAMP_KEYS,
+    lastUpdated: TIMESTAMP_KEYS,
+    lastChanged: TIMESTAMP_KEYS,
+    lastSeen: TIMESTAMP_KEYS,
+    firstSeen: TIMESTAMP_KEYS,
+    geolocation: ['type', 'exists'],
+    tags: ['type', 'operator', 'values'],
+    telemetry: ['type', 'field', 'operator', 'value'],
+    readiness: ['type', 'level', 'levels'],
+    kit: ['type', 'isKit', 'isMember', 'satisfied', 'manifest', 'parentAssetId'],
+    locationStatus: ['type', 'values'],
+    // Location vocabulary. `tags`, `geolocation`, the timestamps and `telemetry`
+    // are shared with assets above — same word, same fact, one entry.
+    path: ['type', 'path', 'includeSublocations'],
+    locationType: ['type', 'values'],
+    hasReaders: ['type', 'value'],
+    geofence: ['type', 'exists'],
+    // One word, two vocabularies: the location condition takes only
+    // `manifestId`; the snapshot fork adds `satisfied`. This table is per-WORD,
+    // so `satisfied` is admitted here for both — the `case 'manifest'` branch
+    // is what refuses it on a location query.
+    manifest: ['type', 'manifestId', 'satisfied'],
+    // Event vocabulary. `location` reuses the ASSET entry above (the location
+    // entity's own word is `path`) — the two happen to declare the same
+    // PROPERTIES, which is all this table checks, but they are NOT the same
+    // fact: an asset's `location` is where it is now, an event's is where it
+    // happened. `occurred` does NOT reuse TIMESTAMP_KEYS:
+    // `includeNeverSet` is meaningless when every event has a timestamp, and
+    // accepting a property that can never apply is how a query comes to say
+    // something the compiler ignores.
+    occurred: ['type', 'operator', 'value'],
+    eventType: ['type', 'values'],
+    reader: ['type', 'name'],
+    user: ['type', 'name'],
+    action: ['type', 'name'],
+    // Snapshot vocabulary. `occurred`, `location`, `assetType`, `manifest`,
+    // `user` and `reader` are all shared with the entries above — same word,
+    // same properties, one entry. Only these two are the snapshot's own.
+    //
+    // `asset` takes an id and nothing else. It does NOT get `withAsset`'s
+    // `hasAny`: every snapshot has a subject, so "any asset at all" is not a
+    // question, and accepting a property that can never discriminate is how a
+    // query comes to say something the compiler ignores.
+    snapshotType: ['type', 'values'],
+    asset: ['type', 'assetId'],
+    // Reader vocabulary. `location` is shared with the entries above.
+    deviceType: ['type', 'values'],
+    readerType: ['type', 'values'],
+    attachedAsset: ['type', 'assetId'],
+    online: ['type', 'value'],
+    hasReported: ['type', 'value'],
+    hasGeolocation: ['type', 'value'],
+};
+const HEX24 = /^[0-9a-fA-F]{24}$/;
+/** The kit.manifest vocabulary (SemanticManifestState in the contract). */
+const MANIFEST_STATES = [
+    'satisfied',
+    'needsRecheck',
+    'notSatisfied',
+    'neverChecked',
+];
+function checkProperties(cond, path) {
+    // The table is typed against the contract's vocabulary (a new condition type
+    // is a compile error until it is listed); the lookup itself takes whatever
+    // arbitrary string arrived on the wire.
+    const allowed = ALLOWED_KEYS[String(cond.type)];
+    if (!allowed)
+        return; // unknown type gets its own, better message
+    const extra = Object.keys(cond).filter((k) => !allowed.includes(k));
+    if (extra.length) {
+        (0, types_1.failSemanticValidation)(path, 'UNKNOWN_PROPERTY', `'${cond.type}' does not support ${extra.map((k) => `'${k}'`).join(', ')}` +
+            ` (allowed: ${allowed.filter((k) => k !== 'type').join(', ') || 'none'})`, extra.includes('negate') || extra.includes('not')
+            ? 'The query language has no negation. Express the opposite directly, ' +
+                'or use notExists for an unset field.'
+            : undefined);
+    }
+}
+/**
+ * A non-empty values array drawn from a closed platform set. The three
+ * enum-valued conditions (`eventType`, `snapshotType`, `deviceType`,
+ * `readerType`) all want exactly this, and an unknown value must be a loud
+ * failure with a suggestion rather than an arm that matches nothing.
+ */
+function requireEnumValues(values, universe, label, path) {
+    if (!Array.isArray(values) || values.length === 0) {
+        (0, types_1.failSemanticValidation)(path, 'BAD_SHAPE', `${label} needs a non-empty values array`);
+    }
+    const unknown = values.filter((v) => !universe.includes(v));
+    if (unknown.length) {
+        (0, types_1.failSemanticValidation)(path, 'BAD_VALUE', `Unknown ${label} ${unknown.map((v) => `'${v}'`).join(', ')}`, (0, suggest_1.nearest)(universe, String(unknown[0])));
+    }
+}
+function requireString(v, path, field) {
+    if (typeof v !== 'string' || v === '') {
+        (0, types_1.failSemanticValidation)(path, 'BAD_SHAPE', `'${field}' must be a non-empty string`);
+    }
+}
+/**
+ * Mutually-exclusive properties, enforced here and not only at the wire
+ * boundary.
+ *
+ * Closing key NAMES is not enough. A back-end that merely picked one branch
+ * would silently IGNORE the other — a query that runs and returns rows
+ * unrelated to half of what it says. Same failure class as the invented
+ * `negate` property, one level down.
+ */
+function requireExactlyOne(cond, keys, path, label) {
+    const set = keys.filter((k) => cond[k] !== undefined);
+    if (set.length !== 1) {
+        (0, types_1.failSemanticValidation)(path, 'BAD_SHAPE', set.length === 0
+            ? `${label} needs exactly one of ${keys.join(', ')}`
+            : `${label} takes exactly one of ${keys.join(', ')} — got ${set.join(' and ')}`);
+    }
+}
+/**
+ * Boolean-typed properties must be REAL booleans, not truthy stand-ins. This
+ * is an axis where the two back-ends part company: the Mongo compiler branches
+ * on truthiness while the evaluator compares with `===`, so `isKit: null`
+ * matches every non-kit in Mongo and nothing in memory. Worst is
+ * `satisfied: null`, which compiles to `{groupSatisfiesManifest: null}` — Mongo
+ * reads that as "missing OR null", i.e. the whole non-kit fleet: the exact
+ * wrong-rows bug the exact-match ruling closed, back through a side door. And
+ * even where the engines agree (`includeSubtypes: "false"` reads as true on
+ * both sides), the query silently means the opposite of what was written.
+ */
+function requireBooleansIfSet(cond, keys, path) {
+    for (const k of keys) {
+        const v = cond[k];
+        if (v !== undefined && typeof v !== 'boolean') {
+            (0, types_1.failSemanticValidation)(path, 'BAD_VALUE', `'${k}' must be true or false — got ${JSON.stringify(v)}`);
+        }
+    }
+}
+/**
+ * Find a field by name, case-insensitively — the one lookup both back-ends
+ * use, so neither can resolve a name to a different field than the other.
+ */
+function findSemanticField(catalogue, fieldName) {
+    return catalogue.fields.find((f) => f.name.toLowerCase() === String(fieldName).toLowerCase());
+}
+exports.findSemanticField = findSemanticField;
+// ---------------------------------------------------------------------------
+// Leaves
+// ---------------------------------------------------------------------------
+/**
+ * Is this word in the queried entity's vocabulary?
+ *
+ * A condition can be perfectly well-formed and still be nonsense for the thing
+ * being queried — `readiness` on a location, `snapshotType` on an asset. Left
+ * unchecked that is not a syntax error, it is a query that runs and answers
+ * the wrong question, so it is refused here with the entity named.
+ *
+ * When the word belongs to a DIFFERENT entity, say which. That is the
+ * generator's likeliest mistake — it has seen the whole language somewhere —
+ * and "'readiness' is an asset condition" sends it to the right place, where
+ * "not a location condition" only says no.
+ */
+function checkEntityVocabulary(type, ctx, path) {
+    var _a;
+    const allowed = (_a = contract_1.semanticConditionTypesByEntity[ctx.entityType]) !== null && _a !== void 0 ? _a : [];
+    if (allowed.includes(type))
+        return;
+    // An entity with no vocabulary is one the language does not speak yet, and
+    // that is the real reason nothing will work — a per-condition complaint here
+    // would send the caller looking for a word that does not exist.
+    if (!allowed.length) {
+        (0, types_1.failSemanticValidation)(path, 'UNSUPPORTED_ENTITY', `'${ctx.entityType}' queries are not supported yet`);
+    }
+    const owner = Object.keys(contract_1.semanticConditionTypesByEntity).find((e) => e !== ctx.entityType && contract_1.semanticConditionTypesByEntity[e].includes(type));
+    if (owner) {
+        (0, types_1.failSemanticValidation)(path, 'WRONG_ENTITY', `'${type}' is a ${owner} condition — this is a ${ctx.entityType} query`);
+    }
+    // Reuses the language's existing "that is not a condition type" code — this
+    // gate now reaches that case before the leaf switch does, and one meaning
+    // should not have two codes.
+    (0, types_1.failSemanticValidation)(path, 'UNKNOWN_TYPE', `'${type}' is not a ${ctx.entityType} condition`, (0, suggest_1.nearest)([...allowed], type));
+}
+function checkLeaf(cond, ctx, path) {
+    // Also checked here, not only in the tree walk: leaves nested inside an
+    // `or` reach this function directly.
+    checkProperties(cond, path);
+    checkEntityVocabulary(cond.type, ctx, path);
+    switch (cond.type) {
+        case 'assetType':
+            requireString(cond.path, path, 'path');
+            requireBooleansIfSet(cond, ['includeSubtypes'], path);
+            return;
+        case 'location':
+        case 'homeLocation':
+            requireString(cond.path, path, 'path');
+            requireBooleansIfSet(cond, ['includeSublocations'], path);
+            return;
+        case 'withAsset': {
+            requireExactlyOne(cond, ['assetId', 'hasAny'], path, 'withAsset');
+            requireBooleansIfSet(cond, ['hasAny'], path);
+            if (cond.hasAny !== undefined)
+                return;
+            if (!cond.assetId || !HEX24.test(cond.assetId)) {
+                (0, types_1.failSemanticValidation)(path, 'BAD_ASSET_ID', 'withAsset needs a valid assetId (24-hex) or hasAny');
+            }
+            return;
+        }
+        case 'geolocation':
+            requireBooleansIfSet(cond, ['exists'], path);
+            return;
+        case 'tags':
+            // Both back-ends read anything that is not 'all' as 'any', so an
+            // unchecked operator is a typo silently widening all-of to any-of —
+            // with the two engines agreeing and both wrong about the intent.
+            if (cond.operator !== undefined &&
+                !contract_1.semanticSetOperators.includes(cond.operator)) {
+                (0, types_1.failSemanticValidation)(path, 'BAD_OPERATOR', `tags operator must be one of ${contract_1.semanticSetOperators.join(', ')} — got '${cond.operator}'`, (0, suggest_1.nearest)(contract_1.semanticSetOperators, String(cond.operator)));
+            }
+            if (!Array.isArray(cond.values) || cond.values.length === 0) {
+                (0, types_1.failSemanticValidation)(path, 'BAD_TAGS', 'tags condition needs a non-empty values array');
+            }
+            return;
+        case 'telemetry': {
+            // Re-checked here, not only at the wire boundary: this value becomes part
+            // of a document PATH downstream, so an unchecked field name would build a
+            // query over an arbitrary key.
+            if (!contract_1.semanticTelemetryFields.includes(cond.field)) {
+                (0, types_1.failSemanticValidation)(path, 'BAD_VALUE', `Unknown telemetry field '${cond.field}' (allowed: ${contract_1.semanticTelemetryFields.join(', ')})`, (0, suggest_1.nearest)(contract_1.semanticTelemetryFields, String(cond.field)));
+            }
+            if (!['eq', 'ne', 'gt', 'gte', 'lt', 'lte'].includes(cond.operator)) {
+                (0, types_1.failSemanticValidation)(path, 'BAD_OPERATOR', `Unknown telemetry operator '${cond.operator}'`);
+            }
+            if (typeof cond.value !== 'number') {
+                (0, types_1.failSemanticValidation)(path, 'BAD_VALUE', `telemetry '${cond.field}' needs a numeric value`);
+            }
+            return;
+        }
+        case 'readiness':
+            checkReadiness(cond, path);
+            return;
+        case 'kit': {
+            requireExactlyOne(cond, ['isKit', 'isMember', 'satisfied', 'manifest', 'parentAssetId'], path, 'kit');
+            requireBooleansIfSet(cond, ['isKit', 'isMember', 'satisfied'], path);
+            if (cond.manifest !== undefined &&
+                !MANIFEST_STATES.includes(cond.manifest)) {
+                (0, types_1.failSemanticValidation)(path, 'BAD_VALUE', `kit.manifest must be one of ${MANIFEST_STATES.join(', ')}`);
+            }
+            if (cond.parentAssetId !== undefined && !HEX24.test(cond.parentAssetId)) {
+                (0, types_1.failSemanticValidation)(path, 'BAD_ASSET_ID', 'kit.parentAssetId must be a 24-hex asset id');
+            }
+            return;
+        }
+        case 'locationStatus': {
+            if (!Array.isArray(cond.values) || cond.values.length === 0) {
+                (0, types_1.failSemanticValidation)(path, 'BAD_SHAPE', 'locationStatus needs a non-empty values array');
+            }
+            const unknown = cond.values.filter((v) => !contract_1.LOCATION_STATUS.includes(v));
+            if (unknown.length) {
+                (0, types_1.failSemanticValidation)(path, 'BAD_VALUE', `Unknown location status ${unknown.map((v) => `'${v}'`).join(', ')}`, (0, suggest_1.nearest)(contract_1.LOCATION_STATUS, String(unknown[0])));
+            }
+            return;
+        }
+        case 'createdDate':
+        case 'lastUpdated':
+        case 'lastChanged':
+        case 'lastSeen':
+        case 'firstSeen':
+            checkTimestamp(cond, ctx, path);
+            return;
+        case 'customField':
+            checkCustomField(cond, ctx, path);
+            return;
+        // --- Location vocabulary ---------------------------------------------
+        case 'path':
+            requireString(cond.path, path, 'path');
+            requireBooleansIfSet(cond, ['includeSublocations'], path);
+            return;
+        case 'locationType': {
+            if (!Array.isArray(cond.values) || cond.values.length === 0) {
+                (0, types_1.failSemanticValidation)(path, 'BAD_SHAPE', 'locationType needs a non-empty values array');
+            }
+            const unknown = cond.values.filter((v) => !contract_1.LOCATION_TYPES.includes(v));
+            if (unknown.length) {
+                (0, types_1.failSemanticValidation)(path, 'BAD_VALUE', `Unknown location type ${unknown.map((v) => `'${v}'`).join(', ')}`, (0, suggest_1.nearest)(contract_1.LOCATION_TYPES, String(unknown[0])));
+            }
+            return;
+        }
+        case 'hasReaders':
+            requireBooleansIfSet(cond, ['value'], path);
+            if (cond.value === undefined) {
+                (0, types_1.failSemanticValidation)(path, 'BAD_SHAPE', "hasReaders needs 'value' (true or false)");
+            }
+            return;
+        case 'geofence':
+            requireBooleansIfSet(cond, ['exists'], path);
+            if (cond.exists === undefined) {
+                (0, types_1.failSemanticValidation)(path, 'BAD_SHAPE', "geofence needs 'exists' (true or false)");
+            }
+            return;
+        case 'manifest': {
+            // Read through a widened local: `satisfied` exists only on the snapshot
+            // fork of this word, so the union type does not carry it.
+            const satisfied = cond.satisfied;
+            if (ctx.entityType === 'snapshot') {
+                // Snapshot fork: the id becomes optional and `satisfied` joins it —
+                // either alone ("all failed checks") or together, at least one
+                // present. Boolean-strict: the flag it reads is exact-match, and a
+                // truthy string would silently match nothing.
+                if (cond.manifestId === undefined && satisfied === undefined) {
+                    (0, types_1.failSemanticValidation)(path, 'BAD_SHAPE', "manifest needs 'manifestId', 'satisfied', or both");
+                }
+                if (satisfied !== undefined && typeof satisfied !== 'boolean') {
+                    (0, types_1.failSemanticValidation)(path, 'BAD_VALUE', 'manifest.satisfied must be true or false');
+                }
+                if (cond.manifestId !== undefined && !HEX24.test(String(cond.manifestId))) {
+                    (0, types_1.failSemanticValidation)(path, 'BAD_MANIFEST_ID', 'manifest.manifestId must be a 24-hex manifest id');
+                }
+                return;
+            }
+            // Location: exactly the historical shape. The shared key table admits
+            // `satisfied` for both entities, so this is where a location query is
+            // refused it.
+            if (satisfied !== undefined) {
+                (0, types_1.failSemanticValidation)(path, 'BAD_SHAPE', "'satisfied' is a snapshot manifest property — a location manifest condition takes only 'manifestId'");
+            }
+            // Ids point. A name would have to be resolved, and a resolution that
+            // missed would run and match nothing.
+            if (!HEX24.test(String(cond.manifestId))) {
+                (0, types_1.failSemanticValidation)(path, 'BAD_MANIFEST_ID', 'manifest.manifestId must be a 24-hex manifest id');
+            }
+            return;
+        }
+        // --- Event vocabulary -------------------------------------------------
+        case 'occurred':
+            // Deliberately NOT `checkTimestamp`: that helper also permits
+            // `includeNeverSet`, which is meaningless when every event has a
+            // timestamp by construction.
+            if (!contract_1.semanticTimestampOperators.includes(cond.operator)) {
+                (0, types_1.failSemanticValidation)(path, 'BAD_OPERATOR', `occurred operator must be one of ${contract_1.semanticTimestampOperators.join(', ')}` +
+                    ` — got '${cond.operator}'`, (0, suggest_1.nearest)(contract_1.semanticTimestampOperators, String(cond.operator)));
+            }
+            // Read through a widened local: `value` is non-optional in the
+            // contract, so comparing it to `undefined` narrows `cond` to `never` and
+            // every later reference stops compiling. The wire can still omit it.
+            {
+                const raw = cond.value;
+                if (raw === undefined) {
+                    (0, types_1.failSemanticValidation)(path, 'BAD_SHAPE', `occurred ${cond.operator} needs a value`);
+                }
+                try {
+                    (0, dates_1.semanticDateBoundaryMs)(raw, cond.operator, ctx.now, ctx.tz);
+                }
+                catch (e) {
+                    return (0, types_1.failSemanticValidation)(path, 'BAD_DATE', e.message);
+                }
+            }
+            return;
+        case 'eventType': {
+            if (!Array.isArray(cond.values) || cond.values.length === 0) {
+                (0, types_1.failSemanticValidation)(path, 'BAD_SHAPE', 'eventType needs a non-empty values array');
+            }
+            const unknown = cond.values.filter((v) => !contract_1.EVENT_TYPES.includes(v));
+            if (unknown.length) {
+                (0, types_1.failSemanticValidation)(path, 'BAD_VALUE', `Unknown event type ${unknown.map((v) => `'${v}'`).join(', ')}`, (0, suggest_1.nearest)(contract_1.EVENT_TYPES, String(unknown[0])));
+            }
+            return;
+        }
+        // The three name-resolved words. Resolution happens HERE rather than in
+        // the compiler so both engines see the same ids, and so an unknown or
+        // ambiguous name is a validation issue with a suggestion — the shape the
+        // AI repair loop and the wire both already understand.
+        case 'reader':
+            resolveOrFail(ctx.catalogue.readers, cond.name, path, 'reader');
+            return;
+        case 'user':
+            resolveOrFail(ctx.catalogue.users, cond.name, path, 'user');
+            return;
+        case 'action':
+            resolveOrFail(ctx.catalogue.actions, cond.name, path, 'action');
+            return;
+        // --- Snapshot vocabulary ----------------------------------------------
+        case 'snapshotType': {
+            if (!Array.isArray(cond.values) || cond.values.length === 0) {
+                (0, types_1.failSemanticValidation)(path, 'BAD_SHAPE', 'snapshotType needs a non-empty values array');
+            }
+            const unknown = cond.values.filter((v) => !contract_1.SNAPSHOT_TYPES.includes(v));
+            if (unknown.length) {
+                (0, types_1.failSemanticValidation)(path, 'BAD_VALUE', `Unknown snapshot type ${unknown.map((v) => `'${v}'`).join(', ')}` +
+                    ` (${contract_1.SNAPSHOT_TYPES.join(', ')})`, (0, suggest_1.nearest)(contract_1.SNAPSHOT_TYPES, String(unknown[0])));
+            }
+            return;
+        }
+        case 'asset':
+            // An id, never a name — the refusal the event vocabulary is built on.
+            // A name here would be a substring regex, and "BC-A1" would quietly
+            // bring back "BC-A10".
+            if (!HEX24.test(String(cond.assetId))) {
+                (0, types_1.failSemanticValidation)(path, 'BAD_ASSET_ID', 'asset.assetId must be a 24-hex asset id');
+            }
+            return;
+        // --- Reader vocabulary ------------------------------------------------
+        case 'deviceType':
+            requireEnumValues(cond.values, contract_1.DEVICE_TYPES, 'deviceType', path);
+            return;
+        case 'readerType':
+            requireEnumValues(cond.values, contract_1.READER_TYPES, 'readerType', path);
+            return;
+        case 'attachedAsset':
+            if (!HEX24.test(String(cond.assetId))) {
+                (0, types_1.failSemanticValidation)(path, 'BAD_ASSET_ID', 'attachedAsset.assetId must be a 24-hex asset id');
+            }
+            return;
+        case 'online':
+        case 'hasReported':
+        case 'hasGeolocation':
+            // Required, not optional. A boolean condition with no value has no
+            // meaning to fall back to — defaulting it either way would answer a
+            // question the caller did not ask.
+            if (typeof cond.value !== 'boolean') {
+                (0, types_1.failSemanticValidation)(path, 'BAD_SHAPE', `${cond.type} needs 'value' (true or false)`);
+            }
+            return;
+        default:
+            (0, types_1.failSemanticValidation)(path, 'UNKNOWN_TYPE', `Unknown condition type '${cond.type}'`);
+    }
+}
+/**
+ * Resolve a name or fail with the resolver's own issue. The compiler resolves
+ * again from the same catalogue to get the ids it emits; this pass exists so
+ * the FAILURE happens at validation time, where it becomes a repairable issue
+ * rather than a query that ran against nothing.
+ */
+function resolveOrFail(catalogue, name, path, noun) {
+    const { issue } = (0, resolve_name_1.resolveName)(catalogue, name, { path, noun });
+    if (issue)
+        (0, types_1.failSemanticValidation)(path, issue.code, issue.message, issue.suggestion);
+}
+function checkReadiness(cond, path) {
+    var _a;
+    if (cond.level !== undefined && cond.levels !== undefined) {
+        (0, types_1.failSemanticValidation)(path, 'BAD_SHAPE', "readiness takes 'level' or 'levels', not both");
+    }
+    const levels = (_a = cond.levels) !== null && _a !== void 0 ? _a : (cond.level === undefined ? undefined : [cond.level]);
+    if (!levels)
+        (0, types_1.failSemanticValidation)(path, 'BAD_SHAPE', "readiness needs 'level' or 'levels'");
+    if (!Array.isArray(levels))
+        (0, types_1.failSemanticValidation)(path, 'BAD_SHAPE', "'levels' must be an array");
+    if (levels.length === 0)
+        (0, types_1.failSemanticValidation)(path, 'BAD_SHAPE', "'levels' must be non-empty");
+    for (const l of levels) {
+        if (l !== 0 && l !== 1 && l !== 2) {
+            (0, types_1.failSemanticValidation)(path, 'BAD_VALUE', `readiness level must be 0 (ready), 1 (conditional) or 2 (not ready) — got ${l}`);
+        }
+    }
+}
+function checkTimestamp(cond, ctx, path) {
+    const op = cond.operator;
+    if (!['gt', 'gte', 'lt', 'lte'].includes(op)) {
+        (0, types_1.failSemanticValidation)(path, 'BAD_OPERATOR', `'${cond.type}' supports gt, gte, lt, lte — got '${op}'`);
+    }
+    if (cond.value === undefined) {
+        (0, types_1.failSemanticValidation)(path, 'BAD_SHAPE', `'${cond.type}' ${op} needs a value`);
+    }
+    if (cond.includeNeverSet !== undefined && op !== 'lt' && op !== 'lte') {
+        (0, types_1.failSemanticValidation)(path, 'BAD_SHAPE', `'includeNeverSet' applies to lt/lte only — a missing timestamp correctly fails ${op}`);
+    }
+    requireBooleansIfSet(cond, ['includeNeverSet'], path);
+    let ms;
+    try {
+        ms = (0, dates_1.semanticDateBoundaryMs)(cond.value, op, ctx.now, ctx.tz);
+    }
+    catch (e) {
+        return (0, types_1.failSemanticValidation)(path, 'BAD_DATE', e.message);
+    }
+    if (cond.type === 'createdDate') {
+        // Creation time is carried by the ObjectId, whose 4-byte timestamp is
+        // unsigned: dates before 1970 or past 2106 have no id to compare against,
+        // and must fail as a validation issue rather than as an exception escaping
+        // from a back-end. `+1` because the inclusive forms step a second (see the
+        // compiler's boundary-second note).
+        const second = Math.floor(ms / 1000) + 1;
+        if (second < 0 || second > 0xffffffff) {
+            (0, types_1.failSemanticValidation)(path, 'BAD_DATE', `'${cond.type}': date is outside the representable range (1970–2106)`);
+        }
+    }
+}
+function checkCustomField(cond, ctx, path) {
+    var _a;
+    const fdef = findSemanticField(ctx.catalogue, cond.fieldName);
+    if (!fdef) {
+        (0, types_1.failSemanticValidation)(path, 'UNKNOWN_FIELD', `No custom field named '${cond.fieldName}'`, (0, suggest_1.nearest)(ctx.catalogue.fields.map((f) => f.name), String(cond.fieldName)));
+    }
+    if (cond.operator === 'exists' || cond.operator === 'notExists') {
+        if (cond.value !== undefined) {
+            (0, types_1.failSemanticValidation)(path, 'BAD_SHAPE', `'${cond.fieldName}' ${cond.operator} takes no value`);
+        }
+    }
+    else if (cond.value === undefined) {
+        (0, types_1.failSemanticValidation)(path, 'BAD_SHAPE', `'${cond.fieldName}' ${cond.operator} needs a value`);
+    }
+    if (cond.includeUnset !== undefined && cond.operator !== 'ne') {
+        (0, types_1.failSemanticValidation)(path, 'BAD_SHAPE', "'includeUnset' applies to the ne operator only — it is what decides " +
+            'whether an unset field counts as "not equal"');
+    }
+    requireBooleansIfSet(cond, ['includeUnset'], path);
+    // Honest refusal until the DATETIME ruling lands: matching against the wrong
+    // slot is a valid query that returns nothing.
+    if (fdef.dataType === 'DATETIME') {
+        (0, types_1.failSemanticValidation)(path, 'UNSUPPORTED_DATATYPE', `'${fdef.name}' is a date-and-time field, which semantic queries do not support yet`);
+    }
+    // A dropdown value must match an option exactly, or the query silently
+    // returns nothing. Reject with the nearest option instead.
+    if (((_a = fdef.options) === null || _a === void 0 ? void 0 : _a.length) && cond.operator === 'eq' && typeof cond.value === 'string') {
+        if (!fdef.options.includes(cond.value)) {
+            (0, types_1.failSemanticValidation)(path, 'BAD_OPTION', `'${cond.value}' is not an option for '${fdef.name}'`, (0, suggest_1.nearest)(fdef.options, cond.value));
+        }
+    }
+    if (cond.operator === 'contains') {
+        if (fdef.dataType !== 'STRING') {
+            (0, types_1.failSemanticValidation)(path, 'BAD_OPERATOR', `'contains' applies to STRING fields only ('${fdef.name}' is ${fdef.dataType})`);
+        }
+        return;
+    }
+    if (cond.operator === 'exists' || cond.operator === 'notExists')
+        return;
+    if (!['eq', 'ne', 'gt', 'gte', 'lt', 'lte'].includes(cond.operator)) {
+        (0, types_1.failSemanticValidation)(path, 'BAD_OPERATOR', `Unknown operator '${cond.operator}' on '${fdef.name}'`);
+    }
+    // The value must be expressible in the slot it will be compared against.
+    checkValue(cond, fdef, ctx, path);
+}
+/**
+ * Turn a written value into the form its storage slot actually holds.
+ *
+ * Shared deliberately: the Mongo compiler and the in-memory evaluator must
+ * compare against the SAME value, and this is where a numeric literal for a
+ * text field, or a relative date for a DATE field, becomes one concrete thing.
+ * Two copies of this would classify the same document differently.
+ *
+ * Throws a plain Error — the caller decides whether that is a validation issue
+ * (it is, at the gate) or an impossible state (it is, after the gate).
+ */
+function coerceSemanticValue(value, dataType, now, tz) {
+    switch (dataType) {
+        case 'DATE':
+            // Confirmed encoding: YYYYMMDD integer, e.g. 20260815.
+            return (0, dates_1.semanticCivilToYyyymmdd)((0, dates_1.resolveSemanticDate)(value, now, tz));
+        case 'INTEGER':
+        case 'DECIMAL': {
+            const n = typeof value === 'number' ? value : Number(value);
+            if (!Number.isFinite(n)) {
+                throw new Error(`is ${dataType} but got '${String(value)}'`);
+            }
+            return n;
+        }
+        case 'BOOLEAN': {
+            if (typeof value === 'boolean')
+                return value;
+            if (value === 'true' || value === 'false')
+                return value === 'true';
+            throw new Error(`is BOOLEAN but got '${String(value)}'`);
+        }
+        default:
+            return typeof value === 'string' ? value : String(value !== null && value !== void 0 ? value : '');
+    }
+}
+exports.coerceSemanticValue = coerceSemanticValue;
+function checkValue(cond, fdef, ctx, path) {
+    try {
+        coerceSemanticValue(cond.value, fdef.dataType, ctx.now, ctx.tz);
+    }
+    catch (e) {
+        const message = e.message;
+        fdef.dataType === 'DATE'
+            ? (0, types_1.failSemanticValidation)(path, 'BAD_DATE', `'${fdef.name}': ${message}`)
+            : (0, types_1.failSemanticValidation)(path, 'BAD_VALUE', `'${fdef.name}' ${message}`);
+    }
+}
+// ---------------------------------------------------------------------------
+// Tree
+// ---------------------------------------------------------------------------
+function checkConditions(conds, ctx, depth, budget, path) {
+    if (!Array.isArray(conds))
+        (0, types_1.failSemanticValidation)(path, 'BAD_SHAPE', 'conditions must be an array');
+    if (depth > LIMITS.maxDepth) {
+        (0, types_1.failSemanticValidation)(path, 'TOO_DEEP', `Nesting exceeds maximum depth ${LIMITS.maxDepth}`);
+    }
+    conds.forEach((cond, i) => {
+        if (++budget.n > LIMITS.maxConditions) {
+            (0, types_1.failSemanticValidation)(path, 'TOO_MANY', `Query exceeds maximum of ${LIMITS.maxConditions} conditions`);
+        }
+        const p = `${path}[${i}]`;
+        if (!cond || typeof cond !== 'object')
+            (0, types_1.failSemanticValidation)(p, 'BAD_SHAPE', 'condition must be an object');
+        if (cond.type === 'and' || cond.type === 'or') {
+            // Leaves are checked inside checkLeaf (the only path an or-branch leaf
+            // takes), so groups are checked here and nowhere twice.
+            checkProperties(cond, p);
+            if (!Array.isArray(cond.conditions) || cond.conditions.length === 0) {
+                // An empty group means "always true" — quietly widening the query to
+                // everything.
+                (0, types_1.failSemanticValidation)(p, 'BAD_SHAPE', `'${cond.type}' needs a non-empty conditions array`);
+            }
+        }
+        if (cond.type === 'and') {
+            checkConditions(cond.conditions, ctx, depth + 1, budget, p);
+        }
+        else if (cond.type === 'or') {
+            cond.conditions.forEach((c, j) => {
+                const bp = `${p}[${j}]`;
+                // Or-branches bypass the top of this walk, so its object guard must
+                // run here too — a null branch is a validation issue, not a TypeError
+                // out of the property check.
+                if (!c || typeof c !== 'object')
+                    (0, types_1.failSemanticValidation)(bp, 'BAD_SHAPE', 'condition must be an object');
+                if (c.type === 'and' || c.type === 'or') {
+                    // The recursive walk counts the group itself against the budget —
+                    // counting it here as well double-charged every nested group.
+                    checkConditions([c], ctx, depth + 1, budget, bp);
+                }
+                else {
+                    // Leaves never pass through the walk above, so they are counted
+                    // here. Uncounted branches were a stored query that a 60-byte GET
+                    // could replay as tens of thousands of regex arms over the whole
+                    // collection.
+                    if (++budget.n > LIMITS.maxConditions) {
+                        (0, types_1.failSemanticValidation)(p, 'TOO_MANY', `Query exceeds maximum of ${LIMITS.maxConditions} conditions`);
+                    }
+                    checkLeaf(c, ctx, bp);
+                }
+            });
+        }
+        else {
+            checkLeaf(cond, ctx, p);
+        }
+    });
+}
+// ---------------------------------------------------------------------------
+// Entry points
+// ---------------------------------------------------------------------------
+/**
+ * Assert a query is valid, throwing `SemanticQueryValidationError` on the
+ * first problem. This is the gate: a back-end may assume anything that passed
+ * through it is safe to execute.
+ */
+function assertSemanticQuery(semanticQuery, catalogue, opts = {}) {
+    var _a, _b, _c;
+    const ctx = {
+        catalogue,
+        now: (_a = opts.now) !== null && _a !== void 0 ? _a : new Date(),
+        tz: (_b = opts.timeZone) !== null && _b !== void 0 ? _b : 'UTC',
+        entityType: (_c = opts.entityType) !== null && _c !== void 0 ? _c : 'asset',
+    };
+    if (!semanticQuery || !Array.isArray(semanticQuery.conditions)) {
+        (0, types_1.failSemanticValidation)('conditions', 'BAD_SHAPE', 'semanticQuery.conditions must be an array');
+    }
+    // The closed vocabulary applies to the ENVELOPE too. Without this a top-level
+    // `{conditions:[…], negate:true}` passes cleanly — the original
+    // invented-property failure, one level up from the conditions it guards.
+    const envelopeExtra = Object.keys(semanticQuery).filter((k) => k !== 'version' && k !== 'conditions');
+    if (envelopeExtra.length) {
+        (0, types_1.failSemanticValidation)('', 'UNKNOWN_PROPERTY', `A semantic query has only 'version' and 'conditions' — got ${envelopeExtra
+            .map((k) => `'${k}'`)
+            .join(', ')}`);
+    }
+    if (semanticQuery.version !== undefined &&
+        semanticQuery.version !== contract_1.SEMANTIC_QUERY_VERSION) {
+        (0, types_1.failSemanticValidation)('version', 'BAD_VERSION', `Unsupported semantic query version ${semanticQuery.version} ` +
+            `(this build understands version ${contract_1.SEMANTIC_QUERY_VERSION})`);
+    }
+    checkConditions(semanticQuery.conditions, ctx, 1, { n: 0 }, 'conditions');
+    checkEventAssetTypeScope(semanticQuery.conditions, ctx);
+}
+exports.assertSemanticQuery = assertSemanticQuery;
+/**
+ * Every condition ANDed with the rest at the top level — descending through
+ * `and` groups, never through `or`, because an or-branch is an alternative
+ * rather than a further constraint.
+ */
+function conjuncts(conditions) {
+    return conditions.flatMap((c) => c.type === 'and' && Array.isArray(c.conditions)
+        ? conjuncts(c.conditions)
+        : [c]);
+}
+/**
+ * `assetType` beside an `eventType` that names no asset-CRUD event.
+ *
+ * The condition already scopes itself to `ASSET_CRUD_EVENT_TYPES` at the leaf,
+ * so this conjunction is not WRONG — it is provably empty, which is worse:
+ * "movements of forklifts" would render as an ordinary filter over an ordinary
+ * empty feed, the exact silent-nothing that kept `assetType` out of the event
+ * vocabulary in the first place. Refusing it with a reason is what lets the
+ * word exist at all.
+ *
+ * Only conjuncts are considered — `(forklift creations) OR (any movement)` is
+ * a legitimate question, and leaf scoping already answers it correctly.
+ */
+function checkEventAssetTypeScope(conditions, ctx) {
+    var _a;
+    if (ctx.entityType !== 'event')
+        return;
+    const flat = conjuncts(conditions);
+    if (!flat.some((c) => c.type === 'assetType'))
+        return;
+    for (const cond of flat) {
+        if (cond.type !== 'eventType')
+            continue;
+        const values = (_a = cond.values) !== null && _a !== void 0 ? _a : [];
+        if (!values.length)
+            continue;
+        if (values.some((v) => contract_1.ASSET_CRUD_EVENT_TYPES.includes(v))) {
+            continue;
+        }
+        (0, types_1.failSemanticValidation)('conditions', 'CONFLICTING_CONDITIONS', `An asset type can only narrow ${contract_1.ASSET_CRUD_EVENT_TYPES.join(', ')} — ` +
+            `the other event kinds do not record the asset's type, so pairing it ` +
+            `with ${values.join(', ')} matches nothing`, `Drop the asset type, or ask about ${contract_1.ASSET_CRUD_EVENT_TYPES.join(', ')}`);
+    }
+}
+/** Validate without throwing. Empty array = valid. */
+function validateSemanticQuery(semanticQuery, catalogue, opts = {}) {
+    try {
+        assertSemanticQuery(semanticQuery, catalogue, opts);
+        return [];
+    }
+    catch (e) {
+        if (e instanceof types_1.SemanticQueryValidationError)
+            return e.issues;
+        throw e;
+    }
+}
+exports.validateSemanticQuery = validateSemanticQuery;
+/** True when any condition touches a custom field — both back-ends need to know. */
+function queryUsesCustomFields(semanticQuery) {
+    var _a;
+    const walk = (conds) => conds.some((c) => {
+        var _a;
+        return (c === null || c === void 0 ? void 0 : c.type) === 'customField' ||
+            (((c === null || c === void 0 ? void 0 : c.type) === 'and' || (c === null || c === void 0 ? void 0 : c.type) === 'or') && walk((_a = c.conditions) !== null && _a !== void 0 ? _a : []));
+    });
+    return walk((_a = semanticQuery === null || semanticQuery === void 0 ? void 0 : semanticQuery.conditions) !== null && _a !== void 0 ? _a : []);
+}
+exports.queryUsesCustomFields = queryUsesCustomFields;
 //# sourceMappingURL=validate.js.map