@spotto/semantic-query 1.0.70-alpha.26 → 1.0.70-alpha.27

package/dist/evaluate.js

@@ -1,510 +1,546 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.evaluateSemanticQuery = void 0;
-// Workspace Dependencies
-const contract_1 = require("@spotto/contract");
-// Project Dependencies
-const dates_1 = require("./dates");
-const resolve_name_1 = require("./resolve-name");
-const validate_1 = require("./validate");
-const SLOT = {
-    STRING: 'valueString',
-    INTEGER: 'valueInteger',
-    DECIMAL: 'valueDecimal',
-    BOOLEAN: 'valueBoolean',
-    DATE: 'valueDate',
-};
-function get(doc, path) {
-    return path.split('.').reduce((a, k) => (a == null ? undefined : a[k]), doc);
-}
-function cmp(actual, op, target) {
-    if (actual === undefined || actual === null)
-        return false;
-    switch (op) {
-        case 'eq':
-            return actual === target;
-        case 'ne':
-            return actual !== target;
-        case 'gt':
-            return actual > target;
-        case 'gte':
-            return actual >= target;
-        case 'lt':
-            return actual < target;
-        case 'lte':
-            return actual <= target;
-        default:
-            return false;
-    }
-}
-function evaluateSemanticQuery(query, docs, schema, opts = {}) {
-    var _a, _b, _c;
-    const ctx = {
-        schema,
-        now: (_a = opts.now) !== null && _a !== void 0 ? _a : new Date(),
-        tz: (_b = opts.timeZone) !== null && _b !== void 0 ? _b : 'UTC',
-        fieldByName: new Map(schema.fields.map((f) => [f.name.toLowerCase(), f])),
-        typeById: new Map(schema.types.map((t) => [t.id, t])),
-        entityType: (_c = opts.entityType) !== null && _c !== void 0 ? _c : 'asset',
-    };
-    return docs.filter((d) => query.conditions.every((c) => match(d, c, ctx)));
-}
-exports.evaluateSemanticQuery = evaluateSemanticQuery;
-/**
- * Grouping is shared — it is structure, not subject matter — and everything
- * else dispatches to the entity's own matcher, mirroring the Mongo compiler so
- * the two engines are organised the same way and can be read side by side.
- */
-function match(doc, cond, ctx) {
-    if (cond.type === 'and')
-        return cond.conditions.every((c) => match(doc, c, ctx));
-    if (cond.type === 'or')
-        return cond.conditions.some((c) => match(doc, c, ctx));
-    if (ctx.entityType === 'location') {
-        return matchLocation(doc, cond, ctx);
-    }
-    if (ctx.entityType === 'event') {
-        return matchEvent(doc, cond, ctx);
-    }
-    if (ctx.entityType === 'snapshot') {
-        return matchSnapshot(doc, cond, ctx);
-    }
-    if (ctx.entityType === 'reader') {
-        return matchReader(doc, cond);
-    }
-    return matchAsset(doc, cond, ctx);
-}
-/**
- * Reads the SERVER event document. Events are never evaluated in the browser —
- * the client caches query RESULTS, not events, so there is no corpus to run
- * over. This matcher exists as the ORACLE: the acceptance property
- * `evaluate(q, docs) === find(compile(q))` is what catches an encoding mistake
- * in the Mongo compiler, and an entity with no second implementation has
- * nothing checking it but the person who wrote it.
- *
- * The three name-resolved words compare against the ids VALIDATION already
- * resolved, from the same catalogue the compiler uses — so the two engines
- * cannot disagree about who "Sarah" is.
- */
-function matchEvent(doc, cond, ctx) {
-    var _a, _b, _c, _d, _e;
-    switch (cond.type) {
-        case 'occurred':
-            return cmpTimestamp(get(doc, 'timestamp'), cond.operator, cond.value, ctx);
-        case 'eventType':
-            return ((_a = cond.values) !== null && _a !== void 0 ? _a : []).includes(get(doc, 'type'));
-        case 'assetType': {
-            // BOTH halves, exactly as `action` below and exactly as the compiler:
-            // `thing` is a full asset only on the CRUD events, so the type scope is
-            // part of the condition rather than something a caller must remember.
-            // Checked FIRST — a movement event has no `thing.typePath` at all, and
-            // reading one would only ever produce a confusing miss.
-            if (!contract_1.ASSET_CRUD_EVENT_TYPES.includes(String(get(doc, 'type')))) {
-                return false;
-            }
-            const actual = String((_b = get(doc, 'thing.typePath')) !== null && _b !== void 0 ? _b : '');
-            return cond.includeSubtypes !== false
-                ? actual.startsWith(cond.path)
-                : actual === cond.path;
-        }
-        case 'location': {
-            // The stored pipe path, exactly as a location document keeps it — events
-            // embed it under `location.name`.
-            const actual = String((_c = get(doc, 'location.name')) !== null && _c !== void 0 ? _c : '');
-            return cond.includeSublocations !== false
-                ? actual.startsWith(cond.path)
-                : actual === cond.path;
-        }
-        case 'reader':
-            return idIn(get(doc, 'reader._id'), resolvedIds(ctx.schema.readers, cond.name));
-        case 'user':
-            // A resolved user id inherently excludes system-generated events — Slate
-            // movements carry no user at all, and must never answer "what did X do".
-            return idIn(get(doc, 'user._id'), resolvedIds(ctx.schema.users, cond.name));
-        case 'action': {
-            // An action implies a submission, so both halves are checked — matching
-            // the compiler, which constrains the type for the same reason.
-            // Both submission types — see the compiler's note.
-            if (!SUBMISSION_EVENT_TYPES.includes(String(get(doc, 'type'))))
-                return false;
-            // Resolve ONCE — resolving inside the predicate re-ran it per action.
-            const ids = resolvedIds(ctx.schema.actions, cond.name);
-            const names = ((_d = ctx.schema.actions) !== null && _d !== void 0 ? _d : [])
-                .filter((a) => ids.includes(a.id))
-                .map((a) => a.name);
-            return names.includes(String((_e = get(doc, 'submission.actionName')) !== null && _e !== void 0 ? _e : ''));
-        }
-        default:
-            // LOUD, not false. This function is the ORACLE the Mongo compiler is
-            // checked against, and an oracle that silently matches nothing AGREES
-            // with a compiler that returns nothing — so a word added to the
-            // vocabulary and the compiler but forgotten here would let the
-            // differential check pass by both engines being wrong together.
-            throw new Error(`semantic-query evaluator has no arm for event condition ` +
-                `'${cond.type}'`);
-    }
-}
-/**
- * Reads the SERVER snapshot document.
- *
- * Unlike the event matcher, this one is NOT only an oracle — it is the
- * production path. Snapshots are cached whole and the list filters them in the
- * browser (`useSnapshotList` → `db.snapshots.toArray()`), so a mistake here is
- * a wrong answer a user sees, not a test that fails. The Mongo compiler still
- * has to agree with it for saved queries and widgets.
- *
- * Two arms below are not the obvious reading of the field, and both are
- * copied from the flat filter (`snapshots/filters.ts`) rather than invented,
- * because chip and query must return the same rows.
- */
-function matchSnapshot(doc, cond, ctx) {
-    var _a, _b, _c;
-    switch (cond.type) {
-        case 'occurred':
-            // `submitted`, not `created` — the flat time filter's field. It is
-            // optional, so an unsubmitted snapshot matches no bound; `cmpTimestamp`
-            // returns false for an absent value, which is the same answer the flat
-            // filter's range gives.
-            return cmpTimestamp(get(doc, 'submitted'), cond.operator, cond.value, ctx);
-        case 'snapshotType': {
-            const type = get(doc, 'type');
-            const hasManifest = get(doc, 'manifest') != null;
-            return ((_a = cond.values) !== null && _a !== void 0 ? _a : []).some((wanted) => {
-                const rule = contract_1.SNAPSHOT_TYPE_RULES[wanted];
-                if (!rule)
-                    return false;
-                if (type === rule.explicit)
-                    return true;
-                // Legacy: no `type` at all, classified by the manifest's presence.
-                // Without this arm every pre-`type` snapshot silently disappears from
-                // a kind filter that the chip beside it still returns.
-                return (type == null &&
-                    rule.legacyHasManifest !== undefined &&
-                    hasManifest === rule.legacyHasManifest);
-            });
-        }
-        case 'asset':
-            // The snapshot's SUBJECT asset, not its contents — see the contract.
-            return idIn(get(doc, 'asset._id'), [cond.assetId]);
-        case 'assetType': {
-            const actual = String((_b = get(doc, 'asset.typePath')) !== null && _b !== void 0 ? _b : '');
-            return cond.includeSubtypes !== false
-                ? actual.startsWith(cond.path)
-                : actual === cond.path;
-        }
-        case 'location': {
-            // `location.path` here, NOT `location.name` as events use. Absent on
-            // legacy snapshots, which therefore match no path condition — the same
-            // acceptance record scope already makes (usergroups S7).
-            const actual = String((_c = get(doc, 'location.path')) !== null && _c !== void 0 ? _c : '');
-            if (!actual)
-                return false;
-            return cond.includeSublocations !== false
-                ? actual.startsWith(cond.path)
-                : actual === cond.path;
-        }
-        case 'manifest':
-            return idIn(get(doc, 'manifest._id'), [cond.manifestId]);
-        case 'user':
-            return idIn(get(doc, 'user._id'), resolvedIds(ctx.schema.users, cond.name));
-        case 'reader':
-            return idIn(get(doc, 'reader._id'), resolvedIds(ctx.schema.readers, cond.name));
-        default:
-            // LOUD, for the reason the event matcher gives — and more so here, since
-            // this arm running in the browser is what the user actually sees.
-            throw new Error(`semantic-query evaluator has no arm for snapshot condition ` +
-                `'${cond.type}'`);
-    }
-}
-/**
- * Reads the SERVER reader document — and, like the snapshot matcher, this is
- * PRODUCTION code: `useReaderList` holds the whole set and the list filters it
- * in memory.
- *
- * No `ctx`: every reader condition is a plain field comparison. Nothing here
- * resolves a name or a date, which is the whole reason this vocabulary is the
- * least treacherous of the four.
- */
-function matchReader(doc, cond) {
-    var _a, _b, _c;
-    switch (cond.type) {
-        case 'deviceType':
-            return ((_a = cond.values) !== null && _a !== void 0 ? _a : []).includes(get(doc, 'deviceType'));
-        case 'readerType':
-            return ((_b = cond.values) !== null && _b !== void 0 ? _b : []).includes(get(doc, 'type'));
-        case 'location': {
-            // `locationName` holds the FULL pipe path (`readers/helpers.ts` copies
-            // `location.name`, which is a location document's path). A reader with
-            // no location matches nothing rather than everything.
-            const actual = String((_c = get(doc, 'locationName')) !== null && _c !== void 0 ? _c : '');
-            if (!actual)
-                return false;
-            return cond.includeSublocations !== false
-                ? actual.startsWith(cond.path)
-                : actual === cond.path;
-        }
-        case 'attachedAsset':
-            return idIn(get(doc, 'asset'), [cond.assetId]);
-        case 'online':
-            // Strict equality against the stored boolean. A reader that has never
-            // reported has no `state` at all, so it is neither online nor offline —
-            // `hasReported` is the word for that, and conflating the two is exactly
-            // what the prototype did.
-            return get(doc, 'state.online') === cond.value;
-        case 'hasReported':
-            // `state.onlineTransTime` is the marker the flat filter uses, not
-            // `state` itself.
-            return (get(doc, 'state.onlineTransTime') !== undefined) === cond.value;
-        case 'hasGeolocation':
-            return (get(doc, 'state.geolocation') != null) === cond.value;
-        default:
-            throw new Error(`semantic-query evaluator has no arm for reader condition ` +
-                `'${cond.type}'`);
-    }
-}
-/**
- * An event's ONE timestamp against a boundary. No `includeNeverSet` branch:
- * every event has a timestamp by construction, so there is no absent case to
- * decide a polarity for.
- */
-function cmpTimestamp(actual, operator, value, ctx) {
-    if (actual === undefined || actual === null)
-        return false;
-    const ms = (0, dates_1.semanticDateBoundaryMs)(value, operator, ctx.now, ctx.tz);
-    return cmp(actual, operator, ms);
-}
-/** The event types that carry `submission.actionName`. */
-const SUBMISSION_EVENT_TYPES = ['FormSubmitted', 'FormSubmissionVoided'];
-/** Ids a name resolves to; empty when it does not resolve (validation refused it first). */
-function resolvedIds(catalogue, name) {
-    return (0, resolve_name_1.resolveName)(catalogue, name, { path: '', noun: '' }).ids;
-}
-function idIn(actual, ids) {
-    // Case-insensitive: `String(ObjectId)` is lowercase hex, but a caller-built
-    // catalogue may carry uppercase (the wire's own id check accepts either).
-    // Comparing raw would make the ORACLE miss rows the compiler matches — and
-    // an oracle that under-matches agrees with a broken compiler.
-    if (actual == null)
-        return false;
-    const a = String(actual).toLowerCase();
-    return ids.some((id) => id.toLowerCase() === a);
-}
-/**
- * Reads the SERVER document shape, as the asset matcher does — a client
- * caching parsed responses maps into it first (`evaluable-*`).
- *
- * Two words differ from their asset namesakes and both would fail silently:
- * the pipe path lives in `name` (a location document has no `path` field), and
- * `geolocation` is the CONFIGURED position at the top level, not the observed
- * `state.geolocation` an asset's condition reads.
- */
-function matchLocation(doc, cond, ctx) {
-    var _a, _b;
-    switch (cond.type) {
-        case 'path':
-            return prefixMatch(String((_a = get(doc, 'name')) !== null && _a !== void 0 ? _a : ''), cond.path, cond.includeSublocations !== false);
-        case 'locationType':
-            return ((_b = cond.values) !== null && _b !== void 0 ? _b : []).includes(get(doc, 'type'));
-        case 'hasReaders': {
-            const readers = get(doc, 'readers');
-            return (Array.isArray(readers) && readers.length > 0) === cond.value;
-        }
-        case 'geofence': {
-            // `!= null` is deliberate (missing OR explicit null), matching the
-            // compiler's `{geofence: null}` partition exactly. `!== undefined` alone
-            // would put a null geofence on the opposite side from Mongo.
-            const v = get(doc, 'geofence');
-            return cond.exists ? v != null : v == null;
-        }
-        case 'manifest': {
-            const ids = get(doc, 'manifestIds');
-            return Array.isArray(ids) && ids.some((id) => String(id) === cond.manifestId);
-        }
-        case 'geolocation': {
-            const v = get(doc, 'geolocation');
-            return cond.exists !== false ? v !== undefined : v === undefined;
-        }
-        case 'tags':
-            return matchTags(doc, cond);
-        // No lastSeen / firstSeen / telemetry — see the vocabulary in the contract.
-        case 'createdDate':
-        case 'lastUpdated':
-        case 'lastChanged':
-            return matchTimestamp(doc, cond, ctx);
-        default:
-            return false;
-    }
-}
-function matchTags(doc, cond) {
-    var _a, _b;
-    const tags = ((_a = doc.tagIds) !== null && _a !== void 0 ? _a : []).map(String);
-    const want = ((_b = cond.values) !== null && _b !== void 0 ? _b : []).map(String);
-    return cond.operator === 'all'
-        ? want.every((t) => tags.includes(t))
-        : want.some((t) => tags.includes(t));
-}
-function matchAsset(doc, cond, ctx) {
-    var _a, _b, _c, _d;
-    switch (cond.type) {
-        case 'and':
-            return cond.conditions.every((c) => match(doc, c, ctx));
-        case 'or':
-            return cond.conditions.some((c) => match(doc, c, ctx));
-        case 'assetType':
-            return prefixMatch(String((_a = get(doc, 'typePath')) !== null && _a !== void 0 ? _a : ''), cond.path, cond.includeSubtypes !== false);
-        case 'location':
-            return prefixMatch(String((_b = get(doc, 'state.locationName')) !== null && _b !== void 0 ? _b : ''), cond.path, cond.includeSublocations !== false);
-        case 'homeLocation':
-            return prefixMatch(String((_c = get(doc, 'homeLocationPath')) !== null && _c !== void 0 ? _c : ''), cond.path, cond.includeSublocations !== false);
-        case 'withAsset': {
-            const v = get(doc, 'state.locationWithId');
-            if (cond.hasAny !== undefined)
-                return (v !== undefined && v !== null) === cond.hasAny;
-            return v != null && String(v) === cond.assetId;
-        }
-        case 'geolocation': {
-            const v = get(doc, 'state.geolocation');
-            return cond.exists !== false ? v !== undefined : v === undefined;
-        }
-        case 'tags':
-            return matchTags(doc, cond);
-        case 'telemetry':
-            return cmp(get(doc, `telemetry.${cond.field}`), cond.operator, cond.value);
-        case 'readiness': {
-            const levels = (_d = cond.levels) !== null && _d !== void 0 ? _d : (cond.level === undefined ? [] : [cond.level]);
-            // Missing readiness ≡ green (0).
-            const actual = get(doc, 'readiness.ready');
-            const effective = typeof actual === 'number' ? actual : 0;
-            return levels.includes(effective);
-        }
-        case 'kit': {
-            if (cond.parentAssetId !== undefined) {
-                const p = get(doc, 'groupParentId');
-                return p != null && String(p) === cond.parentAssetId;
-            }
-            if (cond.isKit !== undefined)
-                return (doc.typeKit === true) === cond.isKit;
-            if (cond.isMember !== undefined)
-                return (doc.groupMember === true) === cond.isMember;
-            // Three-valued, unlike the two flags above: `groupSatisfiesKit` is only
-            // set when the asset IS a kit, its type carries a manifest template, and
-            // that template declares requirements (groups/satisfies.ts). Absent means
-            // the question does not apply — so it is neither satisfied NOR
-            // unsatisfied, and an exact match answers both directions.
-            return doc.groupSatisfiesKit === cond.satisfied;
-        }
-        case 'locationStatus': {
-            const status = get(doc, 'state.locationStatus');
-            if (typeof status === 'string' && cond.values.includes(status))
-                return true;
-            // NEVERSEEN also means "no state at all".
-            return cond.values.includes('NEVERSEEN') && get(doc, 'state') === undefined;
-        }
-        case 'createdDate':
-        case 'lastUpdated':
-        case 'lastChanged':
-        case 'lastSeen':
-        case 'firstSeen':
-            return matchTimestamp(doc, cond, ctx);
-        case 'customField':
-            return matchCustomField(doc, cond, ctx);
-        default:
-            return false;
-    }
-}
-function prefixMatch(actual, path, includeDescendants) {
-    return includeDescendants ? actual.startsWith(path) : actual === path;
-}
-const TIMESTAMP_FIELD = {
-    lastUpdated: 'lastUpdated',
-    lastChanged: 'lastChanged',
-    lastSeen: 'state.lastSeen',
-    firstSeen: 'state.firstSeen',
-};
-function matchTimestamp(doc, cond, ctx) {
-    const ms = (0, dates_1.semanticDateBoundaryMs)(cond.value, cond.operator, ctx.now, ctx.tz);
-    if (cond.type === 'createdDate') {
-        // The ObjectId's first 4 bytes are the creation time in SECONDS. The
-        // compiler steps `lte`/`gt` to the next second (a zero-tail boundary id
-        // sorts before every real id in the same second); mirror that exactly,
-        // or documents created within the boundary second classify differently.
-        const created = parseInt(String(doc._id).slice(0, 8), 16);
-        const second = Math.floor(ms / 1000);
-        switch (cond.operator) {
-            case 'gte':
-                return created >= second;
-            case 'lt':
-                return created < second;
-            case 'lte':
-                return created < second + 1;
-            default: // gt
-                return created >= second + 1;
-        }
-    }
-    const actual = get(doc, TIMESTAMP_FIELD[cond.type]);
-    const neverSet = actual === undefined || actual === null;
-    if (neverSet) {
-        return ((cond.operator === 'lt' || cond.operator === 'lte') &&
-            cond.includeNeverSet !== false);
-    }
-    return cmp(actual, cond.operator, ms);
-}
-// ---------------------------------------------------------------------------
-// Custom fields — mirror of the compiler's two-container conjunct
-// ---------------------------------------------------------------------------
-/**
- * Every value the field holds in this container.
- *
- * Matched by field `_id` ONLY — the compiler's `$elemMatch: {_id: …}` cannot
- * match a name — and ALL matching entries are returned, because `$elemMatch`
- * is existential: a duplicated field where one entry is null and another
- * holds the value must match, so inspecting only the first entry would
- * disagree with Mongo.
- */
-function valuesFor(entries, fdef, slot) {
-    return (entries !== null && entries !== void 0 ? entries : [])
-        .filter((e) => (e === null || e === void 0 ? void 0 : e._id) !== undefined && String(e._id) === fdef.id)
-        .map((e) => e[slot]);
-}
-function isPresent(v) {
-    return v !== undefined && v !== null && v !== '';
-}
-function matchCustomField(doc, cond, ctx) {
-    var _a;
-    const fdef = ctx.fieldByName.get(String(cond.fieldName).toLowerCase());
-    if (!fdef)
-        return false;
-    const slot = SLOT[fdef.dataType];
-    // The in-memory equivalent of the joinedType $lookup: the asset's own
-    // fieldValues entries, and its type's inheritance-resolved entries.
-    const type = ctx.typeById.get(String(doc.typeId));
-    const values = [
-        ...valuesFor(doc.fieldValues, fdef, slot),
-        ...valuesFor(type === null || type === void 0 ? void 0 : type.typeFieldValuesAll, fdef, slot),
-    ];
-    const anyPresent = values.some(isPresent);
-    switch (cond.operator) {
-        case 'exists':
-            return anyPresent;
-        case 'notExists':
-            return !anyPresent;
-        case 'contains': {
-            const term = String((_a = cond.value) !== null && _a !== void 0 ? _a : '').toLowerCase();
-            return values.some((v) => isPresent(v) && String(v).toLowerCase().includes(term));
-        }
-        default:
-            break;
-    }
-    // The SAME coercion the Mongo compiler applies — shared, not mirrored.
-    // A numeric literal for a text field, or a relative date for a DATE field,
-    // has to become one concrete value; two copies of this rule would classify
-    // the same document differently.
-    const target = (0, validate_1.coerceSemanticValue)(cond.value, fdef.dataType, ctx.now, ctx.tz);
-    if (cond.operator === 'ne') {
-        // Present-and-different at either level; default also counts fully unset.
-        const strict = values.some((v) => isPresent(v) && v !== target);
-        return cond.includeUnset === false ? strict : strict || !anyPresent;
-    }
-    return values.some((v) => cmp(v, cond.operator, target));
-}
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.evaluateSemanticQuery = void 0;
+// Workspace Dependencies
+const contract_1 = require("@spotto/contract");
+// Project Dependencies
+const dates_1 = require("./dates");
+const resolve_name_1 = require("./resolve-name");
+const validate_1 = require("./validate");
+const SLOT = {
+    STRING: 'valueString',
+    INTEGER: 'valueInteger',
+    DECIMAL: 'valueDecimal',
+    BOOLEAN: 'valueBoolean',
+    DATE: 'valueDate',
+};
+function get(doc, path) {
+    return path.split('.').reduce((a, k) => (a == null ? undefined : a[k]), doc);
+}
+function cmp(actual, op, target) {
+    if (actual === undefined || actual === null)
+        return false;
+    switch (op) {
+        case 'eq':
+            return actual === target;
+        case 'ne':
+            return actual !== target;
+        case 'gt':
+            return actual > target;
+        case 'gte':
+            return actual >= target;
+        case 'lt':
+            return actual < target;
+        case 'lte':
+            return actual <= target;
+        default:
+            return false;
+    }
+}
+function evaluateSemanticQuery(query, docs, schema, opts = {}) {
+    var _a, _b, _c;
+    const ctx = {
+        schema,
+        now: (_a = opts.now) !== null && _a !== void 0 ? _a : new Date(),
+        tz: (_b = opts.timeZone) !== null && _b !== void 0 ? _b : 'UTC',
+        fieldByName: new Map(schema.fields.map((f) => [f.name.toLowerCase(), f])),
+        typeById: new Map(schema.types.map((t) => [t.id, t])),
+        entityType: (_c = opts.entityType) !== null && _c !== void 0 ? _c : 'asset',
+    };
+    return docs.filter((d) => query.conditions.every((c) => match(d, c, ctx)));
+}
+exports.evaluateSemanticQuery = evaluateSemanticQuery;
+/**
+ * Grouping is shared — it is structure, not subject matter — and everything
+ * else dispatches to the entity's own matcher, mirroring the Mongo compiler so
+ * the two engines are organised the same way and can be read side by side.
+ */
+function match(doc, cond, ctx) {
+    if (cond.type === 'and')
+        return cond.conditions.every((c) => match(doc, c, ctx));
+    if (cond.type === 'or')
+        return cond.conditions.some((c) => match(doc, c, ctx));
+    if (ctx.entityType === 'location') {
+        return matchLocation(doc, cond, ctx);
+    }
+    if (ctx.entityType === 'event') {
+        return matchEvent(doc, cond, ctx);
+    }
+    if (ctx.entityType === 'snapshot') {
+        return matchSnapshot(doc, cond, ctx);
+    }
+    if (ctx.entityType === 'reader') {
+        return matchReader(doc, cond);
+    }
+    return matchAsset(doc, cond, ctx);
+}
+/**
+ * Reads the SERVER event document. Events are never evaluated in the browser —
+ * the client caches query RESULTS, not events, so there is no corpus to run
+ * over. This matcher exists as the ORACLE: the acceptance property
+ * `evaluate(q, docs) === find(compile(q))` is what catches an encoding mistake
+ * in the Mongo compiler, and an entity with no second implementation has
+ * nothing checking it but the person who wrote it.
+ *
+ * The three name-resolved words compare against the ids VALIDATION already
+ * resolved, from the same catalogue the compiler uses — so the two engines
+ * cannot disagree about who "Sarah" is.
+ */
+function matchEvent(doc, cond, ctx) {
+    var _a, _b, _c, _d, _e;
+    switch (cond.type) {
+        case 'occurred':
+            return cmpTimestamp(get(doc, 'timestamp'), cond.operator, cond.value, ctx);
+        case 'eventType':
+            return ((_a = cond.values) !== null && _a !== void 0 ? _a : []).includes(get(doc, 'type'));
+        case 'assetType': {
+            // BOTH halves, exactly as `action` below and exactly as the compiler:
+            // `thing` is a full asset only on the CRUD events, so the type scope is
+            // part of the condition rather than something a caller must remember.
+            // Checked FIRST — a movement event has no `thing.typePath` at all, and
+            // reading one would only ever produce a confusing miss.
+            if (!contract_1.ASSET_CRUD_EVENT_TYPES.includes(String(get(doc, 'type')))) {
+                return false;
+            }
+            const actual = String((_b = get(doc, 'thing.typePath')) !== null && _b !== void 0 ? _b : '');
+            return cond.includeSubtypes !== false
+                ? actual.startsWith(cond.path)
+                : actual === cond.path;
+        }
+        case 'location': {
+            // The stored pipe path, exactly as a location document keeps it — events
+            // embed it under `location.name`.
+            const actual = String((_c = get(doc, 'location.name')) !== null && _c !== void 0 ? _c : '');
+            return cond.includeSublocations !== false
+                ? actual.startsWith(cond.path)
+                : actual === cond.path;
+        }
+        case 'reader':
+            return idIn(get(doc, 'reader._id'), resolvedIds(ctx.schema.readers, cond.name));
+        case 'user':
+            // A resolved user id inherently excludes system-generated events — Slate
+            // movements carry no user at all, and must never answer "what did X do".
+            return idIn(get(doc, 'user._id'), resolvedIds(ctx.schema.users, cond.name));
+        case 'action': {
+            // An action implies a submission, so both halves are checked — matching
+            // the compiler, which constrains the type for the same reason.
+            // Both submission types — see the compiler's note.
+            if (!SUBMISSION_EVENT_TYPES.includes(String(get(doc, 'type'))))
+                return false;
+            // Resolve ONCE — resolving inside the predicate re-ran it per action.
+            const ids = resolvedIds(ctx.schema.actions, cond.name);
+            const names = ((_d = ctx.schema.actions) !== null && _d !== void 0 ? _d : [])
+                .filter((a) => ids.includes(a.id))
+                .map((a) => a.name);
+            return names.includes(String((_e = get(doc, 'submission.actionName')) !== null && _e !== void 0 ? _e : ''));
+        }
+        default:
+            // LOUD, not false. This function is the ORACLE the Mongo compiler is
+            // checked against, and an oracle that silently matches nothing AGREES
+            // with a compiler that returns nothing — so a word added to the
+            // vocabulary and the compiler but forgotten here would let the
+            // differential check pass by both engines being wrong together.
+            throw new Error(`semantic-query evaluator has no arm for event condition ` +
+                `'${cond.type}'`);
+    }
+}
+/**
+ * Reads the SERVER snapshot document.
+ *
+ * Unlike the event matcher, this one is NOT only an oracle — it is the
+ * production path. Snapshots are cached whole and the list filters them in the
+ * browser (`useSnapshotList` → `db.snapshots.toArray()`), so a mistake here is
+ * a wrong answer a user sees, not a test that fails. The Mongo compiler still
+ * has to agree with it for saved queries and widgets.
+ *
+ * Two arms below are not the obvious reading of the field, and both are
+ * copied from the flat filter (`snapshots/filters.ts`) rather than invented,
+ * because chip and query must return the same rows.
+ */
+function matchSnapshot(doc, cond, ctx) {
+    var _a, _b, _c;
+    switch (cond.type) {
+        case 'occurred':
+            // `submitted`, not `created` — the flat time filter's field. It is
+            // optional, so an unsubmitted snapshot matches no bound; `cmpTimestamp`
+            // returns false for an absent value, which is the same answer the flat
+            // filter's range gives.
+            return cmpTimestamp(get(doc, 'submitted'), cond.operator, cond.value, ctx);
+        case 'snapshotType': {
+            const type = get(doc, 'type');
+            const hasManifest = get(doc, 'manifest') != null;
+            return ((_a = cond.values) !== null && _a !== void 0 ? _a : []).some((wanted) => {
+                const rule = contract_1.SNAPSHOT_TYPE_RULES[wanted];
+                if (!rule)
+                    return false;
+                if (type === rule.explicit)
+                    return true;
+                // Legacy: no `type` at all, classified by the manifest's presence.
+                // Without this arm every pre-`type` snapshot silently disappears from
+                // a kind filter that the chip beside it still returns.
+                return (type == null &&
+                    rule.legacyHasManifest !== undefined &&
+                    hasManifest === rule.legacyHasManifest);
+            });
+        }
+        case 'asset':
+            // The snapshot's SUBJECT asset, not its contents — see the contract.
+            return idIn(get(doc, 'asset._id'), [cond.assetId]);
+        case 'assetType': {
+            const actual = String((_b = get(doc, 'asset.typePath')) !== null && _b !== void 0 ? _b : '');
+            return cond.includeSubtypes !== false
+                ? actual.startsWith(cond.path)
+                : actual === cond.path;
+        }
+        case 'location': {
+            // `location.path` here, NOT `location.name` as events use. Absent on
+            // legacy snapshots, which therefore match no path condition — the same
+            // acceptance record scope already makes (usergroups S7).
+            const actual = String((_c = get(doc, 'location.path')) !== null && _c !== void 0 ? _c : '');
+            if (!actual)
+                return false;
+            return cond.includeSublocations !== false
+                ? actual.startsWith(cond.path)
+                : actual === cond.path;
+        }
+        case 'manifest': {
+            // Mirrors the compiler byte-for-byte: `satisfied` is an exact match on
+            // the frozen `c_satisfiesManifest` annotation — a snapshot that never
+            // stamped a verdict carries no flag and matches NEITHER polarity. Both
+            // keys AND together when present; the validator guarantees at least
+            // one, so reaching the end means every present key matched.
+            if (cond.manifestId !== undefined &&
+                !idIn(get(doc, 'manifest._id'), [cond.manifestId])) {
+                return false;
+            }
+            if (cond.satisfied !== undefined &&
+                get(doc, 'c_satisfiesManifest') !== cond.satisfied) {
+                return false;
+            }
+            return true;
+        }
+        case 'user':
+            return idIn(get(doc, 'user._id'), resolvedIds(ctx.schema.users, cond.name));
+        case 'reader':
+            return idIn(get(doc, 'reader._id'), resolvedIds(ctx.schema.readers, cond.name));
+        default:
+            // LOUD, for the reason the event matcher gives — and more so here, since
+            // this arm running in the browser is what the user actually sees.
+            throw new Error(`semantic-query evaluator has no arm for snapshot condition ` +
+                `'${cond.type}'`);
+    }
+}
+/**
+ * Reads the SERVER reader document — and, like the snapshot matcher, this is
+ * PRODUCTION code: `useReaderList` holds the whole set and the list filters it
+ * in memory.
+ *
+ * No `ctx`: every reader condition is a plain field comparison. Nothing here
+ * resolves a name or a date, which is the whole reason this vocabulary is the
+ * least treacherous of the four.
+ */
+function matchReader(doc, cond) {
+    var _a, _b, _c;
+    switch (cond.type) {
+        case 'deviceType':
+            return ((_a = cond.values) !== null && _a !== void 0 ? _a : []).includes(get(doc, 'deviceType'));
+        case 'readerType':
+            return ((_b = cond.values) !== null && _b !== void 0 ? _b : []).includes(get(doc, 'type'));
+        case 'location': {
+            // `locationName` holds the FULL pipe path (`readers/helpers.ts` copies
+            // `location.name`, which is a location document's path). A reader with
+            // no location matches nothing rather than everything.
+            const actual = String((_c = get(doc, 'locationName')) !== null && _c !== void 0 ? _c : '');
+            if (!actual)
+                return false;
+            return cond.includeSublocations !== false
+                ? actual.startsWith(cond.path)
+                : actual === cond.path;
+        }
+        case 'attachedAsset':
+            return idIn(get(doc, 'asset'), [cond.assetId]);
+        case 'online':
+            // Strict equality against the stored boolean. A reader that has never
+            // reported has no `state` at all, so it is neither online nor offline —
+            // `hasReported` is the word for that, and conflating the two is exactly
+            // what the prototype did.
+            return get(doc, 'state.online') === cond.value;
+        case 'hasReported':
+            // `state.onlineTransTime` is the marker the flat filter uses, not
+            // `state` itself.
+            return (get(doc, 'state.onlineTransTime') !== undefined) === cond.value;
+        case 'hasGeolocation':
+            return (get(doc, 'state.geolocation') != null) === cond.value;
+        default:
+            throw new Error(`semantic-query evaluator has no arm for reader condition ` +
+                `'${cond.type}'`);
+    }
+}
+/**
+ * An event's ONE timestamp against a boundary. No `includeNeverSet` branch:
+ * every event has a timestamp by construction, so there is no absent case to
+ * decide a polarity for.
+ */
+function cmpTimestamp(actual, operator, value, ctx) {
+    if (actual === undefined || actual === null)
+        return false;
+    const ms = (0, dates_1.semanticDateBoundaryMs)(value, operator, ctx.now, ctx.tz);
+    return cmp(actual, operator, ms);
+}
+/** The event types that carry `submission.actionName`. */
+const SUBMISSION_EVENT_TYPES = ['FormSubmitted', 'FormSubmissionVoided'];
+/** Ids a name resolves to; empty when it does not resolve (validation refused it first). */
+function resolvedIds(catalogue, name) {
+    return (0, resolve_name_1.resolveName)(catalogue, name, { path: '', noun: '' }).ids;
+}
+function idIn(actual, ids) {
+    // Case-insensitive: `String(ObjectId)` is lowercase hex, but a caller-built
+    // catalogue may carry uppercase (the wire's own id check accepts either).
+    // Comparing raw would make the ORACLE miss rows the compiler matches — and
+    // an oracle that under-matches agrees with a broken compiler.
+    if (actual == null)
+        return false;
+    const a = String(actual).toLowerCase();
+    return ids.some((id) => id.toLowerCase() === a);
+}
+/**
+ * Reads the SERVER document shape, as the asset matcher does — a client
+ * caching parsed responses maps into it first (`evaluable-*`).
+ *
+ * Two words differ from their asset namesakes and both would fail silently:
+ * the pipe path lives in `name` (a location document has no `path` field), and
+ * `geolocation` is the CONFIGURED position at the top level, not the observed
+ * `state.geolocation` an asset's condition reads.
+ */
+function matchLocation(doc, cond, ctx) {
+    var _a, _b;
+    switch (cond.type) {
+        case 'path':
+            return prefixMatch(String((_a = get(doc, 'name')) !== null && _a !== void 0 ? _a : ''), cond.path, cond.includeSublocations !== false);
+        case 'locationType':
+            return ((_b = cond.values) !== null && _b !== void 0 ? _b : []).includes(get(doc, 'type'));
+        case 'hasReaders': {
+            const readers = get(doc, 'readers');
+            return (Array.isArray(readers) && readers.length > 0) === cond.value;
+        }
+        case 'geofence': {
+            // `!= null` is deliberate (missing OR explicit null), matching the
+            // compiler's `{geofence: null}` partition exactly. `!== undefined` alone
+            // would put a null geofence on the opposite side from Mongo.
+            const v = get(doc, 'geofence');
+            return cond.exists ? v != null : v == null;
+        }
+        case 'manifest': {
+            const ids = get(doc, 'manifestIds');
+            return Array.isArray(ids) && ids.some((id) => String(id) === cond.manifestId);
+        }
+        case 'geolocation': {
+            const v = get(doc, 'geolocation');
+            return cond.exists !== false ? v !== undefined : v === undefined;
+        }
+        case 'tags':
+            return matchTags(doc, cond);
+        // No lastSeen / firstSeen / telemetry — see the vocabulary in the contract.
+        case 'createdDate':
+        case 'lastUpdated':
+        case 'lastChanged':
+            return matchTimestamp(doc, cond, ctx);
+        default:
+            return false;
+    }
+}
+function matchTags(doc, cond) {
+    var _a, _b;
+    const tags = ((_a = doc.tagIds) !== null && _a !== void 0 ? _a : []).map(String);
+    const want = ((_b = cond.values) !== null && _b !== void 0 ? _b : []).map(String);
+    return cond.operator === 'all'
+        ? want.every((t) => tags.includes(t))
+        : want.some((t) => tags.includes(t));
+}
+function matchAsset(doc, cond, ctx) {
+    var _a, _b, _c, _d;
+    switch (cond.type) {
+        case 'and':
+            return cond.conditions.every((c) => match(doc, c, ctx));
+        case 'or':
+            return cond.conditions.some((c) => match(doc, c, ctx));
+        case 'assetType':
+            return prefixMatch(String((_a = get(doc, 'typePath')) !== null && _a !== void 0 ? _a : ''), cond.path, cond.includeSubtypes !== false);
+        case 'location':
+            return prefixMatch(String((_b = get(doc, 'state.locationName')) !== null && _b !== void 0 ? _b : ''), cond.path, cond.includeSublocations !== false);
+        case 'homeLocation':
+            return prefixMatch(String((_c = get(doc, 'homeLocationPath')) !== null && _c !== void 0 ? _c : ''), cond.path, cond.includeSublocations !== false);
+        case 'withAsset': {
+            const v = get(doc, 'state.locationWithId');
+            if (cond.hasAny !== undefined)
+                return (v !== undefined && v !== null) === cond.hasAny;
+            return v != null && String(v) === cond.assetId;
+        }
+        case 'geolocation': {
+            const v = get(doc, 'state.geolocation');
+            return cond.exists !== false ? v !== undefined : v === undefined;
+        }
+        case 'tags':
+            return matchTags(doc, cond);
+        case 'telemetry':
+            return cmp(get(doc, `telemetry.${cond.field}`), cond.operator, cond.value);
+        case 'readiness': {
+            const levels = (_d = cond.levels) !== null && _d !== void 0 ? _d : (cond.level === undefined ? [] : [cond.level]);
+            // Missing readiness ≡ green (0).
+            const actual = get(doc, 'readiness.ready');
+            const effective = typeof actual === 'number' ? actual : 0;
+            return levels.includes(effective);
+        }
+        case 'kit': {
+            if (cond.parentAssetId !== undefined) {
+                const p = get(doc, 'groupParentId');
+                return p != null && String(p) === cond.parentAssetId;
+            }
+            if (cond.isKit !== undefined)
+                return (doc.typeKit === true) === cond.isKit;
+            if (cond.isMember !== undefined)
+                return (doc.groupMember === true) === cond.isMember;
+            // The 4-state manifest-check status, mirroring the Mongo compile
+            // exactly — `neverChecked` carries the same typeKit self-scope, and
+            // every state requires `hasManifest` (a stored status outlives a
+            // manifest detach as inert history; the gate keeps the filter agreeing
+            // with the display).
+            if (cond.manifest !== undefined) {
+                if (doc.hasManifest !== true)
+                    return false;
+                const status = doc.groupSatisfiesManifest;
+                switch (cond.manifest) {
+                    case 'satisfied':
+                        return status === 0;
+                    case 'needsRecheck':
+                        return status === 1;
+                    case 'notSatisfied':
+                        return status === 2;
+                    case 'neverChecked':
+                        return doc.typeKit === true && status === undefined;
+                }
+            }
+            // Legacy `satisfied` boolean over the 4-state `groupSatisfiesManifest`
+            // (0 satisfied · 1 needs-recheck · 2 not satisfied · absent never
+            // checked): true → 0, false → 2, exactly mirroring the Mongo compile —
+            // including its `hasManifest` gate. Exact value matches — absent means
+            // no manifest check has ever stamped the field, so it is neither
+            // satisfied NOR unsatisfied.
+            return (doc.hasManifest === true &&
+                doc.groupSatisfiesManifest === (cond.satisfied ? 0 : 2));
+        }
+        case 'locationStatus': {
+            const status = get(doc, 'state.locationStatus');
+            if (typeof status === 'string' && cond.values.includes(status))
+                return true;
+            // NEVERSEEN also means "no state at all".
+            return cond.values.includes('NEVERSEEN') && get(doc, 'state') === undefined;
+        }
+        case 'createdDate':
+        case 'lastUpdated':
+        case 'lastChanged':
+        case 'lastSeen':
+        case 'firstSeen':
+            return matchTimestamp(doc, cond, ctx);
+        case 'customField':
+            return matchCustomField(doc, cond, ctx);
+        default:
+            return false;
+    }
+}
+function prefixMatch(actual, path, includeDescendants) {
+    return includeDescendants ? actual.startsWith(path) : actual === path;
+}
+const TIMESTAMP_FIELD = {
+    lastUpdated: 'lastUpdated',
+    lastChanged: 'lastChanged',
+    lastSeen: 'state.lastSeen',
+    firstSeen: 'state.firstSeen',
+};
+function matchTimestamp(doc, cond, ctx) {
+    const ms = (0, dates_1.semanticDateBoundaryMs)(cond.value, cond.operator, ctx.now, ctx.tz);
+    if (cond.type === 'createdDate') {
+        // The ObjectId's first 4 bytes are the creation time in SECONDS. The
+        // compiler steps `lte`/`gt` to the next second (a zero-tail boundary id
+        // sorts before every real id in the same second); mirror that exactly,
+        // or documents created within the boundary second classify differently.
+        const created = parseInt(String(doc._id).slice(0, 8), 16);
+        const second = Math.floor(ms / 1000);
+        switch (cond.operator) {
+            case 'gte':
+                return created >= second;
+            case 'lt':
+                return created < second;
+            case 'lte':
+                return created < second + 1;
+            default: // gt
+                return created >= second + 1;
+        }
+    }
+    const actual = get(doc, TIMESTAMP_FIELD[cond.type]);
+    const neverSet = actual === undefined || actual === null;
+    if (neverSet) {
+        return ((cond.operator === 'lt' || cond.operator === 'lte') &&
+            cond.includeNeverSet !== false);
+    }
+    return cmp(actual, cond.operator, ms);
+}
+// ---------------------------------------------------------------------------
+// Custom fields — mirror of the compiler's two-container conjunct
+// ---------------------------------------------------------------------------
+/**
+ * Every value the field holds in this container.
+ *
+ * Matched by field `_id` ONLY — the compiler's `$elemMatch: {_id: …}` cannot
+ * match a name — and ALL matching entries are returned, because `$elemMatch`
+ * is existential: a duplicated field where one entry is null and another
+ * holds the value must match, so inspecting only the first entry would
+ * disagree with Mongo.
+ */
+function valuesFor(entries, fdef, slot) {
+    return (entries !== null && entries !== void 0 ? entries : [])
+        .filter((e) => (e === null || e === void 0 ? void 0 : e._id) !== undefined && String(e._id) === fdef.id)
+        .map((e) => e[slot]);
+}
+function isPresent(v) {
+    return v !== undefined && v !== null && v !== '';
+}
+function matchCustomField(doc, cond, ctx) {
+    var _a;
+    const fdef = ctx.fieldByName.get(String(cond.fieldName).toLowerCase());
+    if (!fdef)
+        return false;
+    const slot = SLOT[fdef.dataType];
+    // The in-memory equivalent of the joinedType $lookup: the asset's own
+    // fieldValues entries, and its type's inheritance-resolved entries.
+    const type = ctx.typeById.get(String(doc.typeId));
+    const values = [
+        ...valuesFor(doc.fieldValues, fdef, slot),
+        ...valuesFor(type === null || type === void 0 ? void 0 : type.typeFieldValuesAll, fdef, slot),
+    ];
+    const anyPresent = values.some(isPresent);
+    switch (cond.operator) {
+        case 'exists':
+            return anyPresent;
+        case 'notExists':
+            return !anyPresent;
+        case 'contains': {
+            const term = String((_a = cond.value) !== null && _a !== void 0 ? _a : '').toLowerCase();
+            return values.some((v) => isPresent(v) && String(v).toLowerCase().includes(term));
+        }
+        default:
+            break;
+    }
+    // The SAME coercion the Mongo compiler applies — shared, not mirrored.
+    // A numeric literal for a text field, or a relative date for a DATE field,
+    // has to become one concrete value; two copies of this rule would classify
+    // the same document differently.
+    const target = (0, validate_1.coerceSemanticValue)(cond.value, fdef.dataType, ctx.now, ctx.tz);
+    if (cond.operator === 'ne') {
+        // Present-and-different at either level; default also counts fully unset.
+        const strict = values.some((v) => isPresent(v) && v !== target);
+        return cond.includeUnset === false ? strict : strict || !anyPresent;
+    }
+    return values.some((v) => cmp(v, cond.operator, target));
+}
 //# sourceMappingURL=evaluate.js.map