@cardstack/boxel-cli 0.13.0-unstable.4 → 0.13.0-unstable.6

package/bundled-test-harness/assets/index-query-engine-test-BETfoYOK.js

@@ -0,0 +1,2593 @@
+import { s as __toESM } from "./chunk-Rp0pCe6z.js";
+import { r as initializeDeferredDecorator, t as decorateFieldV2 } from "./runtime--fcdnjmJ-BoCBNIsz.js";
+import { Br as testRealmURL, Fa as maybeHandleScopedCSSRequest, Go as identifyCard, Ka as VirtualNetwork, Ls as wrapper_default, Os as FilterRefersToNonexistentTypeError, Ys as Loader, Za as fetcher, ba as isFilterRefersToNonsearchableFieldError, l as internalKeyFor, un as format, va as IndexQueryEngine, wa as jobStagingId, ws as getFieldDefinitions } from "./runtime-common-BTaLJEw-.js";
+import { T as rri } from "./paths-C9-NYXnM.js";
+import { O as baseRealm, it as baseRealmRRI } from "./constants-Icc0nFW-.js";
+import { t as config } from "./environment-DIUJgBKt.js";
+import { t as shimExternals } from "./externals-k-2ZBepK.js";
+import { t as require_qunit } from "./qunit-C-Foo4Nd.js";
+import { Mt as tagTestModuleExports, at as setupIndex, b as getDbAdapter, it as serializeCard, rt as getTypes } from "./mock-matrix-FjsXmU7-.js";
+import { t as p } from "./helpers-DhyRg69S.js";
+//#region tests/unit/index-query-engine-test.ts
+var import_qunit = /* @__PURE__ */ __toESM(require_qunit());
+var cardApi;
+var string;
+var date;
+var number;
+var boolean;
+var codeRef;
+var { resolvedBaseRealmURL } = config;
+(0, import_qunit.module)("Unit | query", function(hooks) {
+	let dbAdapter;
+	let indexQueryEngine;
+	let loader;
+	let testCards = {};
+	let virtualNetwork;
+	hooks.before(async function() {
+		dbAdapter = await getDbAdapter();
+	});
+	hooks.beforeEach(async function() {
+		virtualNetwork = new VirtualNetwork();
+		virtualNetwork.addURLMapping(new URL(baseRealm.url), new URL(resolvedBaseRealmURL));
+		virtualNetwork.addRealmMapping("@cardstack/base/", resolvedBaseRealmURL);
+		virtualNetwork.addImportMap("@cardstack/boxel-icons/", (rest) => {
+			return `${config.iconsURL}/@cardstack/boxel-icons/v1/icons/${rest}.js`;
+		});
+		shimExternals(virtualNetwork);
+		loader = new Loader(fetcher(virtualNetwork.fetch, [async (req, next) => {
+			return await maybeHandleScopedCSSRequest(req) || next(req);
+		}]), virtualNetwork.resolveImport, { virtualNetwork });
+		cardApi = await loader.import("@cardstack/base/card-api");
+		string = await loader.import("@cardstack/base/string");
+		date = await loader.import("@cardstack/base/date");
+		number = await loader.import("@cardstack/base/number");
+		boolean = await loader.import("@cardstack/base/boolean");
+		codeRef = await loader.import("@cardstack/base/code-ref");
+		let { field, contains, containsMany, linksToMany, linksTo, CardDef, FieldDef, setCardAsSavedForTest } = cardApi;
+		let { default: StringField } = string;
+		let { default: CodeRefField } = codeRef;
+		let { default: DateField } = date;
+		let { default: NumberField } = number;
+		let { default: BooleanField } = boolean;
+		class Address extends FieldDef {
+			static {
+				decorateFieldV2(this.prototype, "street", [field], function() {
+					return contains(StringField);
+				});
+			}
+			#street = (initializeDeferredDecorator(this, "street"), void 0);
+			static {
+				decorateFieldV2(this.prototype, "city", [field], function() {
+					return contains(StringField);
+				});
+			}
+			#city = (initializeDeferredDecorator(this, "city"), void 0);
+			static {
+				decorateFieldV2(this.prototype, "number", [field], function() {
+					return contains(NumberField);
+				});
+			}
+			#number = (initializeDeferredDecorator(this, "number"), void 0);
+		}
+		class Person extends CardDef {
+			static {
+				decorateFieldV2(this.prototype, "name", [field], function() {
+					return contains(StringField);
+				});
+			}
+			#name = (initializeDeferredDecorator(this, "name"), void 0);
+			static {
+				decorateFieldV2(this.prototype, "nickNames", [field], function() {
+					return containsMany(StringField);
+				});
+			}
+			#nickNames = (initializeDeferredDecorator(this, "nickNames"), void 0);
+			static {
+				decorateFieldV2(this.prototype, "address", [field], function() {
+					return contains(Address);
+				});
+			}
+			#address = (initializeDeferredDecorator(this, "address"), void 0);
+			static {
+				decorateFieldV2(this.prototype, "bestFriend", [field], function() {
+					return linksTo(() => Person, { searchable: "friends" });
+				});
+			}
+			#bestFriend = (initializeDeferredDecorator(this, "bestFriend"), void 0);
+			static {
+				decorateFieldV2(this.prototype, "friends", [field], function() {
+					return linksToMany(() => Person, { searchable: "bestFriend" });
+				});
+			}
+			#friends = (initializeDeferredDecorator(this, "friends"), void 0);
+			static {
+				decorateFieldV2(this.prototype, "age", [field], function() {
+					return contains(NumberField);
+				});
+			}
+			#age = (initializeDeferredDecorator(this, "age"), void 0);
+			static {
+				decorateFieldV2(this.prototype, "isHairy", [field], function() {
+					return contains(BooleanField);
+				});
+			}
+			#isHairy = (initializeDeferredDecorator(this, "isHairy"), void 0);
+			static {
+				decorateFieldV2(this.prototype, "lotteryNumbers", [field], function() {
+					return containsMany(NumberField);
+				});
+			}
+			#lotteryNumbers = (initializeDeferredDecorator(this, "lotteryNumbers"), void 0);
+		}
+		class FancyPerson extends Person {
+			static {
+				decorateFieldV2(this.prototype, "favoriteColor", [field], function() {
+					return contains(StringField);
+				});
+			}
+			#favoriteColor = (initializeDeferredDecorator(this, "favoriteColor"), void 0);
+		}
+		class Cat extends CardDef {
+			static {
+				decorateFieldV2(this.prototype, "name", [field], function() {
+					return contains(StringField);
+				});
+			}
+			#name = (initializeDeferredDecorator(this, "name"), void 0);
+		}
+		class SimpleSpec extends CardDef {
+			static {
+				decorateFieldV2(this.prototype, "cardTitle", [field], function() {
+					return contains(StringField);
+				});
+			}
+			#cardTitle = (initializeDeferredDecorator(this, "cardTitle"), void 0);
+			static {
+				decorateFieldV2(this.prototype, "ref", [field], function() {
+					return contains(CodeRefField);
+				});
+			}
+			#ref = (initializeDeferredDecorator(this, "ref"), void 0);
+		}
+		class Event extends CardDef {
+			static {
+				decorateFieldV2(this.prototype, "cardTitle", [field], function() {
+					return contains(StringField);
+				});
+			}
+			#cardTitle = (initializeDeferredDecorator(this, "cardTitle"), void 0);
+			static {
+				decorateFieldV2(this.prototype, "venue", [field], function() {
+					return contains(StringField);
+				});
+			}
+			#venue = (initializeDeferredDecorator(this, "venue"), void 0);
+			static {
+				decorateFieldV2(this.prototype, "date", [field], function() {
+					return contains(DateField);
+				});
+			}
+			#date = (initializeDeferredDecorator(this, "date"), void 0);
+		}
+		class Org extends CardDef {
+			static {
+				decorateFieldV2(this.prototype, "name", [field], function() {
+					return contains(StringField);
+				});
+			}
+			#name = (initializeDeferredDecorator(this, "name"), void 0);
+			static {
+				decorateFieldV2(this.prototype, "headquarters", [field], function() {
+					return linksTo(() => Person, { searchable: true });
+				});
+			}
+			#headquarters = (initializeDeferredDecorator(this, "headquarters"), void 0);
+			static {
+				decorateFieldV2(this.prototype, "ceo", [field], function() {
+					return linksTo(() => Person);
+				});
+			}
+			#ceo = (initializeDeferredDecorator(this, "ceo"), void 0);
+			static {
+				decorateFieldV2(this.prototype, "staff", [field], function() {
+					return linksToMany(() => Person);
+				});
+			}
+			#staff = (initializeDeferredDecorator(this, "staff"), void 0);
+			static {
+				decorateFieldV2(this.prototype, "matchingPeople", [field], function() {
+					return linksToMany(() => Person, { query: {
+						filter: { eq: { name: "match" } },
+						page: {
+							size: 10,
+							number: 0
+						}
+					} });
+				});
+			}
+			#matchingPeople = (initializeDeferredDecorator(this, "matchingPeople"), void 0);
+		}
+		tagTestModuleExports(`${testRealmURL}address`, { Address });
+		tagTestModuleExports(`${testRealmURL}person`, { Person });
+		tagTestModuleExports(`${testRealmURL}fancy-person`, { FancyPerson });
+		tagTestModuleExports(`${testRealmURL}cat`, { Cat });
+		tagTestModuleExports(`${testRealmURL}spec`, { SimpleSpec });
+		tagTestModuleExports(`${testRealmURL}event`, { Event });
+		tagTestModuleExports(`${testRealmURL}org`, { Org });
+		let stringFieldEntry = new SimpleSpec({
+			cardTitle: "String Field",
+			ref: {
+				module: `${baseRealmRRI}string`,
+				name: "default"
+			}
+		});
+		let numberFieldEntry = new SimpleSpec({
+			cardTitle: "Number Field",
+			ref: {
+				module: `${baseRealmRRI}number`,
+				name: "default"
+			}
+		});
+		let ringo = new Person({
+			name: "Ringo",
+			address: new Address({
+				street: "100 Treat Street",
+				city: "Waggington"
+			})
+		});
+		let vangogh = new Person({
+			name: "Van Gogh",
+			address: new Address({
+				street: "456 Grand Blvd",
+				city: "Barksville"
+			}),
+			bestFriend: ringo,
+			friends: [ringo]
+		});
+		testCards = {
+			mango: new FancyPerson({
+				name: "Mango",
+				address: new Address({
+					street: "123 Main Street",
+					city: "Barksville"
+				}),
+				bestFriend: vangogh,
+				friends: [vangogh, ringo]
+			}),
+			vangogh,
+			ringo,
+			paper: new Cat({ name: "Paper" }),
+			mangoBirthday: new Event({
+				cardTitle: "Mango's Birthday",
+				venue: "Dog Park",
+				date: p("2024-10-30")
+			}),
+			vangoghBirthday: new Event({
+				cardTitle: "Van Gogh's Birthday",
+				venue: "Backyard",
+				date: p("2024-11-19")
+			}),
+			stringFieldEntry,
+			numberFieldEntry
+		};
+		for (let [name, card] of Object.entries(testCards)) {
+			card.id = rri(`${testRealmURL}${name}`);
+			setCardAsSavedForTest(card);
+		}
+		let api = await loader.import("@cardstack/base/card-api");
+		async function buildDefinition(cardDef) {
+			let { fields, fieldDefs } = getFieldDefinitions(api, cardDef);
+			return {
+				codeRef: identifyCard(cardDef),
+				displayName: cardDef.displayName,
+				fields,
+				fieldDefs
+			};
+		}
+		await dbAdapter.reset();
+		indexQueryEngine = new IndexQueryEngine(dbAdapter, {
+			async lookupDefinition(codeRef) {
+				switch (internalKeyFor(codeRef, void 0, virtualNetwork)) {
+					case `${testRealmURL}address/Address`: return await buildDefinition(Address);
+					case `${testRealmURL}person/Person`: return await buildDefinition(Person);
+					case `${testRealmURL}fancy-person/FancyPerson`: return await buildDefinition(FancyPerson);
+					case `${testRealmURL}cat/Cat`: return await buildDefinition(Cat);
+					case `${testRealmURL}spec/SimpleSpec`: return await buildDefinition(SimpleSpec);
+					case `${testRealmURL}event/Event`: return await buildDefinition(Event);
+					case `${testRealmURL}org/Org`: return await buildDefinition(Org);
+					default: throw new FilterRefersToNonexistentTypeError(codeRef, { cause: `Definition for ${wrapper_default(codeRef)} not found` });
+				}
+			},
+			async lookupDefinitionEntry() {
+				throw new Error("lookupDefinitionEntry is not used by these tests");
+			},
+			async lookupCachedDefinition() {},
+			async invalidate(_realmURL) {
+				return [];
+			},
+			async clearRealmDefinitions(_realmURL) {},
+			async getCachedDefinitions() {},
+			async populateDefinitionCacheEntry() {},
+			async getCachedDefinitionsBatch() {
+				return {};
+			},
+			registerRealm() {},
+			async clearAllDefinitions() {},
+			forRealm() {
+				return this;
+			}
+		}, virtualNetwork);
+	});
+	(0, import_qunit.test)("can get all cards with empty filter", async function(assert) {
+		let { mango, vangogh, paper } = testCards;
+		await setupIndex(dbAdapter, [
+			mango,
+			vangogh,
+			paper
+		]);
+		let { cards: results, meta } = await indexQueryEngine.searchCards(new URL(testRealmURL), {});
+		assert.strictEqual(meta.page.total, 3, "the total results meta is correct");
+		assert.deepEqual(results, [
+			await serializeCard(mango),
+			await serializeCard(paper),
+			await serializeCard(vangogh)
+		], "results are correct");
+	});
+	(0, import_qunit.test)("deleted cards are not included in results", async function(assert) {
+		let { mango, vangogh, paper } = testCards;
+		await setupIndex(dbAdapter, [
+			{
+				card: mango,
+				data: { is_deleted: false }
+			},
+			{
+				card: vangogh,
+				data: { is_deleted: null }
+			},
+			{
+				card: paper,
+				data: { is_deleted: true }
+			}
+		]);
+		let { meta } = await indexQueryEngine.searchCards(new URL(testRealmURL), {});
+		assert.strictEqual(meta.page.total, 2, "the total results meta is correct");
+	});
+	(0, import_qunit.test)("error docs are not included in results", async function(assert) {
+		let { mango, vangogh } = testCards;
+		await setupIndex(dbAdapter, [
+			{
+				url: `${testRealmURL}1.json`,
+				type: "instance",
+				has_error: true,
+				generation: 1,
+				realm_url: testRealmURL,
+				pristine_doc: void 0,
+				types: [],
+				error_doc: {
+					message: "test error",
+					status: 500,
+					additionalErrors: []
+				}
+			},
+			{
+				url: `${testRealmURL}mango.json`,
+				type: "instance",
+				generation: 1,
+				realm_url: testRealmURL,
+				pristine_doc: await serializeCard(mango),
+				types: await getTypes(mango),
+				error_doc: void 0
+			},
+			{
+				url: `${testRealmURL}vangogh.json`,
+				type: "instance",
+				generation: 1,
+				realm_url: testRealmURL,
+				pristine_doc: await serializeCard(vangogh),
+				types: await getTypes(vangogh),
+				error_doc: void 0
+			}
+		]);
+		let { cards: results, meta } = await indexQueryEngine.searchCards(new URL(testRealmURL), {});
+		assert.strictEqual(meta.page.total, 2, "the total results meta is correct");
+		assert.deepEqual(getIds(results), [mango.id, vangogh.id], "results are correct");
+	});
+	(0, import_qunit.test)("can filter by type", async function(assert) {
+		let { mango, vangogh, paper } = testCards;
+		await setupIndex(dbAdapter, [
+			mango,
+			vangogh,
+			paper
+		]);
+		let type = await personCardType(testCards);
+		let { cards: results, meta } = await indexQueryEngine.searchCards(new URL(testRealmURL), { filter: { type } });
+		assert.strictEqual(meta.page.total, 2, "the total results meta is correct");
+		assert.deepEqual(getIds(results), [mango.id, vangogh.id], "results are correct");
+	});
+	(0, import_qunit.test)("not: { type } genuinely excludes rows whose types chain contains the ref", async function(assert) {
+		let { paper } = testCards;
+		await setupIndex(dbAdapter, [
+			testCards.mango,
+			testCards.vangogh,
+			paper
+		]);
+		let personType = await personCardType(testCards);
+		let { cards: results, meta } = await indexQueryEngine.searchCards(new URL(testRealmURL), { filter: { not: { type: personType } } });
+		assert.strictEqual(meta.page.total, 1, "only the non-Person card remains");
+		assert.deepEqual(getIds(results), [paper.id], "the Cat is kept; both Person-chain cards are excluded");
+	});
+	(0, import_qunit.test)("every: [{ type: A }, { type: B }] is an intersection, satisfiable within one chain", async function(assert) {
+		let { mango, ringo } = testCards;
+		await setupIndex(dbAdapter, [mango, ringo]);
+		let personType = await personCardType(testCards);
+		let fancyType = internalKeyToCodeRef([...await getTypes(mango)].shift());
+		let { cards: results, meta } = await indexQueryEngine.searchCards(new URL(testRealmURL), { filter: { every: [{ type: fancyType }, { type: personType }] } });
+		assert.strictEqual(meta.page.total, 1, "the intersection matches one card");
+		assert.deepEqual(getIds(results), [mango.id], "only the FancyPerson");
+	});
+	(0, import_qunit.test)("a type filter spelled with the base realm alias matches a canonically-keyed row", async function(assert) {
+		await setupIndex(dbAdapter, [{
+			url: `${testRealmURL}vangogh.json`,
+			file_alias: `${testRealmURL}vangogh`,
+			type: "instance",
+			generation: 1,
+			realm_url: testRealmURL,
+			deps: [],
+			types: [`${baseRealmRRI}card-api/CardDef`],
+			last_modified: "1",
+			resource_created_at: "1"
+		}]);
+		for (let [label, module] of [["prefix form", `${baseRealmRRI}card-api`], ["alias URL form", "https://cardstack.com/base/card-api"]]) {
+			let { meta } = await indexQueryEngine.searchCards(new URL(testRealmURL), { filter: { type: {
+				module,
+				name: "CardDef"
+			} } });
+			assert.strictEqual(meta.page.total, 1, `a filter in ${label} matches the canonically-keyed row`);
+		}
+	});
+	(0, import_qunit.test)("{ type: baseRef } matches every card instance (BaseDef terminates the chain)", async function(assert) {
+		let { mango, paper } = testCards;
+		await setupIndex(dbAdapter, [mango, paper]);
+		let baseType = internalKeyToCodeRef([...await getTypes(mango)].pop());
+		let { cards: results, meta } = await indexQueryEngine.searchCards(new URL(testRealmURL), { filter: { type: baseType } });
+		assert.strictEqual(meta.page.total, 2, "both cards match BaseDef");
+		assert.deepEqual(getIds(results), [mango.id, paper.id]);
+	});
+	(0, import_qunit.test)(`can filter using 'eq'`, async function(assert) {
+		let { mango, vangogh, paper } = testCards;
+		await setupIndex(dbAdapter, [
+			{
+				card: mango,
+				data: { search_doc: { name: "Mango" } }
+			},
+			{
+				card: vangogh,
+				data: { search_doc: { name: "Van Gogh" } }
+			},
+			{
+				card: paper,
+				data: { search_doc: { name: "Mango" } }
+			}
+		]);
+		let type = await personCardType(testCards);
+		let { cards: results, meta } = await indexQueryEngine.searchCards(new URL(testRealmURL), { filter: {
+			eq: { name: "Mango" },
+			on: type
+		} });
+		assert.strictEqual(meta.page.total, 1, "the total results meta is correct");
+		assert.deepEqual(getIds(results), [mango.id], "results are correct");
+	});
+	(0, import_qunit.test)(`can filter using 'eq' thru nested fields`, async function(assert) {
+		let { mango, vangogh, ringo } = testCards;
+		await setupIndex(dbAdapter, [
+			{
+				card: mango,
+				data: { search_doc: {
+					name: "Mango",
+					address: {
+						street: "123 Main Street",
+						city: "Barksville"
+					}
+				} }
+			},
+			{
+				card: vangogh,
+				data: { search_doc: {
+					name: "Van Gogh",
+					address: {
+						street: "456 Grand Blvd",
+						city: "Barksville"
+					}
+				} }
+			},
+			{
+				card: ringo,
+				data: { search_doc: {
+					name: "Ringo",
+					address: {
+						street: "100 Treat Street",
+						city: "Waggington"
+					}
+				} }
+			}
+		]);
+		let type = await personCardType(testCards);
+		let { cards: results, meta } = await indexQueryEngine.searchCards(new URL(testRealmURL), { filter: {
+			on: type,
+			eq: { "address.city": "Barksville" }
+		} });
+		assert.strictEqual(meta.page.total, 2, "the total results meta is correct");
+		assert.deepEqual(getIds(results), [mango.id, vangogh.id], "results are correct");
+	});
+	(0, import_qunit.test)(`can use 'eq' to match multiple fields`, async function(assert) {
+		let { mango, vangogh } = testCards;
+		await setupIndex(dbAdapter, [{
+			card: mango,
+			data: { search_doc: {
+				name: "Mango",
+				nickNames: ["Mang Mang", "Baby"]
+			} }
+		}, {
+			card: vangogh,
+			data: { search_doc: {
+				name: "Van Gogh",
+				nickNames: ["Big boy", "Farty"]
+			} }
+		}]);
+		let type = await personCardType(testCards);
+		let { cards: results, meta } = await indexQueryEngine.searchCards(new URL(testRealmURL), { filter: {
+			on: type,
+			eq: {
+				name: "Van Gogh",
+				nickNames: "Farty"
+			}
+		} });
+		assert.strictEqual(meta.page.total, 1, "the total results meta is correct");
+		assert.deepEqual(getIds(results), [vangogh.id], "results are correct");
+	});
+	(0, import_qunit.test)(`can use 'eq' to find 'null' values`, async function(assert) {
+		let { mango, vangogh, ringo } = testCards;
+		await setupIndex(dbAdapter, [
+			{
+				card: mango,
+				data: { search_doc: { name: "Mango" } }
+			},
+			{
+				card: vangogh,
+				data: { search_doc: { name: "Van Gogh" } }
+			},
+			{
+				card: ringo,
+				data: { search_doc: { name: null } }
+			}
+		]);
+		let type = await personCardType(testCards);
+		let { cards: results, meta } = await indexQueryEngine.searchCards(new URL(testRealmURL), { filter: {
+			on: type,
+			eq: { name: null }
+		} });
+		assert.strictEqual(meta.page.total, 1, "the total results meta is correct");
+		assert.deepEqual(getIds(results), [ringo.id], "results are correct");
+	});
+	(0, import_qunit.test)(`can use 'eq' to match against number type`, async function(assert) {
+		let { mango, vangogh } = testCards;
+		await setupIndex(dbAdapter, [{
+			card: mango,
+			data: { search_doc: {
+				name: "Mango",
+				age: 4
+			} }
+		}, {
+			card: vangogh,
+			data: { search_doc: {
+				name: "Van Gogh",
+				age: 8
+			} }
+		}]);
+		let type = await personCardType(testCards);
+		let { cards: results, meta } = await indexQueryEngine.searchCards(new URL(testRealmURL), { filter: {
+			on: type,
+			eq: { age: 4 }
+		} });
+		assert.strictEqual(meta.page.total, 1, "the total results meta is correct");
+		assert.deepEqual(getIds(results), [mango.id], "results are correct");
+	});
+	(0, import_qunit.test)(`can use 'eq' to match against boolean type`, async function(assert) {
+		let { mango, vangogh, ringo } = testCards;
+		await setupIndex(dbAdapter, [
+			{
+				card: mango,
+				data: { search_doc: {
+					name: "Mango",
+					isHairy: false
+				} }
+			},
+			{
+				card: vangogh,
+				data: { search_doc: {
+					name: "Van Gogh",
+					isHairy: true
+				} }
+			},
+			{
+				card: ringo,
+				data: { search_doc: {
+					name: "Van Gogh",
+					isHairy: null
+				} }
+			}
+		]);
+		let type = await personCardType(testCards);
+		{
+			let { cards: results, meta } = await indexQueryEngine.searchCards(new URL(testRealmURL), { filter: {
+				on: type,
+				eq: { isHairy: false }
+			} });
+			assert.strictEqual(meta.page.total, 1, "the total results meta is correct");
+			assert.deepEqual(getIds(results), [mango.id], "results are correct");
+		}
+		{
+			let { cards: results, meta } = await indexQueryEngine.searchCards(new URL(testRealmURL), { filter: {
+				on: type,
+				eq: { isHairy: true }
+			} });
+			assert.strictEqual(meta.page.total, 1, "the total results meta is correct");
+			assert.deepEqual(getIds(results), [vangogh.id], "results are correct");
+		}
+		{
+			let { cards: results, meta } = await indexQueryEngine.searchCards(new URL(testRealmURL), { filter: {
+				on: type,
+				eq: { isHairy: null }
+			} });
+			assert.strictEqual(meta.page.total, 1, "the total results meta is correct");
+			assert.deepEqual(getIds(results), [ringo.id], "results are correct");
+		}
+	});
+	(0, import_qunit.test)("can filter eq from a code ref query value", async function(assert) {
+		let { stringFieldEntry, numberFieldEntry } = testCards;
+		await setupIndex(dbAdapter, [{
+			card: stringFieldEntry,
+			data: { search_doc: {
+				cardTitle: stringFieldEntry.cardTitle,
+				ref: internalKeyFor(stringFieldEntry.ref, void 0, virtualNetwork)
+			} }
+		}, {
+			card: numberFieldEntry,
+			data: { search_doc: {
+				cardTitle: numberFieldEntry.cardTitle,
+				ref: internalKeyFor(numberFieldEntry.ref, void 0, virtualNetwork)
+			} }
+		}]);
+		let type = await SimpleSpecType(testCards);
+		let { cards: results, meta } = await indexQueryEngine.searchCards(new URL(testRealmURL), { filter: {
+			on: type,
+			eq: { ref: {
+				module: `${baseRealmRRI}string`,
+				name: "default"
+			} }
+		} });
+		assert.strictEqual(meta.page.total, 1, "the total results meta is correct");
+		assert.deepEqual(getIds(results), [stringFieldEntry.id], "results are correct");
+	});
+	(0, import_qunit.test)("can filter eq from a date query value", async function(assert) {
+		let { mangoBirthday, vangoghBirthday } = testCards;
+		await setupIndex(dbAdapter, [{
+			card: mangoBirthday,
+			data: { search_doc: {
+				cardTitle: mangoBirthday.cardTitle,
+				venue: mangoBirthday.venue,
+				date: format(mangoBirthday.date, "yyyy-MM-dd")
+			} }
+		}, {
+			card: vangoghBirthday,
+			data: { search_doc: {
+				cardTitle: vangoghBirthday.cardTitle,
+				venue: vangoghBirthday.venue,
+				date: format(vangoghBirthday.date, "yyyy-MM-dd")
+			} }
+		}]);
+		let type = await eventType(testCards);
+		let { cards: results, meta } = await indexQueryEngine.searchCards(new URL(testRealmURL), { filter: {
+			on: type,
+			eq: { date: "2024-10-30" }
+		} });
+		assert.strictEqual(meta.page.total, 1, "the total results meta is correct");
+		assert.deepEqual(getIds(results), [mangoBirthday.id], "results are correct");
+	});
+	(0, import_qunit.test)(`can filter using 'in'`, async function(assert) {
+		let { mango, vangogh, ringo } = testCards;
+		await setupIndex(dbAdapter, [
+			{
+				card: mango,
+				data: { search_doc: { name: "Mango" } }
+			},
+			{
+				card: vangogh,
+				data: { search_doc: { name: "Van Gogh" } }
+			},
+			{
+				card: ringo,
+				data: { search_doc: { name: "Ringo" } }
+			}
+		]);
+		let type = await personCardType(testCards);
+		let { cards: results, meta } = await indexQueryEngine.searchCards(new URL(testRealmURL), { filter: {
+			in: { name: ["Mango", "Ringo"] },
+			on: type
+		} });
+		assert.strictEqual(meta.page.total, 2, "the total results meta is correct");
+		assert.deepEqual(getIds(results), [mango.id, ringo.id], "results are correct");
+	});
+	(0, import_qunit.test)(`can filter using 'in' with a single value`, async function(assert) {
+		let { mango, vangogh } = testCards;
+		await setupIndex(dbAdapter, [{
+			card: mango,
+			data: { search_doc: { name: "Mango" } }
+		}, {
+			card: vangogh,
+			data: { search_doc: { name: "Van Gogh" } }
+		}]);
+		let type = await personCardType(testCards);
+		let { cards: results, meta } = await indexQueryEngine.searchCards(new URL(testRealmURL), { filter: {
+			in: { name: ["Mango"] },
+			on: type
+		} });
+		assert.strictEqual(meta.page.total, 1, "the total results meta is correct");
+		assert.deepEqual(getIds(results), [mango.id], "results are correct");
+	});
+	(0, import_qunit.test)(`can filter using 'in' with an empty array`, async function(assert) {
+		let { mango, vangogh } = testCards;
+		await setupIndex(dbAdapter, [{
+			card: mango,
+			data: { search_doc: { name: "Mango" } }
+		}, {
+			card: vangogh,
+			data: { search_doc: { name: "Van Gogh" } }
+		}]);
+		let type = await personCardType(testCards);
+		let { cards: results, meta } = await indexQueryEngine.searchCards(new URL(testRealmURL), { filter: {
+			in: { name: [] },
+			on: type
+		} });
+		assert.strictEqual(meta.page.total, 0, "the total results meta is correct");
+		assert.deepEqual(getIds(results), [], "results are correct");
+	});
+	(0, import_qunit.test)(`can filter using 'in' with null values`, async function(assert) {
+		let { mango, vangogh, ringo } = testCards;
+		await setupIndex(dbAdapter, [
+			{
+				card: mango,
+				data: { search_doc: { name: "Mango" } }
+			},
+			{
+				card: vangogh,
+				data: { search_doc: { name: null } }
+			},
+			{
+				card: ringo,
+				data: { search_doc: { name: "Ringo" } }
+			}
+		]);
+		let type = await personCardType(testCards);
+		let { cards: results, meta } = await indexQueryEngine.searchCards(new URL(testRealmURL), { filter: {
+			in: { name: ["Mango", null] },
+			on: type
+		} });
+		assert.strictEqual(meta.page.total, 2, "the total results meta is correct");
+		assert.deepEqual(getIds(results), [mango.id, vangogh.id], "results are correct");
+	});
+	(0, import_qunit.test)(`can filter using 'in' thru nested fields`, async function(assert) {
+		let { mango, vangogh, ringo } = testCards;
+		await setupIndex(dbAdapter, [
+			{
+				card: mango,
+				data: { search_doc: {
+					name: "Mango",
+					address: { city: "Barksville" }
+				} }
+			},
+			{
+				card: vangogh,
+				data: { search_doc: {
+					name: "Van Gogh",
+					address: { city: "Barksville" }
+				} }
+			},
+			{
+				card: ringo,
+				data: { search_doc: {
+					name: "Ringo",
+					address: { city: "Waggington" }
+				} }
+			}
+		]);
+		let type = await personCardType(testCards);
+		let { cards: results, meta } = await indexQueryEngine.searchCards(new URL(testRealmURL), { filter: {
+			on: type,
+			in: { "address.city": ["Waggington"] }
+		} });
+		assert.strictEqual(meta.page.total, 1, "the total results meta is correct");
+		assert.deepEqual(getIds(results), [ringo.id], "results are correct");
+	});
+	(0, import_qunit.test)(`can negate an 'in' filter with 'not'`, async function(assert) {
+		let { mango, vangogh, ringo } = testCards;
+		await setupIndex(dbAdapter, [
+			{
+				card: mango,
+				data: { search_doc: { name: "Mango" } }
+			},
+			{
+				card: vangogh,
+				data: { search_doc: { name: "Van Gogh" } }
+			},
+			{
+				card: ringo,
+				data: { search_doc: { name: "Ringo" } }
+			}
+		]);
+		let type = await personCardType(testCards);
+		let { cards: results, meta } = await indexQueryEngine.searchCards(new URL(testRealmURL), { filter: {
+			on: type,
+			not: { in: { name: ["Mango", "Ringo"] } }
+		} });
+		assert.strictEqual(meta.page.total, 1, "the total results meta is correct");
+		assert.deepEqual(getIds(results), [vangogh.id], "results are correct");
+	});
+	(0, import_qunit.test)(`can filter using 'in' with the id field`, async function(assert) {
+		let { mango, vangogh, ringo } = testCards;
+		await setupIndex(dbAdapter, [
+			{
+				card: mango,
+				data: { search_doc: {
+					id: mango.id,
+					name: "Mango"
+				} }
+			},
+			{
+				card: vangogh,
+				data: { search_doc: {
+					id: vangogh.id,
+					name: "Van Gogh"
+				} }
+			},
+			{
+				card: ringo,
+				data: { search_doc: {
+					id: ringo.id,
+					name: "Ringo"
+				} }
+			}
+		]);
+		let type = await personCardType(testCards);
+		let { cards: results, meta } = await indexQueryEngine.searchCards(new URL(testRealmURL), { filter: {
+			on: type,
+			in: { id: [mango.id, ringo.id] }
+		} });
+		assert.strictEqual(meta.page.total, 2, "the total results meta is correct");
+		assert.deepEqual(getIds(results), [mango.id, ringo.id], "results are correct");
+	});
+	(0, import_qunit.test)(`can search with a 'not' filter`, async function(assert) {
+		let { mango, vangogh, ringo } = testCards;
+		await setupIndex(dbAdapter, [
+			{
+				card: mango,
+				data: { search_doc: { name: "Mango" } }
+			},
+			{
+				card: vangogh,
+				data: { search_doc: { name: "Van Gogh" } }
+			},
+			{
+				card: ringo,
+				data: { search_doc: { name: "Ringo" } }
+			}
+		]);
+		let type = await personCardType(testCards);
+		let { cards: results, meta } = await indexQueryEngine.searchCards(new URL(testRealmURL), { filter: {
+			on: type,
+			not: { eq: { name: "Mango" } }
+		} });
+		assert.strictEqual(meta.page.total, 2, "the total results meta is correct");
+		assert.deepEqual(getIds(results), [ringo.id, vangogh.id], "results are correct");
+	});
+	(0, import_qunit.test)("can handle a filter with double negatives", async function(assert) {
+		let { mango, vangogh, ringo } = testCards;
+		await setupIndex(dbAdapter, [
+			{
+				card: mango,
+				data: { search_doc: { name: "Mango" } }
+			},
+			{
+				card: vangogh,
+				data: { search_doc: { name: "Van Gogh" } }
+			},
+			{
+				card: ringo,
+				data: { search_doc: { name: "Ringo" } }
+			}
+		]);
+		let type = await personCardType(testCards);
+		let { cards: results, meta } = await indexQueryEngine.searchCards(new URL(testRealmURL), { filter: {
+			on: type,
+			not: { not: { not: { eq: { name: "Mango" } } } }
+		} });
+		assert.strictEqual(meta.page.total, 2, "the total results meta is correct");
+		assert.deepEqual(getIds(results), [ringo.id, vangogh.id], "results are correct");
+	});
+	(0, import_qunit.test)(`can use a 'contains' filter`, async function(assert) {
+		let { mango, vangogh, ringo } = testCards;
+		await setupIndex(dbAdapter, [
+			{
+				card: mango,
+				data: { search_doc: { name: "Mango" } }
+			},
+			{
+				card: vangogh,
+				data: { search_doc: { name: "Van Gogh" } }
+			},
+			{
+				card: ringo,
+				data: { search_doc: { name: "Ringo" } }
+			}
+		]);
+		let type = await personCardType(testCards);
+		let { cards: results, meta } = await indexQueryEngine.searchCards(new URL(testRealmURL), { filter: {
+			on: type,
+			contains: { name: "ngo" }
+		} });
+		assert.strictEqual(meta.page.total, 2, "the total results meta is correct");
+		assert.deepEqual(getIds(results), [mango.id, ringo.id], "results are correct");
+	});
+	(0, import_qunit.test)(`contains filter is case insensitive`, async function(assert) {
+		let { mango, vangogh, ringo } = testCards;
+		await setupIndex(dbAdapter, [
+			{
+				card: mango,
+				data: { search_doc: { name: "Mango" } }
+			},
+			{
+				card: vangogh,
+				data: { search_doc: { name: "Van Gogh" } }
+			},
+			{
+				card: ringo,
+				data: { search_doc: { name: "Ringo" } }
+			}
+		]);
+		let type = await personCardType(testCards);
+		let { cards: results, meta } = await indexQueryEngine.searchCards(new URL(testRealmURL), { filter: {
+			on: type,
+			contains: { name: "mang" }
+		} });
+		assert.strictEqual(meta.page.total, 1, "the total results meta is correct");
+		assert.deepEqual(getIds(results), [mango.id], "results are correct");
+	});
+	(0, import_qunit.test)(`can use 'contains' to match multiple fields`, async function(assert) {
+		let { mango, vangogh } = testCards;
+		await setupIndex(dbAdapter, [{
+			card: mango,
+			data: { search_doc: {
+				name: "Mango",
+				nickNames: ["Mang Mang", "Pee Baby"]
+			} }
+		}, {
+			card: vangogh,
+			data: { search_doc: {
+				name: "Van Gogh",
+				nickNames: ["Big Baby", "Farty"]
+			} }
+		}]);
+		let type = await personCardType(testCards);
+		let { cards: results, meta } = await indexQueryEngine.searchCards(new URL(testRealmURL), { filter: {
+			on: type,
+			contains: {
+				name: "ngo",
+				nickNames: "Baby"
+			}
+		} });
+		assert.strictEqual(meta.page.total, 1, "the total results meta is correct");
+		assert.deepEqual(getIds(results), [mango.id], "results are correct");
+	});
+	(0, import_qunit.test)(`can use a 'contains' filter to match 'null'`, async function(assert) {
+		let { mango, vangogh } = testCards;
+		await setupIndex(dbAdapter, [{
+			card: mango,
+			data: { search_doc: { name: "Mango" } }
+		}, {
+			card: vangogh,
+			data: { search_doc: { name: null } }
+		}]);
+		let type = await personCardType(testCards);
+		let { cards: results, meta } = await indexQueryEngine.searchCards(new URL(testRealmURL), { filter: {
+			on: type,
+			contains: { name: null }
+		} });
+		assert.strictEqual(meta.page.total, 1, "the total results meta is correct");
+		assert.deepEqual(getIds(results), [vangogh.id], "results are correct");
+	});
+	(0, import_qunit.test)(`can use 'every' to combine multiple filters`, async function(assert) {
+		let { mango, vangogh, ringo } = testCards;
+		await setupIndex(dbAdapter, [
+			{
+				card: mango,
+				data: { search_doc: {
+					name: "Mango",
+					address: {
+						street: "123 Main Street",
+						city: "Barksville"
+					}
+				} }
+			},
+			{
+				card: vangogh,
+				data: { search_doc: {
+					name: "Van Gogh",
+					address: {
+						street: "456 Grand Blvd",
+						city: "Barksville"
+					}
+				} }
+			},
+			{
+				card: ringo,
+				data: { search_doc: {
+					name: "Ringo",
+					address: {
+						street: "100 Treat Street",
+						city: "Waggington"
+					}
+				} }
+			}
+		]);
+		let type = await personCardType(testCards);
+		let { cards: results, meta } = await indexQueryEngine.searchCards(new URL(testRealmURL), { filter: {
+			on: type,
+			every: [{ eq: { "address.city": "Barksville" } }, { not: { eq: { "address.street": "456 Grand Blvd" } } }]
+		} });
+		assert.strictEqual(meta.page.total, 1, "the total results meta is correct");
+		assert.deepEqual(getIds(results), [mango.id], "results are correct");
+	});
+	(0, import_qunit.test)(`can use 'any' to combine multiple filters`, async function(assert) {
+		let { mango, vangogh, ringo } = testCards;
+		await setupIndex(dbAdapter, [
+			{
+				card: mango,
+				data: { search_doc: { name: "Mango" } }
+			},
+			{
+				card: vangogh,
+				data: { search_doc: { name: "Van Gogh" } }
+			},
+			{
+				card: ringo,
+				data: { search_doc: { name: "Ringo" } }
+			}
+		]);
+		let type = await personCardType(testCards);
+		let { cards: results, meta } = await indexQueryEngine.searchCards(new URL(testRealmURL), { filter: {
+			on: type,
+			any: [{ eq: { name: "Mango" } }, { eq: { name: "Van Gogh" } }]
+		} });
+		assert.strictEqual(meta.page.total, 2, "the total results meta is correct");
+		assert.deepEqual(getIds(results), [mango.id, vangogh.id], "results are correct");
+	});
+	(0, import_qunit.test)(`returns empty results when query refers to missing card`, async function(assert) {
+		await setupIndex(dbAdapter, []);
+		let { cards, meta } = await indexQueryEngine.searchCards(new URL(testRealmURL), { filter: {
+			on: {
+				module: `${testRealmURL}nonexistent`,
+				name: "Nonexistent"
+			},
+			eq: { nonExistentField: "hello" }
+		} });
+		assert.strictEqual(cards.length, 0, "no cards are returned");
+		assert.strictEqual(meta.page.total, 0, "total count is zero");
+	});
+	(0, import_qunit.test)(`gives a good error when query refers to missing field`, async function(assert) {
+		await setupIndex(dbAdapter, []);
+		let type = await personCardType(testCards);
+		try {
+			await indexQueryEngine.searchCards(new URL(testRealmURL), { filter: {
+				on: type,
+				eq: {
+					name: "Cardy",
+					nonExistentField: "hello"
+				}
+			} });
+			throw new Error("failed to throw expected exception");
+		} catch (err) {
+			assert.strictEqual(err.message, `Your filter refers to a nonexistent field "nonExistentField" on type ${wrapper_default(type)}`);
+		}
+	});
+	(0, import_qunit.test)(`errors when a filter crosses a non-searchable relationship`, async function(assert) {
+		await setupIndex(dbAdapter, []);
+		let orgType = {
+			module: `${testRealmURL}org`,
+			name: "Org"
+		};
+		try {
+			await indexQueryEngine.searchCards(new URL(testRealmURL), { filter: {
+				on: orgType,
+				eq: { "ceo.name": "Robin" }
+			} });
+			throw new Error("failed to throw expected exception");
+		} catch (err) {
+			assert.true(isFilterRefersToNonsearchableFieldError(err), "throws the distinct non-searchable-field error");
+			assert.strictEqual(err.reason, "not-searchable", "reason is not-searchable");
+			assert.true(err.message.includes("\"ceo\""), `message names the relationship: ${err.message}`);
+			assert.true(err.message.includes("not searchable"), `message explains it is not searchable: ${err.message}`);
+			assert.true(err.message.includes("searchable: true"), `message names the annotation to add: ${err.message}`);
+		}
+	});
+	(0, import_qunit.test)(`errors when a filter crosses a non-searchable relationship deeper in the path`, async function(assert) {
+		await setupIndex(dbAdapter, []);
+		let orgType = {
+			module: `${testRealmURL}org`,
+			name: "Org"
+		};
+		try {
+			await indexQueryEngine.searchCards(new URL(testRealmURL), { filter: {
+				on: orgType,
+				eq: { "headquarters.bestFriend.name": "Robin" }
+			} });
+			throw new Error("failed to throw expected exception");
+		} catch (err) {
+			assert.true(isFilterRefersToNonsearchableFieldError(err), "throws the distinct non-searchable-field error");
+			assert.strictEqual(err.reason, "not-searchable", "reason is not-searchable");
+			assert.true(err.message.includes("\"headquarters.bestFriend\""), `message names the deeper hop: ${err.message}`);
+			assert.true(err.message.includes(`searchable: 'bestFriend'`), `message names the route to add to the head field: ${err.message}`);
+		}
+	});
+	(0, import_qunit.test)(`errors when a filter crosses a query-backed relationship`, async function(assert) {
+		await setupIndex(dbAdapter, []);
+		let orgType = {
+			module: `${testRealmURL}org`,
+			name: "Org"
+		};
+		try {
+			await indexQueryEngine.searchCards(new URL(testRealmURL), { filter: {
+				on: orgType,
+				eq: { "matchingPeople.name": "Robin" }
+			} });
+			throw new Error("failed to throw expected exception");
+		} catch (err) {
+			assert.true(isFilterRefersToNonsearchableFieldError(err), "throws the distinct non-searchable-field error");
+			assert.strictEqual(err.reason, "query-backed", "reason is query-backed");
+			assert.true(err.message.includes("\"matchingPeople\""), `message names the relationship: ${err.message}`);
+			assert.true(err.message.includes("query-backed"), `message explains it is query-backed: ${err.message}`);
+		}
+	});
+	(0, import_qunit.test)(`a searchable relationship path compiles and runs`, async function(assert) {
+		await setupIndex(dbAdapter, []);
+		let orgType = {
+			module: `${testRealmURL}org`,
+			name: "Org"
+		};
+		let { meta } = await indexQueryEngine.searchCards(new URL(testRealmURL), { filter: {
+			on: orgType,
+			eq: { "headquarters.name": "Robin" }
+		} });
+		assert.strictEqual(meta.page.total, 0, "the searchable path ran without error");
+	});
+	(0, import_qunit.test)(`a filter on a relationship's id is allowed even when it is not searchable`, async function(assert) {
+		await setupIndex(dbAdapter, []);
+		let orgType = {
+			module: `${testRealmURL}org`,
+			name: "Org"
+		};
+		let { meta } = await indexQueryEngine.searchCards(new URL(testRealmURL), { filter: {
+			on: orgType,
+			eq: { "ceo.id": `${testRealmURL}mango` }
+		} });
+		assert.strictEqual(meta.page.total, 0, "the id reference filter ran without error");
+	});
+	(0, import_qunit.test)(`a nonexistent field beyond a searchable relationship still reports the nonexistent-field error`, async function(assert) {
+		await setupIndex(dbAdapter, []);
+		let orgType = {
+			module: `${testRealmURL}org`,
+			name: "Org"
+		};
+		try {
+			await indexQueryEngine.searchCards(new URL(testRealmURL), { filter: {
+				on: orgType,
+				eq: { "headquarters.nope": "Robin" }
+			} });
+			throw new Error("failed to throw expected exception");
+		} catch (err) {
+			assert.false(isFilterRefersToNonsearchableFieldError(err), "does not throw the searchability error");
+			assert.true(err.message.includes("nonexistent field \"headquarters.nope\""), `reports the nonexistent-field error: ${err.message}`);
+		}
+	});
+	(0, import_qunit.test)(`it can filter on a plural primitive field using 'eq'`, async function(assert) {
+		let { mango, vangogh } = testCards;
+		await setupIndex(dbAdapter, [{
+			card: mango,
+			data: { search_doc: {
+				name: "Mango",
+				nickNames: ["Mang Mang", "Baby"]
+			} }
+		}, {
+			card: vangogh,
+			data: { search_doc: {
+				name: "Van Gogh",
+				nickNames: ["Big boy", "Farty"]
+			} }
+		}]);
+		let type = await personCardType(testCards);
+		let { cards: results, meta } = await indexQueryEngine.searchCards(new URL(testRealmURL), { filter: {
+			on: type,
+			eq: { nickNames: "Farty" }
+		} });
+		assert.strictEqual(meta.page.total, 1, "the total results meta is correct");
+		assert.deepEqual(getIds(results), [vangogh.id], "results are correct");
+	});
+	(0, import_qunit.test)(`it can filter on a nested field within a plural composite field using 'eq'`, async function(assert) {
+		let { mango, vangogh } = testCards;
+		await setupIndex(dbAdapter, [{
+			card: mango,
+			data: { search_doc: {
+				name: "Mango",
+				friends: [{ name: "Van Gogh" }, { name: "Ringo" }]
+			} }
+		}, {
+			card: vangogh,
+			data: { search_doc: {
+				name: "Van Gogh",
+				friends: [{ name: "Ringo" }]
+			} }
+		}]);
+		let type = await personCardType(testCards);
+		{
+			let { cards: results, meta } = await indexQueryEngine.searchCards(new URL(testRealmURL), { filter: {
+				on: type,
+				eq: { "friends.name": "Van Gogh" }
+			} });
+			assert.strictEqual(meta.page.total, 1, "the total results meta is correct");
+			assert.deepEqual(getIds(results), [mango.id], "results are correct");
+		}
+		{
+			let { cards: results, meta } = await indexQueryEngine.searchCards(new URL(testRealmURL), { filter: {
+				on: type,
+				eq: { "friends.name": "Ringo" }
+			} });
+			assert.strictEqual(meta.page.total, 2, "the total results meta is correct");
+			assert.deepEqual(getIds(results), [mango.id, vangogh.id], "results are correct");
+		}
+	});
+	(0, import_qunit.test)("it can match a null in a plural field", async function(assert) {
+		let { mango, vangogh } = testCards;
+		await setupIndex(dbAdapter, [{
+			card: mango,
+			data: { search_doc: {
+				name: "Mango",
+				nickNames: ["Mang Mang", "Baby"]
+			} }
+		}, {
+			card: vangogh,
+			data: { search_doc: {
+				name: "Van Gogh",
+				nickNames: null
+			} }
+		}]);
+		let type = await personCardType(testCards);
+		let { cards: results, meta } = await indexQueryEngine.searchCards(new URL(testRealmURL), { filter: {
+			on: type,
+			eq: { nickNames: null }
+		} });
+		assert.strictEqual(meta.page.total, 1, "the total results meta is correct");
+		assert.deepEqual(getIds(results), [vangogh.id], "results are correct");
+	});
+	(0, import_qunit.test)("it can match a leaf plural field nested in a plural composite field", async function(assert) {
+		let { mango, vangogh } = testCards;
+		await setupIndex(dbAdapter, [{
+			card: mango,
+			data: { search_doc: {
+				name: "Mango",
+				friends: [{
+					name: "Van Gogh",
+					nickNames: ["Big Baby", "Farty"]
+				}, {
+					name: "Ringo",
+					nickNames: ["Mang Mang", "Baby"]
+				}]
+			} }
+		}, {
+			card: vangogh,
+			data: { search_doc: {
+				name: "Van Gogh",
+				friends: [{
+					name: "Ringo",
+					nickNames: ["Ring Ring"]
+				}]
+			} }
+		}]);
+		let type = await personCardType(testCards);
+		let { cards: results, meta } = await indexQueryEngine.searchCards(new URL(testRealmURL), { filter: {
+			on: type,
+			eq: { "friends.nickNames": "Baby" }
+		} });
+		assert.strictEqual(meta.page.total, 1, "the total results meta is correct");
+		assert.deepEqual(getIds(results), [mango.id], "results are correct");
+	});
+	(0, import_qunit.test)("it can match thru a plural nested composite field that is field of a singular composite field", async function(assert) {
+		let { mango, vangogh } = testCards;
+		await setupIndex(dbAdapter, [{
+			card: mango,
+			data: { search_doc: {
+				name: "Mango",
+				bestFriend: {
+					name: "Van Gogh",
+					friends: [{ name: "Ringo" }, { name: "Van Gogh" }]
+				}
+			} }
+		}, {
+			card: vangogh,
+			data: { search_doc: {
+				name: "Van Gogh",
+				bestFriend: {
+					name: "Ringo",
+					friends: [{ name: "Lucky" }]
+				}
+			} }
+		}]);
+		let type = await personCardType(testCards);
+		let { cards: results, meta } = await indexQueryEngine.searchCards(new URL(testRealmURL), { filter: {
+			on: type,
+			eq: { "bestFriend.friends.name": "Lucky" }
+		} });
+		assert.strictEqual(meta.page.total, 1, "the total results meta is correct");
+		assert.deepEqual(getIds(results), [vangogh.id], "results are correct");
+	});
+	(0, import_qunit.test)(`can return a single result for a card when there are multiple matches within a result's search doc`, async function(assert) {
+		let { mango } = testCards;
+		await setupIndex(dbAdapter, [{
+			card: mango,
+			data: { search_doc: {
+				name: "Mango",
+				friends: [{
+					name: "Ringo",
+					bestFriend: { name: "Mango" }
+				}, {
+					name: "Van Gogh",
+					bestFriend: { name: "Mango" }
+				}]
+			} }
+		}]);
+		let type = await personCardType(testCards);
+		let { cards: results, meta } = await indexQueryEngine.searchCards(new URL(testRealmURL), { filter: {
+			on: type,
+			eq: { "friends.bestFriend.name": "Mango" }
+		} });
+		assert.strictEqual(meta.page.total, 1, "the total results meta is correct");
+		assert.deepEqual(getIds(results), [mango.id], "results are correct");
+	});
+	(0, import_qunit.test)("can perform query against a pass's staged rows", async function(assert) {
+		let { mango, vangogh, ringo } = testCards;
+		let stagingId = jobStagingId(1, 1);
+		await setupIndex(dbAdapter, [{
+			realm_url: testRealmURL,
+			current_generation: 1
+		}], {
+			working: [
+				{
+					card: mango,
+					data: {
+						generation: 1,
+						staging_id: stagingId,
+						search_doc: { name: "Mango" }
+					}
+				},
+				{
+					card: vangogh,
+					data: {
+						generation: 2,
+						staging_id: stagingId,
+						search_doc: { name: "Mango" }
+					}
+				},
+				{
+					card: ringo,
+					data: {
+						generation: 2,
+						staging_id: stagingId,
+						search_doc: { name: "Ringo" }
+					}
+				}
+			],
+			production: [
+				{
+					card: mango,
+					data: {
+						generation: 1,
+						search_doc: { name: "Mango" }
+					}
+				},
+				{
+					card: vangogh,
+					data: {
+						generation: 1,
+						search_doc: { name: "Van Gogh" }
+					}
+				},
+				{
+					card: ringo,
+					data: {
+						generation: 1,
+						search_doc: { name: "Mango" }
+					}
+				}
+			]
+		});
+		let type = await personCardType(testCards);
+		let { cards: results, meta } = await indexQueryEngine.searchCards(new URL(testRealmURL), { filter: {
+			on: type,
+			eq: { name: "Mango" }
+		} }, { pendingStagingId: stagingId });
+		assert.strictEqual(meta.page.total, 2, "the total results meta is correct");
+		assert.deepEqual(getIds(results), [mango.id, vangogh.id], "results are correct");
+	});
+	(0, import_qunit.test)("can perform query against \"production\" version of the index", async function(assert) {
+		let { mango, vangogh, ringo } = testCards;
+		let stagingId = jobStagingId(1, 1);
+		await setupIndex(dbAdapter, [{
+			realm_url: testRealmURL,
+			current_generation: 1
+		}], {
+			working: [
+				{
+					card: mango,
+					data: {
+						generation: 1,
+						staging_id: stagingId,
+						search_doc: { name: "Mango" }
+					}
+				},
+				{
+					card: vangogh,
+					data: {
+						generation: 2,
+						staging_id: stagingId,
+						search_doc: { name: "Mango" }
+					}
+				},
+				{
+					card: ringo,
+					data: {
+						generation: 1,
+						staging_id: stagingId,
+						search_doc: { name: "Ringo" }
+					}
+				}
+			],
+			production: [
+				{
+					card: mango,
+					data: {
+						generation: 1,
+						search_doc: { name: "Mango" }
+					}
+				},
+				{
+					card: vangogh,
+					data: {
+						generation: 1,
+						search_doc: { name: "Van Gogh" }
+					}
+				},
+				{
+					card: ringo,
+					data: {
+						generation: 1,
+						search_doc: { name: "Ringo" }
+					}
+				}
+			]
+		});
+		let type = await personCardType(testCards);
+		let { cards: results, meta } = await indexQueryEngine.searchCards(new URL(testRealmURL), { filter: {
+			on: type,
+			eq: { name: "Mango" }
+		} });
+		assert.strictEqual(meta.page.total, 1, "the total results meta is correct");
+		assert.deepEqual(getIds(results), [mango.id], "results are correct");
+	});
+	(0, import_qunit.test)("can sort search results", async function(assert) {
+		let { mango, vangogh, ringo } = testCards;
+		await setupIndex(dbAdapter, [
+			{
+				card: mango,
+				data: { search_doc: { name: "Mango" } }
+			},
+			{
+				card: vangogh,
+				data: { search_doc: { name: "Van Gogh" } }
+			},
+			{
+				card: ringo,
+				data: { search_doc: { name: "Ringo" } }
+			}
+		]);
+		let type = await personCardType(testCards);
+		let { cards: results, meta } = await indexQueryEngine.searchCards(new URL(testRealmURL), { sort: [{
+			on: type,
+			by: "name"
+		}] });
+		assert.strictEqual(meta.page.total, 3, "the total results meta is correct");
+		assert.deepEqual(getIds(results), [
+			mango.id,
+			ringo.id,
+			vangogh.id
+		], "results are correct");
+	});
+	(0, import_qunit.test)("can sort descending", async function(assert) {
+		let { mango, vangogh, ringo } = testCards;
+		await setupIndex(dbAdapter, [
+			{
+				card: mango,
+				data: { search_doc: { name: "Mango" } }
+			},
+			{
+				card: vangogh,
+				data: { search_doc: { name: "Van Gogh" } }
+			},
+			{
+				card: ringo,
+				data: { search_doc: { name: "Ringo" } }
+			}
+		]);
+		let type = await personCardType(testCards);
+		let { cards: results, meta } = await indexQueryEngine.searchCards(new URL(testRealmURL), { sort: [{
+			on: type,
+			by: "name",
+			direction: "desc"
+		}] });
+		assert.strictEqual(meta.page.total, 3, "the total results meta is correct");
+		assert.deepEqual(getIds(results), [
+			vangogh.id,
+			ringo.id,
+			mango.id
+		], "results are correct");
+	});
+	(0, import_qunit.test)("nulls are sorted to the end of search results", async function(assert) {
+		let { mango, vangogh, ringo } = testCards;
+		await setupIndex(dbAdapter, [
+			{
+				card: mango,
+				data: { search_doc: { name: "Mango" } }
+			},
+			{
+				card: vangogh,
+				data: { search_doc: { name: null } }
+			},
+			{
+				card: ringo,
+				data: { search_doc: { name: "Ringo" } }
+			}
+		]);
+		let type = await personCardType(testCards);
+		let { cards: results } = await indexQueryEngine.searchCards(new URL(testRealmURL), { sort: [{
+			on: type,
+			by: "name"
+		}] });
+		assert.deepEqual(getIds(results), [
+			mango.id,
+			ringo.id,
+			vangogh.id
+		], "results are correct");
+	});
+	(0, import_qunit.test)(`can filter using 'gt'`, async function(assert) {
+		let { mango, vangogh, ringo } = testCards;
+		await setupIndex(dbAdapter, [
+			{
+				card: mango,
+				data: { search_doc: {
+					name: "Mango",
+					address: {
+						street: "123 Main Street",
+						city: "Barksville"
+					},
+					age: 35
+				} }
+			},
+			{
+				card: vangogh,
+				data: { search_doc: {
+					name: "Van Gogh",
+					address: {
+						street: "456 Grand Blvd",
+						city: "Barksville"
+					},
+					age: 30
+				} }
+			},
+			{
+				card: ringo,
+				data: { search_doc: {
+					name: "Ringo",
+					address: {
+						street: "100 Treat Street",
+						city: "Waggington"
+					},
+					age: 25
+				} }
+			}
+		]);
+		let type = await personCardType(testCards);
+		let { cards, meta } = await indexQueryEngine.searchCards(new URL(testRealmURL), { filter: {
+			on: type,
+			range: { age: { gt: 25 } }
+		} });
+		assert.strictEqual(meta.page.total, 2, "the total results meta is correct");
+		assert.deepEqual(getIds(cards), [mango.id, vangogh.id], "results are correct");
+	});
+	(0, import_qunit.test)(`range filter works when both 'type' and 'on' are provided`, async function(assert) {
+		let { mango, vangogh, ringo } = testCards;
+		await setupIndex(dbAdapter, [
+			{
+				card: mango,
+				data: { search_doc: {
+					name: "Mango",
+					address: {
+						street: "123 Main Street",
+						city: "Barksville"
+					},
+					age: 35
+				} }
+			},
+			{
+				card: vangogh,
+				data: { search_doc: {
+					name: "Van Gogh",
+					address: {
+						street: "456 Grand Blvd",
+						city: "Barksville"
+					},
+					age: 30
+				} }
+			},
+			{
+				card: ringo,
+				data: { search_doc: {
+					name: "Ringo",
+					address: {
+						street: "100 Treat Street",
+						city: "Waggington"
+					},
+					age: 25
+				} }
+			}
+		]);
+		let type = await personCardType(testCards);
+		let { cards, meta } = await indexQueryEngine.searchCards(new URL(testRealmURL), { filter: {
+			on: type,
+			type,
+			range: { age: { gt: 25 } }
+		} });
+		assert.strictEqual(meta.page.total, 2, "the total results meta is correct");
+		assert.deepEqual(getIds(cards), [mango.id, vangogh.id], "results are correct");
+	});
+	(0, import_qunit.test)(`eq filter works when both 'type' and 'on' are provided`, async function(assert) {
+		let { mango, vangogh, ringo } = testCards;
+		await setupIndex(dbAdapter, [
+			{
+				card: mango,
+				data: { search_doc: { name: "Mango" } }
+			},
+			{
+				card: vangogh,
+				data: { search_doc: { name: "Van Gogh" } }
+			},
+			{
+				card: ringo,
+				data: { search_doc: { name: "Ringo" } }
+			}
+		]);
+		let type = await personCardType(testCards);
+		let { cards, meta } = await indexQueryEngine.searchCards(new URL(testRealmURL), { filter: {
+			on: type,
+			type,
+			eq: { name: "Mango" }
+		} });
+		assert.strictEqual(meta.page.total, 1, "the total results meta is correct");
+		assert.deepEqual(getIds(cards), [mango.id], "results are correct");
+	});
+	(0, import_qunit.test)(`contains filter works when both 'type' and 'on' are provided`, async function(assert) {
+		let { mango, vangogh, ringo } = testCards;
+		await setupIndex(dbAdapter, [
+			{
+				card: mango,
+				data: { search_doc: {
+					name: "Mango",
+					address: { city: "Barksville" }
+				} }
+			},
+			{
+				card: vangogh,
+				data: { search_doc: {
+					name: "Van Gogh",
+					address: { city: "Barksville" }
+				} }
+			},
+			{
+				card: ringo,
+				data: { search_doc: {
+					name: "Ringo",
+					address: { city: "Waggington" }
+				} }
+			}
+		]);
+		let type = await personCardType(testCards);
+		let { cards, meta } = await indexQueryEngine.searchCards(new URL(testRealmURL), { filter: {
+			on: type,
+			type,
+			contains: { "address.city": "Barks" }
+		} });
+		assert.strictEqual(meta.page.total, 2, "the total results meta is correct");
+		assert.deepEqual(getIds(cards), [mango.id, vangogh.id], "results are correct");
+	});
+	(0, import_qunit.test)(`not filter works when both 'type' and 'on' are provided`, async function(assert) {
+		let { mango, vangogh, ringo } = testCards;
+		await setupIndex(dbAdapter, [
+			{
+				card: mango,
+				data: { search_doc: { name: "Mango" } }
+			},
+			{
+				card: vangogh,
+				data: { search_doc: { name: "Van Gogh" } }
+			},
+			{
+				card: ringo,
+				data: { search_doc: { name: "Ringo" } }
+			}
+		]);
+		let type = await personCardType(testCards);
+		let { cards, meta } = await indexQueryEngine.searchCards(new URL(testRealmURL), {
+			filter: {
+				on: type,
+				type,
+				not: { eq: { name: "Mango" } }
+			},
+			sort: [{
+				on: type,
+				by: "name",
+				direction: "asc"
+			}]
+		});
+		assert.strictEqual(meta.page.total, 2, "the total results meta is correct");
+		assert.deepEqual(getIds(cards), [ringo.id, vangogh.id], "results are correct");
+	});
+	(0, import_qunit.test)(`'on' takes precedence over 'type' when they differ`, async function(assert) {
+		let { mango, vangogh, ringo, paper } = testCards;
+		await setupIndex(dbAdapter, [
+			{
+				card: mango,
+				data: { search_doc: {
+					name: "Mango",
+					address: {
+						street: "123 Main Street",
+						city: "Barksville"
+					},
+					age: 35
+				} }
+			},
+			{
+				card: vangogh,
+				data: { search_doc: {
+					name: "Van Gogh",
+					address: {
+						street: "456 Grand Blvd",
+						city: "Barksville"
+					},
+					age: 30
+				} }
+			},
+			{
+				card: ringo,
+				data: { search_doc: {
+					name: "Ringo",
+					address: {
+						street: "100 Treat Street",
+						city: "Waggington"
+					},
+					age: 25
+				} }
+			},
+			{
+				card: paper,
+				data: { search_doc: {
+					name: "Paper",
+					age: 99
+				} }
+			}
+		]);
+		let personType = await personCardType(testCards);
+		let catType = internalKeyToCodeRef([...await getTypes(paper)].shift());
+		let { cards, meta } = await indexQueryEngine.searchCards(new URL(testRealmURL), { filter: {
+			on: personType,
+			type: catType,
+			range: { age: { gt: 25 } }
+		} });
+		assert.strictEqual(meta.page.total, 2, "the total results meta is correct");
+		assert.deepEqual(getIds(cards), [mango.id, vangogh.id], "results are drawn from the on type and ignore conflicting type");
+	});
+	(0, import_qunit.test)(`can filter using 'gte'`, async function(assert) {
+		let { mango, vangogh, ringo } = testCards;
+		await setupIndex(dbAdapter, [
+			{
+				card: mango,
+				data: { search_doc: {
+					name: "Mango",
+					address: {
+						street: "123 Main Street",
+						city: "Barksville"
+					},
+					age: 35
+				} }
+			},
+			{
+				card: vangogh,
+				data: { search_doc: {
+					name: "Van Gogh",
+					address: {
+						street: "456 Grand Blvd",
+						city: "Barksville"
+					},
+					age: 30
+				} }
+			},
+			{
+				card: ringo,
+				data: { search_doc: {
+					name: "Ringo",
+					address: {
+						street: "100 Treat Street",
+						city: "Waggington"
+					},
+					age: 25
+				} }
+			}
+		]);
+		let type = await personCardType(testCards);
+		let { cards, meta } = await indexQueryEngine.searchCards(new URL(testRealmURL), {
+			filter: {
+				on: type,
+				range: { age: { gte: 25 } }
+			},
+			sort: [{
+				on: type,
+				by: "age",
+				direction: "desc"
+			}]
+		});
+		assert.strictEqual(meta.page.total, 3, "the total results meta is correct");
+		assert.deepEqual(getIds(cards), [
+			mango.id,
+			vangogh.id,
+			ringo.id
+		], "results are correct");
+	});
+	(0, import_qunit.test)(`can filter using 'gt' thru nested fields`, async function(assert) {
+		let { mango, vangogh, ringo } = testCards;
+		await setupIndex(dbAdapter, [
+			{
+				card: mango,
+				data: { search_doc: {
+					name: "Mango",
+					address: {
+						street: "123 Main Street",
+						city: "Barksville",
+						number: 123
+					}
+				} }
+			},
+			{
+				card: vangogh,
+				data: { search_doc: {
+					name: "Van Gogh",
+					address: {
+						street: "456 Grand Blvd",
+						city: "Barksville",
+						number: 456
+					}
+				} }
+			},
+			{
+				card: ringo,
+				data: { search_doc: {
+					name: "Ringo",
+					address: {
+						street: "100 Treat Street",
+						city: "Waggington",
+						number: 100
+					}
+				} }
+			}
+		]);
+		let type = await personCardType(testCards);
+		let { cards, meta } = await indexQueryEngine.searchCards(new URL(testRealmURL), { filter: {
+			on: type,
+			range: { "address.number": { gt: 100 } }
+		} });
+		assert.strictEqual(meta.page.total, 2, "the total results meta is correct");
+		assert.deepEqual(getIds(cards), [mango.id, vangogh.id], "results are correct");
+	});
+	(0, import_qunit.test)(`can filter using 'gt' thru a plural primitive field`, async function(assert) {
+		let { mango, vangogh, ringo } = testCards;
+		await setupIndex(dbAdapter, [
+			{
+				card: mango,
+				data: { search_doc: {
+					name: "Mango",
+					lotteryNumbers: [
+						20,
+						50,
+						70
+					]
+				} }
+			},
+			{
+				card: vangogh,
+				data: { search_doc: {
+					name: "Van Gogh",
+					lotteryNumbers: [
+						40,
+						60,
+						80
+					]
+				} }
+			},
+			{
+				card: ringo,
+				data: { search_doc: {
+					name: "Ringo",
+					lotteryNumbers: [
+						10,
+						20,
+						30
+					]
+				} }
+			}
+		]);
+		let type = await personCardType(testCards);
+		let { cards, meta } = await indexQueryEngine.searchCards(new URL(testRealmURL), { filter: {
+			on: type,
+			range: { lotteryNumbers: { gt: 50 } }
+		} });
+		assert.strictEqual(meta.page.total, 2, "the total results meta is correct");
+		assert.deepEqual(getIds(cards), [mango.id, vangogh.id], "results are correct");
+	});
+	(0, import_qunit.test)(`can filter using 'gt' thru a plural composite field`, async function(assert) {
+		let { mango, vangogh, ringo } = testCards;
+		let mangoDoc = {
+			name: "Mango",
+			age: 35
+		};
+		let vanGoghDoc = {
+			name: "Van Gogh",
+			age: 30
+		};
+		let ringoDoc = {
+			name: "Ringo",
+			age: 25
+		};
+		await setupIndex(dbAdapter, [
+			{
+				card: mango,
+				data: { search_doc: {
+					...mangoDoc,
+					friends: [{ ...vanGoghDoc }]
+				} }
+			},
+			{
+				card: vangogh,
+				data: { search_doc: {
+					...vanGoghDoc,
+					friends: [{ ...ringoDoc }]
+				} }
+			},
+			{
+				card: ringo,
+				data: { search_doc: {
+					...ringoDoc,
+					friends: [{ ...mangoDoc }]
+				} }
+			}
+		]);
+		let type = await personCardType(testCards);
+		let { cards, meta } = await indexQueryEngine.searchCards(new URL(testRealmURL), { filter: {
+			on: type,
+			range: { "friends.age": { gt: 25 } }
+		} });
+		assert.strictEqual(meta.page.total, 2, "the total results meta is correct");
+		assert.deepEqual(getIds(cards), [mango.id, ringo.id], "results are correct");
+	});
+	(0, import_qunit.test)(`can filter using 'lt'`, async function(assert) {
+		let { mango, vangogh, ringo } = testCards;
+		await setupIndex(dbAdapter, [
+			{
+				card: mango,
+				data: { search_doc: {
+					name: "Mango",
+					address: {
+						street: "123 Main Street",
+						city: "Barksville"
+					},
+					age: 35
+				} }
+			},
+			{
+				card: vangogh,
+				data: { search_doc: {
+					name: "Van Gogh",
+					address: {
+						street: "456 Grand Blvd",
+						city: "Barksville"
+					},
+					age: 30
+				} }
+			},
+			{
+				card: ringo,
+				data: { search_doc: {
+					name: "Ringo",
+					address: {
+						street: "100 Treat Street",
+						city: "Waggington"
+					},
+					age: 25
+				} }
+			}
+		]);
+		let type = await personCardType(testCards);
+		let { cards, meta } = await indexQueryEngine.searchCards(new URL(testRealmURL), {
+			filter: {
+				on: type,
+				range: { age: { lt: 35 } }
+			},
+			sort: [{
+				on: type,
+				by: "age",
+				direction: "desc"
+			}]
+		});
+		assert.strictEqual(meta.page.total, 2, "the total results meta is correct");
+		assert.deepEqual(getIds(cards), [vangogh.id, ringo.id], "results are correct");
+	});
+	(0, import_qunit.test)(`can filter using 'lte'`, async function(assert) {
+		let { mango, vangogh, ringo } = testCards;
+		await setupIndex(dbAdapter, [
+			{
+				card: mango,
+				data: { search_doc: {
+					name: "Mango",
+					address: {
+						street: "123 Main Street",
+						city: "Barksville"
+					},
+					age: 35
+				} }
+			},
+			{
+				card: vangogh,
+				data: { search_doc: {
+					name: "Van Gogh",
+					address: {
+						street: "456 Grand Blvd",
+						city: "Barksville"
+					},
+					age: 30
+				} }
+			},
+			{
+				card: ringo,
+				data: { search_doc: {
+					name: "Ringo",
+					address: {
+						street: "100 Treat Street",
+						city: "Waggington"
+					},
+					age: 25
+				} }
+			}
+		]);
+		let type = await personCardType(testCards);
+		let { cards, meta } = await indexQueryEngine.searchCards(new URL(testRealmURL), {
+			filter: {
+				on: type,
+				range: { age: { lte: 35 } }
+			},
+			sort: [{
+				on: type,
+				by: "age",
+				direction: "desc"
+			}]
+		});
+		assert.strictEqual(meta.page.total, 3, "the total results meta is correct");
+		assert.deepEqual(getIds(cards), [
+			mango.id,
+			vangogh.id,
+			ringo.id
+		], "results are correct");
+	});
+	(0, import_qunit.test)(`can combine 'range' filter`, async function(assert) {
+		let { mango, vangogh, ringo } = testCards;
+		await setupIndex(dbAdapter, [
+			{
+				card: mango,
+				data: { search_doc: {
+					name: "Mango",
+					address: {
+						street: "123 Main Street",
+						city: "Barksville"
+					},
+					age: 35
+				} }
+			},
+			{
+				card: vangogh,
+				data: { search_doc: {
+					name: "Van Gogh",
+					address: {
+						street: "456 Grand Blvd",
+						city: "Barksville"
+					},
+					age: 30
+				} }
+			},
+			{
+				card: ringo,
+				data: { search_doc: {
+					name: "Ringo",
+					address: {
+						street: "100 Treat Street",
+						city: "Waggington"
+					},
+					age: 25
+				} }
+			}
+		]);
+		let type = await personCardType(testCards);
+		let { cards, meta } = await indexQueryEngine.searchCards(new URL(testRealmURL), {
+			filter: {
+				on: type,
+				range: { age: {
+					gt: 25,
+					lt: 35
+				} }
+			},
+			sort: [{
+				on: type,
+				by: "age",
+				direction: "desc"
+			}]
+		});
+		assert.strictEqual(meta.page.total, 1, "the total results meta is correct");
+		assert.deepEqual(getIds(cards), [vangogh.id], "results are correct");
+	});
+	(0, import_qunit.test)(`cannot filter 'null' value using 'range'`, async function(assert) {
+		let { mango, vangogh, ringo } = testCards;
+		await setupIndex(dbAdapter, [
+			{
+				card: mango,
+				data: { search_doc: {
+					name: "Mango",
+					address: {
+						street: "123 Main Street",
+						city: "Barksville"
+					},
+					age: 35
+				} }
+			},
+			{
+				card: vangogh,
+				data: { search_doc: {
+					name: "Van Gogh",
+					address: {
+						street: "456 Grand Blvd",
+						city: "Barksville"
+					},
+					age: 30
+				} }
+			},
+			{
+				card: ringo,
+				data: { search_doc: {
+					name: "Ringo",
+					address: {
+						street: "100 Treat Street",
+						city: "Waggington"
+					},
+					age: 25
+				} }
+			}
+		]);
+		let type = await personCardType(testCards);
+		assert.rejects(indexQueryEngine.searchCards(new URL(testRealmURL), { filter: {
+			on: type,
+			range: { age: { gt: null } }
+		} }), `'null' is not a permitted value in a 'range' filter`);
+	});
+	(0, import_qunit.test)(`'matches' filter returns rows whose markdown contains the query (case-insensitive)`, async function(assert) {
+		let { mango, vangogh, ringo } = testCards;
+		await setupIndex(dbAdapter, [
+			{
+				card: mango,
+				data: { markdown: "Mango is a friendly puppy who loves to play fetch in the park." }
+			},
+			{
+				card: vangogh,
+				data: { markdown: "Van Gogh is a calm dog with a painterly coat." }
+			},
+			{
+				card: ringo,
+				data: { markdown: "Ringo plays the drums and enjoys long naps." }
+			}
+		]);
+		let lower = await indexQueryEngine.searchCards(new URL(testRealmURL), { filter: { matches: "mango" } });
+		assert.strictEqual(lower.meta.page.total, 1, "one row matches \"mango\"");
+		assert.deepEqual(getIds(lower.cards), [mango.id]);
+		let upper = await indexQueryEngine.searchCards(new URL(testRealmURL), { filter: { matches: "MANGO" } });
+		assert.strictEqual(upper.meta.page.total, 1, "upper-case query still matches");
+		let none = await indexQueryEngine.searchCards(new URL(testRealmURL), { filter: { matches: "xylophone" } });
+		assert.strictEqual(none.meta.page.total, 0, "no rows match a missing term");
+	});
+	(0, import_qunit.test)(`'matches' escapes LIKE wildcards so user input matches literally`, async function(assert) {
+		let { mango, vangogh } = testCards;
+		await setupIndex(dbAdapter, [{
+			card: mango,
+			data: { markdown: "Summer sale: 50% off today only." }
+		}, {
+			card: vangogh,
+			data: { markdown: "Fifty kittens lined up on the fence." }
+		}]);
+		let percent = await indexQueryEngine.searchCards(new URL(testRealmURL), { filter: { matches: "50%" } });
+		assert.strictEqual(percent.meta.page.total, 1, "\"50%\" matches the literal \"50%\" row only");
+		assert.deepEqual(getIds(percent.cards), [mango.id]);
+		let underscore = await indexQueryEngine.searchCards(new URL(testRealmURL), { filter: { matches: "_nothing_" } });
+		assert.strictEqual(underscore.meta.page.total, 0, "underscore is treated literally, not as a single-char wildcard");
+	});
+	(0, import_qunit.test)(`'matches' does not match rows whose markdown is null`, async function(assert) {
+		let { mango, vangogh } = testCards;
+		await setupIndex(dbAdapter, [{
+			card: mango,
+			data: { markdown: "Mango likes fetch." }
+		}, {
+			card: vangogh,
+			data: { markdown: null }
+		}]);
+		let { meta, cards } = await indexQueryEngine.searchCards(new URL(testRealmURL), { filter: { matches: "mango" } });
+		assert.strictEqual(meta.page.total, 1, "only the non-null row matching \"mango\" is returned");
+		assert.deepEqual(getIds(cards), [mango.id]);
+	});
+	(0, import_qunit.test)(`'matches' empty query matches nothing`, async function(assert) {
+		let { mango, ringo } = testCards;
+		await setupIndex(dbAdapter, [{
+			card: mango,
+			data: { markdown: "Mango likes fetch." }
+		}, {
+			card: ringo,
+			data: { markdown: "Ringo likes drums." }
+		}]);
+		let { meta: emptyMeta } = await indexQueryEngine.searchCards(new URL(testRealmURL), { filter: { matches: "" } });
+		assert.strictEqual(emptyMeta.page.total, 0, "empty query does not match every row");
+		let { meta: wsMeta } = await indexQueryEngine.searchCards(new URL(testRealmURL), { filter: { matches: "   " } });
+		assert.strictEqual(wsMeta.page.total, 0, "whitespace-only query does not match every row");
+	});
+	(0, import_qunit.test)(`'matches' parameterizes the query safely (injection attempt)`, async function(assert) {
+		let { mango, vangogh, ringo } = testCards;
+		await setupIndex(dbAdapter, [
+			{
+				card: mango,
+				data: { markdown: "Mango likes fetch." }
+			},
+			{
+				card: vangogh,
+				data: { markdown: "Van Gogh likes naps." }
+			},
+			{
+				card: ringo,
+				data: { markdown: "Ringo likes drums." }
+			}
+		]);
+		let { meta } = await indexQueryEngine.searchCards(new URL(testRealmURL), { filter: { matches: `'; DROP TABLE boxel_index; --` } });
+		assert.strictEqual(meta.page.total, 0, "malicious input is treated as literal LIKE text, not SQL");
+		let sanity = await indexQueryEngine.searchCards(new URL(testRealmURL), { filter: { matches: "mango" } });
+		assert.strictEqual(sanity.meta.page.total, 1, "boxel_index table is intact after injection attempt");
+	});
+	(0, import_qunit.test)(`'matches' tolerates unicode and special characters in the query`, async function(assert) {
+		let { mango } = testCards;
+		await setupIndex(dbAdapter, [{
+			card: mango,
+			data: { markdown: "Mango likes fetch." }
+		}]);
+		let { meta } = await indexQueryEngine.searchCards(new URL(testRealmURL), { filter: { matches: "café 🦮 \"$1 $2\"" } });
+		assert.strictEqual(meta.page.total, 0, "special characters do not throw; no rows match");
+	});
+	(0, import_qunit.test)(`'matches' composes inside 'every' with eq/contains/range/cardType`, async function(assert) {
+		let { mango, vangogh, ringo } = testCards;
+		await setupIndex(dbAdapter, [
+			{
+				card: mango,
+				data: {
+					search_doc: {
+						name: "Mango",
+						age: 35
+					},
+					markdown: "Mango is the name here."
+				}
+			},
+			{
+				card: vangogh,
+				data: {
+					search_doc: {
+						name: "Van Gogh",
+						age: 30
+					},
+					markdown: "Van Gogh is here."
+				}
+			},
+			{
+				card: ringo,
+				data: {
+					search_doc: {
+						name: "Ringo",
+						age: 25
+					},
+					markdown: "Ringo is here."
+				}
+			}
+		]);
+		let type = await personCardType(testCards);
+		let { cards, meta } = await indexQueryEngine.searchCards(new URL(testRealmURL), { filter: {
+			on: type,
+			every: [
+				{ type },
+				{ matches: "mango" },
+				{ eq: { name: "Mango" } },
+				{ contains: { name: "Mang" } },
+				{ range: { age: { gt: 10 } } }
+			]
+		} });
+		assert.strictEqual(meta.page.total, 1, `every-composition narrows to the one row matching all predicates`);
+		assert.deepEqual(getIds(cards), [mango.id], "correct row returned");
+	});
+	(0, import_qunit.test)(`'matches' composes inside 'any' alongside other filters`, async function(assert) {
+		let { mango, vangogh, ringo } = testCards;
+		await setupIndex(dbAdapter, [
+			{
+				card: mango,
+				data: {
+					search_doc: { name: "Mango" },
+					markdown: "Mango is here."
+				}
+			},
+			{
+				card: vangogh,
+				data: {
+					search_doc: { name: "Van Gogh" },
+					markdown: "Van Gogh is here."
+				}
+			},
+			{
+				card: ringo,
+				data: {
+					search_doc: { name: "Ringo" },
+					markdown: "Ringo is here."
+				}
+			}
+		]);
+		let type = await personCardType(testCards);
+		let { cards, meta } = await indexQueryEngine.searchCards(new URL(testRealmURL), { filter: {
+			on: type,
+			any: [{ matches: "ringo" }, { eq: { name: "Mango" } }]
+		} });
+		assert.strictEqual(meta.page.total, 2, `union of the 'matches' branch and the 'eq' branch`);
+		assert.deepEqual(getIds(cards), [mango.id, ringo.id], "results are correct");
+	});
+	(0, import_qunit.test)(`'matches' composes inside 'not'`, async function(assert) {
+		let { mango, vangogh, ringo } = testCards;
+		await setupIndex(dbAdapter, [
+			{
+				card: mango,
+				data: {
+					search_doc: { name: "Mango" },
+					markdown: "Mango is here."
+				}
+			},
+			{
+				card: vangogh,
+				data: {
+					search_doc: { name: "Van Gogh" },
+					markdown: "Van Gogh is here."
+				}
+			},
+			{
+				card: ringo,
+				data: {
+					search_doc: { name: "Ringo" },
+					markdown: "Ringo is here."
+				}
+			}
+		]);
+		let type = await personCardType(testCards);
+		let { cards, meta } = await indexQueryEngine.searchCards(new URL(testRealmURL), { filter: {
+			on: type,
+			not: { matches: "mango" }
+		} });
+		assert.strictEqual(meta.page.total, 2, `'not' drops the one row that matched 'mango'`);
+		assert.deepEqual(getIds(cards), [ringo.id, vangogh.id], "non-mango person rows returned");
+	});
+	(0, import_qunit.test)(`'_matchRelevance' sort orders matched rows ahead of non-matched (SQLite 1/0 fallback)`, async function(assert) {
+		let { mango, vangogh, ringo } = testCards;
+		await setupIndex(dbAdapter, [
+			{
+				card: mango,
+				data: {
+					search_doc: { name: "Mango" },
+					markdown: "Mango is here."
+				}
+			},
+			{
+				card: vangogh,
+				data: {
+					search_doc: { name: "Van Gogh" },
+					markdown: "Van Gogh is here."
+				}
+			},
+			{
+				card: ringo,
+				data: {
+					search_doc: { name: "Ringo" },
+					markdown: "Ringo is here."
+				}
+			}
+		]);
+		let query = { filter: {
+			on: await personCardType(testCards),
+			any: [{ matches: "ringo" }, { eq: { name: "Mango" } }]
+		} };
+		let desc = await indexQueryEngine.searchCards(new URL(testRealmURL), {
+			...query,
+			sort: [{ by: "_matchRelevance" }]
+		});
+		assert.deepEqual(getIds(desc.cards), [ringo.id, mango.id], "best match (the matches-branch hit) sorts first by default (desc)");
+		let asc = await indexQueryEngine.searchCards(new URL(testRealmURL), {
+			...query,
+			sort: [{
+				by: "_matchRelevance",
+				direction: "asc"
+			}]
+		});
+		assert.deepEqual(getIds(asc.cards), [mango.id, ringo.id], "asc reverses the relevance ordering");
+	});
+	(0, import_qunit.test)(`'_matchRelevance' sort with no positive 'matches' term throws`, async function(assert) {
+		let { mango, vangogh, ringo } = testCards;
+		await setupIndex(dbAdapter, [
+			{
+				card: mango,
+				data: { search_doc: { name: "Mango" } }
+			},
+			{
+				card: vangogh,
+				data: { search_doc: { name: "Van Gogh" } }
+			},
+			{
+				card: ringo,
+				data: { search_doc: { name: "Ringo" } }
+			}
+		]);
+		let type = await personCardType(testCards);
+		await assert.rejects(indexQueryEngine.searchCards(new URL(testRealmURL), {
+			filter: {
+				on: type,
+				eq: { name: "Mango" }
+			},
+			sort: [{
+				by: "_matchRelevance",
+				direction: "desc"
+			}]
+		}), /requires at least one positive `matches` filter/, "a query with no matches term cannot sort by relevance");
+		await assert.rejects(indexQueryEngine.searchCards(new URL(testRealmURL), {
+			filter: {
+				on: type,
+				not: { matches: "mango" }
+			},
+			sort: [{
+				by: "_matchRelevance",
+				direction: "desc"
+			}]
+		}), /requires at least one positive `matches` filter/, "a negated matches term does not count as a positive term");
+	});
+	(0, import_qunit.test)("can sort using a general field that is not an attribute of a card", async function(assert) {
+		await setupIndex(dbAdapter, [
+			{
+				url: `${testRealmURL}vangogh.json`,
+				file_alias: `${testRealmURL}vangogh`,
+				type: "instance",
+				generation: 1,
+				realm_url: testRealmURL,
+				deps: [],
+				types: [`${testRealmURL}person/Person`, "https://cardstack.com/base/card-api/CardDef"],
+				last_modified: "1",
+				resource_created_at: "1"
+			},
+			{
+				url: `${testRealmURL}jimmy.json`,
+				file_alias: `${testRealmURL}jimmy`,
+				type: "instance",
+				generation: 1,
+				realm_url: testRealmURL,
+				deps: [],
+				types: [`${testRealmURL}person/Person`, "https://cardstack.com/base/card-api/CardDef"],
+				last_modified: "3",
+				resource_created_at: "3"
+			},
+			{
+				url: `${testRealmURL}donald.json`,
+				file_alias: `${testRealmURL}donald`,
+				type: "instance",
+				generation: 1,
+				realm_url: testRealmURL,
+				deps: [],
+				types: [`${testRealmURL}person/Person`, "https://cardstack.com/base/card-api/CardDef"],
+				last_modified: "2",
+				resource_created_at: "2"
+			}
+		]);
+		let { results } = await indexQueryEngine.search(new URL(testRealmURL), { sort: [{
+			by: "lastModified",
+			direction: "desc"
+		}] }, { includeErrors: true }, { kind: "dataOnly" });
+		assert.deepEqual(results.map((r) => r.url), [
+			`${testRealmURL}jimmy.json`,
+			`${testRealmURL}donald.json`,
+			`${testRealmURL}vangogh.json`
+		], "results are correct");
+		let { results: results2 } = await indexQueryEngine.search(new URL(testRealmURL), { sort: [{
+			by: "lastModified",
+			direction: "asc"
+		}] }, { includeErrors: true }, { kind: "dataOnly" });
+		assert.deepEqual(results2.map((r) => r.url), [
+			`${testRealmURL}vangogh.json`,
+			`${testRealmURL}donald.json`,
+			`${testRealmURL}jimmy.json`
+		], "results are correct");
+		let { results: results3 } = await indexQueryEngine.search(new URL(testRealmURL), { sort: [{
+			by: "createdAt",
+			direction: "desc"
+		}] }, { includeErrors: true }, { kind: "dataOnly" });
+		assert.deepEqual(results3.map((r) => r.url), [
+			`${testRealmURL}jimmy.json`,
+			`${testRealmURL}donald.json`,
+			`${testRealmURL}vangogh.json`
+		], "results are correct");
+	});
+});
+function getIds(resources) {
+	return resources.map((r) => r.id);
+}
+function internalKeyToCodeRef(key) {
+	let parts = key.split("/");
+	let name = parts.pop();
+	return {
+		module: parts.join("/"),
+		name
+	};
+}
+async function personCardType(testCards) {
+	let { vangogh } = testCards;
+	if (!vangogh) throw new Error(`missing the 'vangogh' test card in the--this is the card we use to derive the Person type`);
+	return internalKeyToCodeRef([...await getTypes(vangogh)].shift());
+}
+async function SimpleSpecType(testCards) {
+	let { stringFieldEntry } = testCards;
+	if (!stringFieldEntry) throw new Error(`missing the 'stringFieldEntry' test card in the--this is the card we use to derive the SimpleSpec type`);
+	return internalKeyToCodeRef([...await getTypes(stringFieldEntry)].shift());
+}
+async function eventType(testCards) {
+	let { mangoBirthday } = testCards;
+	if (!mangoBirthday) throw new Error(`missing the 'mangoBirthday' test card in the--this is the card we use to derive the Event type`);
+	return internalKeyToCodeRef([...await getTypes(mangoBirthday)].shift());
+}
+//#endregion