@spotto/semantic-query 1.0.70-alpha.18

package/dist/fixtures.js

@@ -0,0 +1,156 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.FIXTURE_OPTS = exports.FIXTURE_TZ = exports.FIXTURE_NOW = exports.FIXTURE_CORPUS = exports.FIXTURE_NULLS = exports.FIXTURE_AMBULANCE = exports.FIXTURE_FRIDGE = exports.FIXTURE_EPOC = exports.FIXTURE_SCHEMA = exports.FIXTURE_KIT_PARENT = exports.FIXTURE_MANIFEST = exports.FIXTURE_TYPES = exports.FIXTURE_FIELDS = void 0;
+/**
+ * The conformance corpus.
+ *
+ * Shipped as part of the package, on its own entry point
+ * (`@spotto/semantic-query/dist/fixtures`), because it is not test scaffolding
+ * — it is the shared statement of the awkward cases every back-end must
+ * classify identically. The server's Mongo compiler runs against it, and so
+ * does anything else that ever claims to execute this language.
+ *
+ * Deliberately small and hand-readable. Each document exists for a reason
+ * stated beside it; a corpus nobody can hold in their head stops being
+ * evidence and starts being decoration.
+ */
+exports.FIXTURE_FIELDS = {
+    SERIAL: 'aaaaaaaaaaaaaaaaaaaaaa01',
+    MANUFACTURER: 'aaaaaaaaaaaaaaaaaaaaaa02',
+    OWNERSHIP: 'aaaaaaaaaaaaaaaaaaaaaa03',
+    PURCHASE_DATE: 'aaaaaaaaaaaaaaaaaaaaaa04',
+    DECOMMISSIONED: 'aaaaaaaaaaaaaaaaaaaaaa05',
+    CALIBRATED_AT: 'aaaaaaaaaaaaaaaaaaaaaa06',
+};
+exports.FIXTURE_TYPES = {
+    EPOC: 'bbbbbbbbbbbbbbbbbbbbbb01',
+    FRIDGE: 'bbbbbbbbbbbbbbbbbbbbbb02',
+    AMBULANCE: 'bbbbbbbbbbbbbbbbbbbbbb03',
+};
+exports.FIXTURE_MANIFEST = 'cccccccccccccccccccccc01';
+exports.FIXTURE_KIT_PARENT = 'dddddddddddddddddddddd01';
+/**
+ * One organisation's catalogue: every supported data type, a dropdown with
+ * options, a type-level value (Manufacturer, which no asset carries directly),
+ * and a DATETIME field that must be refused rather than matched.
+ */
+exports.FIXTURE_SCHEMA = {
+    fields: [
+        { id: exports.FIXTURE_FIELDS.SERIAL, name: 'SerialNumber', dataType: 'STRING' },
+        { id: exports.FIXTURE_FIELDS.MANUFACTURER, name: 'Manufacturer', dataType: 'STRING' },
+        {
+            id: exports.FIXTURE_FIELDS.OWNERSHIP,
+            name: 'Ownership',
+            dataType: 'STRING',
+            options: ['QH', 'LFA'],
+        },
+        { id: exports.FIXTURE_FIELDS.PURCHASE_DATE, name: 'PurchaseDate', dataType: 'DATE' },
+        { id: exports.FIXTURE_FIELDS.DECOMMISSIONED, name: 'Decommissioned', dataType: 'BOOLEAN' },
+        { id: exports.FIXTURE_FIELDS.CALIBRATED_AT, name: 'CalibratedAt', dataType: 'DATETIME' },
+    ],
+    types: [
+        {
+            id: exports.FIXTURE_TYPES.EPOC,
+            path: 'Blood Analysers|EPOC|',
+            typeFieldValuesAll: [
+                {
+                    _id: exports.FIXTURE_FIELDS.MANUFACTURER,
+                    name: 'Manufacturer',
+                    valueString: 'ABBOTT DIAGNOSTICS',
+                },
+            ],
+        },
+        {
+            id: exports.FIXTURE_TYPES.FRIDGE,
+            path: 'Blood Refrigerators|',
+            typeFieldValuesAll: [
+                {
+                    _id: exports.FIXTURE_FIELDS.MANUFACTURER,
+                    name: 'Manufacturer',
+                    valueString: 'Advanced Health Technology',
+                },
+            ],
+        },
+        { id: exports.FIXTURE_TYPES.AMBULANCE, path: 'Vehicles|Ambulance|', typeFieldValuesAll: [] },
+    ],
+};
+/** Carries a value for everything; its Manufacturer comes from its TYPE, not itself. */
+exports.FIXTURE_EPOC = {
+    _id: '650000000000000000000001',
+    name: 'EPOC Analyser 7',
+    typeId: exports.FIXTURE_TYPES.EPOC,
+    typePath: 'Blood Analysers|EPOC|',
+    fieldValues: [
+        { _id: exports.FIXTURE_FIELDS.SERIAL, name: 'SerialNumber', valueString: 'ABC123' },
+        { _id: exports.FIXTURE_FIELDS.OWNERSHIP, name: 'Ownership', valueString: 'QH' },
+        { _id: exports.FIXTURE_FIELDS.PURCHASE_DATE, name: 'PurchaseDate', valueDate: 20260815 },
+    ],
+    state: {
+        locationName: 'Brisbane|Lab|',
+        locationStatus: 'HOME',
+        lastSeen: 1780000000000,
+        supportsWith: true,
+        locationWithId: exports.FIXTURE_KIT_PARENT,
+    },
+    readiness: { ready: 2, readyIssues: [{ reason: 'Overdue' }] },
+    tagIds: ['E28011700000021A2C5B0001'],
+    labels: [{ name: 'Loan pool' }],
+    manifestIds: [exports.FIXTURE_MANIFEST],
+    lastUpdated: 1700000000000,
+    lastChanged: 1780000000000,
+    groupMember: true,
+};
+/** The sparse asset: no state, no readiness, no tags, never updated. */
+exports.FIXTURE_FRIDGE = {
+    _id: '650000000000000000000002',
+    name: 'Blood Fridge 2',
+    typeId: exports.FIXTURE_TYPES.FRIDGE,
+    typePath: 'Blood Refrigerators|',
+    fieldValues: [],
+    tagIds: [],
+};
+/** A kit, dispatched, whose members fall short of its type's template. */
+exports.FIXTURE_AMBULANCE = {
+    _id: '650000000000000000000003',
+    name: 'Ambulance BC-A1',
+    typeId: exports.FIXTURE_TYPES.AMBULANCE,
+    typePath: 'Vehicles|Ambulance|',
+    fieldValues: [
+        { _id: exports.FIXTURE_FIELDS.OWNERSHIP, name: 'Ownership', valueString: 'LFA' },
+        { _id: exports.FIXTURE_FIELDS.DECOMMISSIONED, name: 'Decommissioned', valueBoolean: true },
+    ],
+    state: { locationName: 'Brisbane|Depot|', locationStatus: 'DISPATCH' },
+    readiness: { ready: 1, readyIssues: [] },
+    tagIds: [],
+    lastUpdated: 1780000000000,
+    typeKit: true,
+    groupSatisfiesKit: false,
+};
+/**
+ * The null-slot document. Every field it carries is present-but-null, which is
+ * a different shape from absent — and the axis where two back-ends most easily
+ * disagree (a database's "does this key exist" versus a language's "is this
+ * empty"). Every condition family must classify it identically on both sides.
+ */
+exports.FIXTURE_NULLS = {
+    _id: '650000000000000000000004',
+    name: 'Null Slots',
+    typeId: exports.FIXTURE_TYPES.AMBULANCE,
+    typePath: 'Vehicles|Ambulance|',
+    fieldValues: [{ _id: exports.FIXTURE_FIELDS.OWNERSHIP, name: 'Ownership', valueString: null }],
+    state: { locationWithId: null, locationName: 'Brisbane|Depot|' },
+    tagIds: null,
+    lastUpdated: null,
+    telemetry: { battery: null },
+};
+exports.FIXTURE_CORPUS = [
+    exports.FIXTURE_EPOC,
+    exports.FIXTURE_FRIDGE,
+    exports.FIXTURE_AMBULANCE,
+    exports.FIXTURE_NULLS,
+];
+/** Frozen clock for the corpus — 2026-07-27 09:00 in Brisbane. */
+exports.FIXTURE_NOW = new Date('2026-07-26T23:00:00Z');
+exports.FIXTURE_TZ = 'Australia/Brisbane';
+exports.FIXTURE_OPTS = { now: exports.FIXTURE_NOW, timeZone: exports.FIXTURE_TZ };
+//# sourceMappingURL=fixtures.js.map

package/dist/fixtures.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"fixtures.js","sourceRoot":"","sources":["../src/fixtures.ts"],"names":[],"mappings":"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"}

package/dist/index.d.ts

@@ -0,0 +1,31 @@
+/**
+ * `@spotto/semantic-query` — the Spotto semantic query language.
+ *
+ * ONE statement of what a query means, shared by everything that reads or
+ * writes one: the client's filter UI and offline evaluation, the API's read
+ * path, and the AI layer that generates queries.
+ *
+ * The split this package exists to enforce:
+ *
+ *   validate()  every rule of the language — the gate both back-ends stand behind
+ *   dates       one resolution of "last 30 days", for everyone
+ *   evaluate()  a query -> yes/no for a document, in memory
+ *   ---------------------------------------------------------------
+ *   compile()   a query -> a MongoDB $match          [server-side only]
+ *
+ * Only the last line is unshareable, because only it is database-specific.
+ *
+ * Be clear about what that does and does not buy. The rules, the date engine
+ * and the field lookup exist once, so no consumer can hold a different opinion
+ * about them — before this, they lived inside the Mongo compiler, and a client
+ * could not so much as check a query without it. What remains genuinely
+ * duplicated is the last step: turning a checked query into a `$match` versus
+ * answering it in memory. Those are two interpretations of the same
+ * instruction and nothing here forces them to agree — only running both over
+ * the same documents can do that, which is what the shipped fixtures are for.
+ */
+export * from './types';
+export * from './dates';
+export * from './suggest';
+export * from './validate';
+export * from './evaluate';

package/dist/index.js

@@ -0,0 +1,48 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+/**
+ * `@spotto/semantic-query` — the Spotto semantic query language.
+ *
+ * ONE statement of what a query means, shared by everything that reads or
+ * writes one: the client's filter UI and offline evaluation, the API's read
+ * path, and the AI layer that generates queries.
+ *
+ * The split this package exists to enforce:
+ *
+ *   validate()  every rule of the language — the gate both back-ends stand behind
+ *   dates       one resolution of "last 30 days", for everyone
+ *   evaluate()  a query -> yes/no for a document, in memory
+ *   ---------------------------------------------------------------
+ *   compile()   a query -> a MongoDB $match          [server-side only]
+ *
+ * Only the last line is unshareable, because only it is database-specific.
+ *
+ * Be clear about what that does and does not buy. The rules, the date engine
+ * and the field lookup exist once, so no consumer can hold a different opinion
+ * about them — before this, they lived inside the Mongo compiler, and a client
+ * could not so much as check a query without it. What remains genuinely
+ * duplicated is the last step: turning a checked query into a `$match` versus
+ * answering it in memory. Those are two interpretations of the same
+ * instruction and nothing here forces them to agree — only running both over
+ * the same documents can do that, which is what the shipped fixtures are for.
+ */
+__exportStar(require("./types"), exports);
+__exportStar(require("./dates"), exports);
+__exportStar(require("./suggest"), exports);
+__exportStar(require("./validate"), exports);
+__exportStar(require("./evaluate"), exports);
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;AAAA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,0CAAuB;AACvB,0CAAuB;AACvB,4CAAyB;AACzB,6CAA0B;AAC1B,6CAA0B"}

package/dist/suggest.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Nearest-candidate matching for "did you mean…" suggestions on validation
+ * errors — an unknown field or dropdown value is rejected WITH the closest
+ * real name, so an honest error is also an actionable one.
+ *
+ * Substring matching alone is not enough: the canonical case is
+ * `SerialNo` → `SerialNumber`, and "serialno" is NOT a substring of
+ * "serialnumber" (…n-o… vs …n-u…) nor within any sane edit-distance
+ * tolerance (5 edits). The longest-shared-prefix pass is what makes that
+ * documented case actually produce a suggestion.
+ */
+export declare function nearest(candidates: string[], wanted: string): string | undefined;

package/dist/suggest.js

@@ -0,0 +1,70 @@
+"use strict";
+/**
+ * Nearest-candidate matching for "did you mean…" suggestions on validation
+ * errors — an unknown field or dropdown value is rejected WITH the closest
+ * real name, so an honest error is also an actionable one.
+ *
+ * Substring matching alone is not enough: the canonical case is
+ * `SerialNo` → `SerialNumber`, and "serialno" is NOT a substring of
+ * "serialnumber" (…n-o… vs …n-u…) nor within any sane edit-distance
+ * tolerance (5 edits). The longest-shared-prefix pass is what makes that
+ * documented case actually produce a suggestion.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.nearest = void 0;
+function editDistance(a, b) {
+    const prev = Array.from({ length: b.length + 1 }, (_, i) => i);
+    const cur = new Array(b.length + 1);
+    for (let i = 1; i <= a.length; i++) {
+        cur[0] = i;
+        for (let j = 1; j <= b.length; j++) {
+            cur[j] = Math.min(prev[j] + 1, cur[j - 1] + 1, prev[j - 1] + (a[i - 1] === b[j - 1] ? 0 : 1));
+        }
+        prev.splice(0, prev.length, ...cur);
+    }
+    return prev[b.length];
+}
+function nearest(candidates, wanted) {
+    const w = wanted.toLowerCase().trim();
+    if (!w)
+        return undefined;
+    const lower = candidates.map((c) => c.toLowerCase());
+    const exact = lower.indexOf(w);
+    if (exact >= 0)
+        return candidates[exact];
+    for (let i = 0; i < lower.length; i++) {
+        if (lower[i].startsWith(w) || w.startsWith(lower[i]))
+            return candidates[i];
+    }
+    for (let i = 0; i < lower.length; i++) {
+        if (lower[i].includes(w) || w.includes(lower[i]))
+            return candidates[i];
+    }
+    let prefixBest;
+    let prefixLen = 0;
+    for (let i = 0; i < lower.length; i++) {
+        let n = 0;
+        while (n < w.length && n < lower[i].length && w[n] === lower[i][n])
+            n++;
+        if (n > prefixLen) {
+            prefixLen = n;
+            prefixBest = candidates[i];
+        }
+    }
+    if (prefixBest && prefixLen >= Math.max(4, Math.ceil(w.length / 2))) {
+        return prefixBest;
+    }
+    let best;
+    let bestScore = Infinity;
+    const tolerance = Math.max(2, Math.floor(w.length / 3));
+    for (let i = 0; i < lower.length; i++) {
+        const d = editDistance(w, lower[i]);
+        if (d < bestScore) {
+            bestScore = d;
+            best = candidates[i];
+        }
+    }
+    return bestScore <= tolerance ? best : undefined;
+}
+exports.nearest = nearest;
+//# sourceMappingURL=suggest.js.map

package/dist/suggest.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"suggest.js","sourceRoot":"","sources":["../src/suggest.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;GAUG;;;AAEH,SAAS,YAAY,CAAC,CAAS,EAAE,CAAS;IACxC,MAAM,IAAI,GAAG,KAAK,CAAC,IAAI,CAAC,EAAE,MAAM,EAAE,CAAC,CAAC,MAAM,GAAG,CAAC,EAAE,EAAE,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,CAAA;IAC9D,MAAM,GAAG,GAAG,IAAI,KAAK,CAAS,CAAC,CAAC,MAAM,GAAG,CAAC,CAAC,CAAA;IAC3C,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,IAAI,CAAC,CAAC,MAAM,EAAE,CAAC,EAAE,EAAE;QAClC,GAAG,CAAC,CAAC,CAAC,GAAG,CAAC,CAAA;QACV,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,IAAI,CAAC,CAAC,MAAM,EAAE,CAAC,EAAE,EAAE;YAClC,GAAG,CAAC,CAAC,CAAC,GAAG,IAAI,CAAC,GAAG,CACf,IAAI,CAAC,CAAC,CAAC,GAAG,CAAC,EACX,GAAG,CAAC,CAAC,GAAG,CAAC,CAAC,GAAG,CAAC,EACd,IAAI,CAAC,CAAC,GAAG,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAC9C,CAAA;SACF;QACD,IAAI,CAAC,MAAM,CAAC,CAAC,EAAE,IAAI,CAAC,MAAM,EAAE,GAAG,GAAG,CAAC,CAAA;KACpC;IACD,OAAO,IAAI,CAAC,CAAC,CAAC,MAAM,CAAC,CAAA;AACvB,CAAC;AAED,SAAgB,OAAO,CAAC,UAAoB,EAAE,MAAc;IAC1D,MAAM,CAAC,GAAG,MAAM,CAAC,WAAW,EAAE,CAAC,IAAI,EAAE,CAAA;IACrC,IAAI,CAAC,CAAC;QAAE,OAAO,SAAS,CAAA;IACxB,MAAM,KAAK,GAAG,UAAU,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,WAAW,EAAE,CAAC,CAAA;IAEpD,MAAM,KAAK,GAAG,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,CAAA;IAC9B,IAAI,KAAK,IAAI,CAAC;QAAE,OAAO,UAAU,CAAC,KAAK,CAAC,CAAA;IAExC,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,KAAK,CAAC,MAAM,EAAE,CAAC,EAAE,EAAE;QACrC,IAAI,KAAK,CAAC,CAAC,CAAC,CAAC,UAAU,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,UAAU,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC;YAAE,OAAO,UAAU,CAAC,CAAC,CAAC,CAAA;KAC3E;IACD,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,KAAK,CAAC,MAAM,EAAE,CAAC,EAAE,EAAE;QACrC,IAAI,KAAK,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC;YAAE,OAAO,UAAU,CAAC,CAAC,CAAC,CAAA;KACvE;IAED,IAAI,UAA8B,CAAA;IAClC,IAAI,SAAS,GAAG,CAAC,CAAA;IACjB,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,KAAK,CAAC,MAAM,EAAE,CAAC,EAAE,EAAE;QACrC,IAAI,CAAC,GAAG,CAAC,CAAA;QACT,OAAO,CAAC,GAAG,CAAC,CAAC,MAAM,IAAI,CAAC,GAAG,KAAK,CAAC,CAAC,CAAC,CAAC,MAAM,IAAI,CAAC,CAAC,CAAC,CAAC,KAAK,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;YAAE,CAAC,EAAE,CAAA;QACvE,IAAI,CAAC,GAAG,SAAS,EAAE;YACjB,SAAS,GAAG,CAAC,CAAA;YACb,UAAU,GAAG,UAAU,CAAC,CAAC,CAAC,CAAA;SAC3B;KACF;IACD,IAAI,UAAU,IAAI,SAAS,IAAI,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,EAAE;QACnE,OAAO,UAAU,CAAA;KAClB;IAED,IAAI,IAAwB,CAAA;IAC5B,IAAI,SAAS,GAAG,QAAQ,CAAA;IACxB,MAAM,SAAS,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAA;IACvD,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,KAAK,CAAC,MAAM,EAAE,CAAC,EAAE,EAAE;QACrC,MAAM,CAAC,GAAG,YAAY,CAAC,CAAC,EAAE,KAAK,CAAC,CAAC,CAAC,CAAC,CAAA;QACnC,IAAI,CAAC,GAAG,SAAS,EAAE;YACjB,SAAS,GAAG,CAAC,CAAA;YACb,IAAI,GAAG,UAAU,CAAC,CAAC,CAAC,CAAA;SACrB;KACF;IACD,OAAO,SAAS,IAAI,SAAS,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,SAAS,CAAA;AAClD,CAAC;AAxCD,0BAwCC"}

package/dist/types.d.ts

@@ -0,0 +1,76 @@
+import { FieldDataType } from '@spotto/contract';
+/**
+ * What an organisation's catalogue looks like to this package.
+ *
+ * These are NOT wire shapes — the wire contract lives in `@spotto/contract`.
+ * This is the vocabulary a query is resolved AGAINST: which custom fields
+ * exist, what type each one is, and (for the evaluator) the type documents
+ * whose values an asset inherits.
+ */
+export interface SemanticFieldDef {
+    /** The field's id — custom-field matching is by `_id`, not name. */
+    id: string;
+    name: string;
+    dataType: FieldDataType;
+    /** Dropdown options — an eq value must match one exactly or the query silently returns nothing. */
+    options?: string[];
+}
+/** A resolved type-level field value, as materialised in `typeFieldValuesAll`. */
+export interface SemanticTypeFieldValue {
+    _id?: string;
+    name?: string;
+    valueString?: string;
+    valueInteger?: number;
+    valueDecimal?: number;
+    valueBoolean?: boolean;
+    valueDate?: number;
+}
+export interface SemanticTypeDef {
+    id: string;
+    /** Pipe-delimited, pipe-terminated. Root type is "". */
+    path: string;
+    /** Inheritance already resolved by the platform. */
+    typeFieldValuesAll: SemanticTypeFieldValue[];
+}
+/**
+ * What VALIDATION needs: field definitions only. The Mongo compiler needs no
+ * more than this either — type-level values reach it through a `$lookup`.
+ */
+export interface SemanticFieldCatalogue {
+    fields: SemanticFieldDef[];
+}
+/**
+ * What EVALUATION needs: the catalogue plus types, because matching a
+ * type-level field value in memory means walking the asset's type document.
+ * (The Mongo compiler gets the same values through a `$lookup` instead.)
+ */
+export interface SemanticAccountSchema extends SemanticFieldCatalogue {
+    types: SemanticTypeDef[];
+}
+export interface SemanticValidationIssue {
+    path: string;
+    code: string;
+    message: string;
+    suggestion?: string;
+}
+export declare class SemanticQueryValidationError extends Error {
+    issues: SemanticValidationIssue[];
+    constructor(issues: SemanticValidationIssue[]);
+}
+/**
+ * Throw one validation issue — fail-fast, this package's contract (the issues
+ * array shape exists for the wire; internally the FIRST problem is the
+ * answer). One helper beside the error class it throws, so issue construction
+ * cannot drift between layers.
+ */
+export declare function failSemanticValidation(path: string, code: string, message: string, suggestion?: string): never;
+export interface SemanticCompileOptions {
+    /**
+     * Explicit — never sampled deeper than the entry point, so a run is
+     * reproducible: the same query, catalogue, `now` and timezone always give
+     * the same answer, whoever is asking.
+     */
+    now?: Date;
+    /** IANA zone for resolving relative dates. */
+    timeZone?: string;
+}

package/dist/types.js

@@ -0,0 +1,24 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.failSemanticValidation = exports.SemanticQueryValidationError = void 0;
+class SemanticQueryValidationError extends Error {
+    constructor(issues) {
+        super(issues.map((i) => i.message).join('; '));
+        this.issues = issues;
+        this.name = 'SemanticQueryValidationError';
+    }
+}
+exports.SemanticQueryValidationError = SemanticQueryValidationError;
+/**
+ * Throw one validation issue — fail-fast, this package's contract (the issues
+ * array shape exists for the wire; internally the FIRST problem is the
+ * answer). One helper beside the error class it throws, so issue construction
+ * cannot drift between layers.
+ */
+function failSemanticValidation(path, code, message, suggestion) {
+    throw new SemanticQueryValidationError([
+        suggestion ? { path, code, message, suggestion } : { path, code, message },
+    ]);
+}
+exports.failSemanticValidation = failSemanticValidation;
+//# sourceMappingURL=types.js.map

package/dist/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":";;;AAmEA,MAAa,4BAA6B,SAAQ,KAAK;IACrD,YAAmB,MAAiC;QAClD,KAAK,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,CAAA;QAD7B,WAAM,GAAN,MAAM,CAA2B;QAElD,IAAI,CAAC,IAAI,GAAG,8BAA8B,CAAA;IAC5C,CAAC;CACF;AALD,oEAKC;AAED;;;;;GAKG;AACH,SAAgB,sBAAsB,CACpC,IAAY,EACZ,IAAY,EACZ,OAAe,EACf,UAAmB;IAEnB,MAAM,IAAI,4BAA4B,CAAC;QACrC,UAAU,CAAC,CAAC,CAAC,EAAE,IAAI,EAAE,IAAI,EAAE,OAAO,EAAE,UAAU,EAAE,CAAC,CAAC,CAAC,EAAE,IAAI,EAAE,IAAI,EAAE,OAAO,EAAE;KAC3E,CAAC,CAAA;AACJ,CAAC;AATD,wDASC"}

package/dist/validate.d.ts

@@ -0,0 +1,33 @@
+import { FieldDataType, SemanticQuery } from '@spotto/contract';
+import { SemanticCompileOptions, SemanticFieldCatalogue, SemanticFieldDef, SemanticValidationIssue } from './types';
+/** The live storage slots. `valueBool` does not exist; the live key is `valueBoolean`. */
+export declare const SEMANTIC_VALUE_SLOT: Record<string, string>;
+/** Millisecond-timestamp fields, by condition type. `createdDate` uses the ObjectId. */
+export declare const SEMANTIC_TIMESTAMP_FIELD: Record<string, string>;
+/**
+ * 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.
+ */
+export declare function findSemanticField(catalogue: SemanticFieldCatalogue, fieldName: unknown): SemanticFieldDef | undefined;
+/**
+ * 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).
+ */
+export declare function coerceSemanticValue(value: unknown, dataType: FieldDataType, now: Date, tz: string): string | number | boolean;
+/**
+ * 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.
+ */
+export declare function assertSemanticQuery(semanticQuery: SemanticQuery, catalogue: SemanticFieldCatalogue, opts?: SemanticCompileOptions): void;
+/** Validate without throwing. Empty array = valid. */
+export declare function validateSemanticQuery(semanticQuery: SemanticQuery, catalogue: SemanticFieldCatalogue, opts?: SemanticCompileOptions): SemanticValidationIssue[];
+/** True when any condition touches a custom field — both back-ends need to know. */
+export declare function queryUsesCustomFields(semanticQuery: SemanticQuery): boolean;