@cardstack/boxel-cli 0.9.0 → 0.10.0-unstable.0

package/bundled-test-harness/assets/instance-filter-matcher-test-Bs4kf7E8.js

@@ -0,0 +1,788 @@
+import { s as __toESM } from "./chunk-Rp0pCe6z.js";
+import { r as initializeDeferredDecorator, t as decorateFieldV2 } from "./runtime--fcdnjmJ-BoCBNIsz.js";
+import { Ar as testRealmURL, G as makeInstanceComparator, Ia as fetcher, K as matchInstanceAgainstFilter, Ms as Loader, Sa as maybeHandleScopedCSSRequest, W as isClientEvaluable, ja as VirtualNetwork } from "./runtime-common-ClpqhbwG.js";
+import { y as rri } from "./paths-BYHDgqsT.js";
+import { D as baseRealm } from "./constants-CqKWhRfY.js";
+import { t as config } from "./environment-DIUJgBKt.js";
+import { t as shimExternals } from "./externals-CKblKBo1.js";
+import { t as require_qunit } from "./qunit-C-Foo4Nd.js";
+import "./mock-matrix-DPQ0j2MD.js";
+import { t as p } from "./helpers-DA4ARnVh.js";
+//#region tests/unit/instance-filter-matcher-test.ts
+var import_qunit = /* @__PURE__ */ __toESM(require_qunit());
+var { resolvedBaseRealmURL } = config;
+(0, import_qunit.module)("Unit | instance-filter-matcher", function(hooks) {
+	let loader;
+	let api;
+	let personRef;
+	let fancyPersonRef;
+	let catRef;
+	let eventRef;
+	let rankedRef;
+	let cards = {};
+	let rankedA;
+	let rankedB;
+	let fileDef;
+	hooks.beforeEach(async function() {
+		let 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 });
+		let cardApi = await loader.import("@cardstack/base/card-api");
+		let string = await loader.import("@cardstack/base/string");
+		let number = await loader.import("@cardstack/base/number");
+		let boolean = await loader.import("@cardstack/base/boolean");
+		let date = await loader.import("@cardstack/base/date");
+		api = {
+			getQueryableValue: cardApi.getQueryableValue,
+			formatQueryValue: cardApi.formatQueryValue,
+			peekAtField: cardApi.peekAtField,
+			isQueryTaintedField: cardApi.isQueryTaintedField,
+			isNonPresentLink: cardApi.isNonPresentLink,
+			getCardMeta: cardApi.getCardMeta,
+			primitive: cardApi.primitive,
+			virtualNetwork
+		};
+		let { field, contains, containsMany, linksTo, linksToMany, CardDef, FieldDef, FileDef, setCardAsSavedForTest } = cardApi;
+		let { default: StringField } = string;
+		let { default: NumberField } = number;
+		let { default: BooleanField } = boolean;
+		let { default: DateField } = date;
+		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);
+		}
+		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);
+				});
+			}
+			#bestFriend = (initializeDeferredDecorator(this, "bestFriend"), void 0);
+			static {
+				decorateFieldV2(this.prototype, "friends", [field], function() {
+					return linksToMany(() => Person);
+				});
+			}
+			#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, "ageDoubled", [field], function() {
+					return contains(NumberField, { computeVia: function() {
+						return (this.age ?? 0) * 2;
+					} });
+				});
+			}
+			#ageDoubled = (initializeDeferredDecorator(this, "ageDoubled"), 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 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 Ranked extends CardDef {
+			static {
+				decorateFieldV2(this.prototype, "name", [field], function() {
+					return contains(StringField);
+				});
+			}
+			#name = (initializeDeferredDecorator(this, "name"), void 0);
+			static {
+				decorateFieldV2(this.prototype, "_matchRelevance", [field], function() {
+					return contains(NumberField);
+				});
+			}
+			#_matchRelevance = (initializeDeferredDecorator(this, "_matchRelevance"), void 0);
+		}
+		loader.shimModule(`${testRealmURL}person`, { Person });
+		loader.shimModule(`${testRealmURL}fancy-person`, { FancyPerson });
+		loader.shimModule(`${testRealmURL}cat`, { Cat });
+		loader.shimModule(`${testRealmURL}event`, { Event });
+		loader.shimModule(`${testRealmURL}ranked`, { Ranked });
+		personRef = {
+			module: rri(`${testRealmURL}person`),
+			name: "Person"
+		};
+		fancyPersonRef = {
+			module: rri(`${testRealmURL}fancy-person`),
+			name: "FancyPerson"
+		};
+		catRef = {
+			module: rri(`${testRealmURL}cat`),
+			name: "Cat"
+		};
+		eventRef = {
+			module: rri(`${testRealmURL}event`),
+			name: "Event"
+		};
+		rankedRef = {
+			module: rri(`${testRealmURL}ranked`),
+			name: "Ranked"
+		};
+		let ringo = new Person({
+			name: "Ringo",
+			nickNames: ["Ring", "Star"],
+			address: new Address({
+				street: "100 Treat Street",
+				city: "Waggington"
+			}),
+			age: 5,
+			isHairy: true
+		});
+		let vangogh = new Person({
+			name: "Van Gogh",
+			nickNames: ["Vango"],
+			address: new Address({
+				street: "456 Grand Blvd",
+				city: "Barksville"
+			}),
+			age: 7,
+			isHairy: false,
+			bestFriend: ringo,
+			friends: [ringo]
+		});
+		cards = {
+			ringo,
+			vangogh,
+			mango: new FancyPerson({
+				name: "Mango",
+				nickNames: ["Mang", "Go"],
+				address: new Address({
+					street: "123 Main Street",
+					city: "Barksville"
+				}),
+				age: 3,
+				isHairy: true,
+				favoriteColor: "orange",
+				bestFriend: vangogh,
+				friends: [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")
+			})
+		};
+		for (let [name, card] of Object.entries(cards)) {
+			card.id = rri(`${testRealmURL}${name}`);
+			setCardAsSavedForTest(card);
+		}
+		rankedA = new Ranked({
+			name: "a",
+			_matchRelevance: 1
+		});
+		rankedB = new Ranked({
+			name: "b",
+			_matchRelevance: 9
+		});
+		rankedA.id = rri(`${testRealmURL}ranked/a`);
+		rankedB.id = rri(`${testRealmURL}ranked/b`);
+		setCardAsSavedForTest(rankedA);
+		setCardAsSavedForTest(rankedB);
+		let fileURL = `${testRealmURL}files/hello.md`;
+		fileDef = new FileDef({
+			id: fileURL,
+			sourceUrl: fileURL,
+			url: fileURL,
+			name: "hello.md",
+			contentType: "text/markdown"
+		});
+	});
+	function match(card, filter) {
+		return matchInstanceAgainstFilter(card, filter, api);
+	}
+	(0, import_qunit.test)("eq on a string field", function(assert) {
+		let { mango, ringo } = cards;
+		assert.strictEqual(match(mango, {
+			on: personRef,
+			eq: { name: "Mango" }
+		}), "match");
+		assert.strictEqual(match(ringo, {
+			on: personRef,
+			eq: { name: "Mango" }
+		}), "no-match");
+	});
+	(0, import_qunit.test)("eq on a nested contains field", function(assert) {
+		let { mango, ringo } = cards;
+		assert.strictEqual(match(mango, {
+			on: personRef,
+			eq: { "address.city": "Barksville" }
+		}), "match");
+		assert.strictEqual(match(ringo, {
+			on: personRef,
+			eq: { "address.city": "Barksville" }
+		}), "no-match");
+	});
+	(0, import_qunit.test)("eq on number and boolean fields", function(assert) {
+		let { mango, ringo } = cards;
+		assert.strictEqual(match(mango, {
+			on: personRef,
+			eq: { age: 3 }
+		}), "match");
+		assert.strictEqual(match(ringo, {
+			on: personRef,
+			eq: { age: 3 }
+		}), "no-match");
+		assert.strictEqual(match(mango, {
+			on: personRef,
+			eq: { isHairy: true }
+		}), "match");
+		assert.strictEqual(match(cards.vangogh, {
+			on: personRef,
+			eq: { isHairy: true }
+		}), "no-match");
+	});
+	(0, import_qunit.test)("eq null matches an unset linksTo field", function(assert) {
+		let { ringo, mango } = cards;
+		assert.strictEqual(match(ringo, {
+			on: personRef,
+			eq: { bestFriend: null }
+		}), "match");
+		assert.strictEqual(match(mango, {
+			on: personRef,
+			eq: { bestFriend: null }
+		}), "no-match");
+	});
+	(0, import_qunit.test)("eq across a linksTo field path", function(assert) {
+		let { mango } = cards;
+		assert.strictEqual(match(mango, {
+			on: personRef,
+			eq: { "bestFriend.name": "Van Gogh" }
+		}), "match");
+		assert.strictEqual(match(mango, {
+			on: personRef,
+			eq: { "bestFriend.name": "Ringo" }
+		}), "no-match");
+	});
+	(0, import_qunit.test)("an unset interior linksTo resolves to NULL at the leaf", function(assert) {
+		let { ringo } = cards;
+		assert.strictEqual(match(ringo, {
+			on: personRef,
+			eq: { "bestFriend.name": null }
+		}), "match");
+		assert.strictEqual(match(ringo, {
+			on: personRef,
+			eq: { "bestFriend.name": "Van Gogh" }
+		}), "no-match");
+		assert.strictEqual(match(ringo, {
+			on: personRef,
+			in: { "bestFriend.name": [null] }
+		}), "match");
+	});
+	(0, import_qunit.test)("in matches when the value is in the set", function(assert) {
+		let { mango, paper } = cards;
+		assert.strictEqual(match(mango, {
+			on: personRef,
+			in: { name: ["Mango", "Ringo"] }
+		}), "match");
+		assert.strictEqual(match(paper, {
+			on: catRef,
+			in: { name: ["Mango", "Ringo"] }
+		}), "no-match");
+	});
+	(0, import_qunit.test)("in with an empty set matches nothing", function(assert) {
+		let { mango } = cards;
+		assert.strictEqual(match(mango, {
+			on: personRef,
+			in: { name: [] }
+		}), "no-match");
+	});
+	(0, import_qunit.test)("in filter matches a URL-form instance against a prefix-form value", function(assert) {
+		let { mango, ringo } = cards;
+		api.virtualNetwork.addRealmMapping("@test/cards/", testRealmURL);
+		assert.strictEqual(match(mango, {
+			on: personRef,
+			in: { id: ["@test/cards/mango"] }
+		}), "match", "prefix-form `in` value matches the URL-form id");
+		assert.strictEqual(match(ringo, {
+			on: personRef,
+			in: { id: ["@test/cards/mango"] }
+		}), "no-match", "a non-matching prefix-form id is still rejected");
+		assert.strictEqual(match(mango, {
+			on: personRef,
+			in: { id: [`${testRealmURL}mango`] }
+		}), "match", "URL-form `in` value still matches the URL-form id");
+		assert.strictEqual(match(mango, {
+			on: personRef,
+			eq: { id: "@test/cards/mango" }
+		}), "no-match", "prefix-form `eq` value does not match (eq stays exact)");
+		assert.strictEqual(match(mango, {
+			on: personRef,
+			eq: { id: `${testRealmURL}mango` }
+		}), "match", "exact URL-form `eq` value matches");
+	});
+	(0, import_qunit.test)("contains is a case-insensitive substring match", function(assert) {
+		let { mango, ringo } = cards;
+		assert.strictEqual(match(mango, {
+			on: personRef,
+			contains: { name: "ang" }
+		}), "match");
+		assert.strictEqual(match(mango, {
+			on: personRef,
+			contains: { name: "MANG" }
+		}), "match");
+		assert.strictEqual(match(ringo, {
+			on: personRef,
+			contains: { name: "ang" }
+		}), "no-match");
+	});
+	(0, import_qunit.test)("contains matches existentially over a containsMany field", function(assert) {
+		let { mango, ringo } = cards;
+		assert.strictEqual(match(mango, {
+			on: personRef,
+			contains: { nickNames: "go" }
+		}), "match");
+		assert.strictEqual(match(ringo, {
+			on: personRef,
+			contains: { nickNames: "go" }
+		}), "no-match");
+	});
+	(0, import_qunit.test)("range on a number field", function(assert) {
+		let { mango, vangogh } = cards;
+		assert.strictEqual(match(vangogh, {
+			on: personRef,
+			range: { age: { gt: 5 } }
+		}), "match");
+		assert.strictEqual(match(mango, {
+			on: personRef,
+			range: { age: { gt: 5 } }
+		}), "no-match");
+		assert.strictEqual(match(mango, {
+			on: personRef,
+			range: { age: {
+				gte: 3,
+				lte: 5
+			} }
+		}), "match");
+	});
+	(0, import_qunit.test)("range on a date field", function(assert) {
+		let { mangoBirthday, vangoghBirthday } = cards;
+		assert.strictEqual(match(vangoghBirthday, {
+			on: eventRef,
+			range: { date: { gt: "2024-11-01" } }
+		}), "match");
+		assert.strictEqual(match(mangoBirthday, {
+			on: eventRef,
+			range: { date: { gt: "2024-11-01" } }
+		}), "no-match");
+	});
+	(0, import_qunit.test)("a query-tainted computed resolves as unresolvable, never a client-only match", function(assert) {
+		let { mango } = cards;
+		assert.strictEqual(match(mango, {
+			on: personRef,
+			range: { ageDoubled: { gt: 0 } }
+		}), "match", "a computed that reads no query field resolves and matches normally");
+		let taintedApi = {
+			...api,
+			isQueryTaintedField: (_instance, fieldName) => fieldName === "ageDoubled"
+		};
+		assert.strictEqual(matchInstanceAgainstFilter(mango, {
+			on: personRef,
+			range: { ageDoubled: { gt: 0 } }
+		}, taintedApi), "unresolvable", "a query-derived computed the server omits is not matched client-side");
+	});
+	(0, import_qunit.test)("a pure type filter walks the adoptsFrom chain", function(assert) {
+		let { mango, paper } = cards;
+		assert.strictEqual(match(mango, { type: personRef }), "match");
+		assert.strictEqual(match(mango, { type: fancyPersonRef }), "match");
+		assert.strictEqual(match(paper, { type: personRef }), "no-match");
+		assert.strictEqual(match(paper, { type: catRef }), "match");
+	});
+	(0, import_qunit.test)("a type gate tolerates equivalent module spellings", function(assert) {
+		let { mango } = cards;
+		api.virtualNetwork.addURLMapping(new URL("https://virtual-alias.example/test/"), new URL(testRealmURL));
+		let aliasedPersonRef = {
+			module: rri("https://virtual-alias.example/test/person"),
+			name: "Person"
+		};
+		assert.strictEqual(match(mango, { type: aliasedPersonRef }), "match", "pure type filter matches across spellings");
+		assert.strictEqual(match(mango, {
+			on: aliasedPersonRef,
+			eq: { name: "Mango" }
+		}), "match", "on-gate matches across spellings");
+	});
+	(0, import_qunit.test)("an on-scoped predicate gates by type", function(assert) {
+		let { mango, vangogh } = cards;
+		assert.strictEqual(match(mango, {
+			on: fancyPersonRef,
+			eq: { favoriteColor: "orange" }
+		}), "match");
+		assert.strictEqual(match(vangogh, {
+			on: fancyPersonRef,
+			eq: { favoriteColor: "orange" }
+		}), "no-match");
+	});
+	(0, import_qunit.test)("every requires all sub-filters", function(assert) {
+		let { mango } = cards;
+		assert.strictEqual(match(mango, {
+			on: personRef,
+			every: [{ eq: { name: "Mango" } }, { eq: { age: 3 } }]
+		}), "match");
+		assert.strictEqual(match(mango, {
+			on: personRef,
+			every: [{ eq: { name: "Mango" } }, { eq: { age: 99 } }]
+		}), "no-match");
+	});
+	(0, import_qunit.test)("any requires at least one sub-filter", function(assert) {
+		let { mango } = cards;
+		assert.strictEqual(match(mango, {
+			on: personRef,
+			any: [{ eq: { name: "Nobody" } }, { eq: { age: 3 } }]
+		}), "match");
+		assert.strictEqual(match(mango, {
+			on: personRef,
+			any: [{ eq: { name: "Nobody" } }, { eq: { age: 99 } }]
+		}), "no-match");
+	});
+	(0, import_qunit.test)("not negates its child", function(assert) {
+		let { mango, ringo } = cards;
+		assert.strictEqual(match(ringo, {
+			on: personRef,
+			not: { eq: { name: "Mango" } }
+		}), "match");
+		assert.strictEqual(match(mango, {
+			on: personRef,
+			not: { eq: { name: "Mango" } }
+		}), "no-match");
+	});
+	(0, import_qunit.test)("deeply nested every/any/not tree", function(assert) {
+		let { mango } = cards;
+		let filter = {
+			on: personRef,
+			every: [
+				{ any: [{ eq: { name: "Mango" } }, { eq: { name: "Ringo" } }] },
+				{ not: { eq: { age: 99 } } },
+				{ range: { age: { lt: 10 } } }
+			]
+		};
+		assert.strictEqual(match(mango, filter), "match");
+	});
+	(0, import_qunit.test)("existential match over a linksToMany path", function(assert) {
+		let { mango } = cards;
+		assert.strictEqual(match(mango, {
+			on: personRef,
+			eq: { "friends.name": "Ringo" }
+		}), "match");
+		assert.strictEqual(match(mango, {
+			on: personRef,
+			eq: { "friends.name": "Nobody" }
+		}), "no-match");
+	});
+	(0, import_qunit.test)("a not-loaded linksTo target is reported as unresolvable", async function(assert) {
+		let cardApi = await loader.import("@cardstack/base/card-api");
+		let doc = { data: {
+			id: `${testRealmURL}lonely`,
+			type: "card",
+			attributes: { name: "Lonely" },
+			relationships: { bestFriend: { links: { self: `${testRealmURL}ghost` } } },
+			meta: { adoptsFrom: personRef }
+		} };
+		let lonely = await cardApi.createFromSerialized(doc.data, doc, new URL(testRealmURL));
+		assert.strictEqual(match(lonely, {
+			on: personRef,
+			eq: { "bestFriend.name": "Van Gogh" }
+		}), "unresolvable", "a predicate over an unloaded link is unresolvable, never no-match");
+		assert.strictEqual(match(lonely, {
+			on: personRef,
+			not: { eq: { "bestFriend.name": "Van Gogh" } }
+		}), "unresolvable");
+		assert.strictEqual(match(lonely, {
+			on: personRef,
+			eq: { name: "Lonely" }
+		}), "match");
+	});
+	(0, import_qunit.test)("isClientEvaluable rejects matches and unsupported operators", function(assert) {
+		assert.false(isClientEvaluable({ matches: "hello" }));
+		assert.false(isClientEvaluable({
+			on: personRef,
+			every: [{ eq: { name: "x" } }, { matches: "y" }]
+		}));
+		assert.false(isClientEvaluable({
+			on: personRef,
+			any: [{ matches: "y" }]
+		}));
+		assert.false(isClientEvaluable({ not: { matches: "y" } }));
+	});
+	(0, import_qunit.test)("isClientEvaluable accepts every supported operator", function(assert) {
+		assert.true(isClientEvaluable({
+			on: personRef,
+			eq: { name: "x" }
+		}));
+		assert.true(isClientEvaluable({
+			on: personRef,
+			in: { name: ["x"] }
+		}));
+		assert.true(isClientEvaluable({
+			on: personRef,
+			contains: { name: "x" }
+		}));
+		assert.true(isClientEvaluable({
+			on: personRef,
+			range: { age: { gt: 1 } }
+		}));
+		assert.true(isClientEvaluable({ type: personRef }));
+		assert.true(isClientEvaluable({
+			on: personRef,
+			every: [{ any: [{ eq: { name: "x" } }, { not: { eq: { age: 1 } } }] }, { range: { age: { lt: 9 } } }]
+		}));
+	});
+	(0, import_qunit.test)("isClientEvaluable declines a filter carrying more than one operator", function(assert) {
+		assert.false(isClientEvaluable({
+			on: personRef,
+			eq: { name: "x" },
+			contains: { name: "y" }
+		}));
+		assert.false(isClientEvaluable({ every: [{
+			on: personRef,
+			eq: { name: "x" },
+			range: { age: { gt: 1 } }
+		}] }), "a multi-operator node nested under every also declines");
+	});
+	(0, import_qunit.test)("comparator orders by a single on-field key with direction", function(assert) {
+		let { mango, vangogh, ringo } = cards;
+		let sort = [{
+			on: personRef,
+			by: "name",
+			direction: "asc"
+		}];
+		let sorted = [
+			vangogh,
+			ringo,
+			mango
+		].sort(makeInstanceComparator(sort, api));
+		assert.deepEqual(sorted.map((c) => c.name), [
+			"Mango",
+			"Ringo",
+			"Van Gogh"
+		]);
+		let desc = [{
+			on: personRef,
+			by: "name",
+			direction: "desc"
+		}];
+		let sortedDesc = [
+			mango,
+			ringo,
+			vangogh
+		].sort(makeInstanceComparator(desc, api));
+		assert.deepEqual(sortedDesc.map((c) => c.name), [
+			"Van Gogh",
+			"Ringo",
+			"Mango"
+		]);
+	});
+	(0, import_qunit.test)("comparator orders by multiple keys", function(assert) {
+		let { mango, vangogh, ringo } = cards;
+		let sort = [{
+			on: personRef,
+			by: "address.city",
+			direction: "asc"
+		}, {
+			on: personRef,
+			by: "name",
+			direction: "desc"
+		}];
+		let sorted = [
+			ringo,
+			mango,
+			vangogh
+		].sort(makeInstanceComparator(sort, api));
+		assert.deepEqual(sorted.map((c) => c.name), [
+			"Van Gogh",
+			"Mango",
+			"Ringo"
+		], "Barksville (Van Gogh, Mango by name desc) then Waggington (Ringo)");
+	});
+	(0, import_qunit.test)("comparator falls back to card URL as a deterministic tiebreak", function(assert) {
+		let { mango, ringo } = cards;
+		let sorted = [ringo, mango].sort(makeInstanceComparator(void 0, api));
+		assert.deepEqual(sorted.map((c) => c.id), [mango.id, ringo.id], "mango sorts before ringo by URL");
+	});
+	(0, import_qunit.test)("a relevance sort ignores a same-named field and falls back to URL order", function(assert) {
+		for (let sort of [[{
+			by: "_matchRelevance",
+			direction: "desc"
+		}], [{
+			by: "_matchRelevance",
+			on: rankedRef,
+			direction: "desc"
+		}]]) {
+			let sorted = [rankedB, rankedA].sort(makeInstanceComparator(sort, api));
+			assert.deepEqual(sorted.map((c) => c.id), [rankedA.id, rankedB.id], `${JSON.stringify(sort)} ignores the _matchRelevance field and sorts by URL`);
+		}
+	});
+	async function hydrateFile(name, timestamps) {
+		let cardApi = await loader.import("@cardstack/base/card-api");
+		let url = `${testRealmURL}files/${name}`;
+		let doc = { data: {
+			id: url,
+			type: "file-meta",
+			attributes: {
+				name,
+				url,
+				contentType: "text/markdown"
+			},
+			meta: {
+				adoptsFrom: {
+					module: `${baseRealm.url}card-api`,
+					name: "FileDef"
+				},
+				lastModified: timestamps.lastModified,
+				resourceCreatedAt: timestamps.resourceCreatedAt
+			}
+		} };
+		return await cardApi.createFromSerialized(doc.data, doc, new URL(testRealmURL));
+	}
+	(0, import_qunit.test)("a hydrated FileDef exposes its meta timestamps through the getters", async function(assert) {
+		let cardApi = await loader.import("@cardstack/base/card-api");
+		let file = await hydrateFile("report.md", {
+			lastModified: 1700000500,
+			resourceCreatedAt: 17e8
+		});
+		assert.strictEqual(file.lastModified, 1700000500, "lastModified getter reads off meta");
+		assert.strictEqual(file.resourceCreatedAt, 17e8, "resourceCreatedAt getter reads off meta");
+		assert.strictEqual(cardApi.getCardMeta(file, "lastModified"), 1700000500, "getCardMeta answers for a file the same way it does for a card");
+		assert.strictEqual(cardApi.getCardMeta(file, "resourceCreatedAt"), 17e8, "getCardMeta resolves resourceCreatedAt for a file");
+	});
+	(0, import_qunit.test)("comparator orders files by their meta lastModified / createdAt", async function(assert) {
+		let files = [await hydrateFile("older.md", {
+			lastModified: 100,
+			resourceCreatedAt: 10
+		}), await hydrateFile("newer.md", {
+			lastModified: 200,
+			resourceCreatedAt: 20
+		})];
+		let byModifiedDesc = [{
+			by: "lastModified",
+			direction: "desc"
+		}];
+		assert.deepEqual([...files].sort(makeInstanceComparator(byModifiedDesc, api)).map((f) => f.name), ["newer.md", "older.md"], "newest lastModified first");
+		let byCreatedAsc = [{
+			by: "createdAt",
+			direction: "asc"
+		}];
+		assert.deepEqual([...files].sort(makeInstanceComparator(byCreatedAsc, api)).map((f) => f.name), ["older.md", "newer.md"], "oldest createdAt first");
+	});
+	(0, import_qunit.test)("_title contains resolves to the card title", function(assert) {
+		let { mangoBirthday, vangoghBirthday } = cards;
+		assert.strictEqual(match(mangoBirthday, { contains: { _title: "Mango" } }), "match", "mangoBirthday's title contains Mango");
+		assert.strictEqual(match(vangoghBirthday, { contains: { _title: "Mango" } }), "no-match", "vangoghBirthday's title does not contain Mango");
+	});
+	(0, import_qunit.test)("_title comparator orders by the card title, not URL", function(assert) {
+		let { mangoBirthday, vangoghBirthday } = cards;
+		let sort = [{
+			on: eventRef,
+			by: "_title",
+			direction: "asc"
+		}];
+		let sorted = [vangoghBirthday, mangoBirthday].sort(makeInstanceComparator(sort, api));
+		assert.deepEqual(sorted.map((c) => c.cardTitle), ["Mango's Birthday", "Van Gogh's Birthday"], "A-Z by title (would be URL order without the _title shim)");
+	});
+	(0, import_qunit.test)("_cardType is non-null for a card instance", function(assert) {
+		let { mango } = cards;
+		assert.strictEqual(match(mango, { eq: { _cardType: null } }), "no-match", "_cardType is not null on a hydrated card");
+		assert.strictEqual(match(mango, { not: { eq: { _cardType: null } } }), "match");
+	});
+	(0, import_qunit.test)("_isCardInstanceFile: false matches a hydrated card (the dedup filter keeps cards)", function(assert) {
+		let { mango } = cards;
+		assert.strictEqual(match(mango, { eq: { _isCardInstanceFile: false } }), "match", "a hydrated card is not a card-instance file, so the dedup keeps it");
+		assert.strictEqual(match(mango, { eq: { _isCardInstanceFile: true } }), "no-match");
+	});
+	(0, import_qunit.test)("isClientEvaluable keeps shimmed synthetic keys but rejects unshimmed underscore keys", function(assert) {
+		assert.true(isClientEvaluable({ eq: { _isCardInstanceFile: false } }), "a shimmed synthetic key stays client-evaluable");
+		assert.true(isClientEvaluable({ contains: { _title: "x" } }));
+		assert.true(isClientEvaluable({ eq: { name: "Mango" } }), "a real field");
+		assert.true(isClientEvaluable({ eq: { id: "x" } }), "the id identity key is a real field and stays client-evaluable (so file id filters route through the matcher, not server-only)");
+		assert.false(isClientEvaluable({ eq: { _mysteryServerKey: 1 } }), "an unshimmed underscore key forces server-only evaluation");
+	});
+	(0, import_qunit.test)("eq on id matches a FileDef by its url", function(assert) {
+		assert.strictEqual(matchInstanceAgainstFilter(fileDef, { eq: { id: `${testRealmURL}files/hello.md` } }, api), "match", "a file matches its own id");
+		assert.strictEqual(matchInstanceAgainstFilter(fileDef, { eq: { id: `${testRealmURL}files/other.md` } }, api), "no-match", "a file does not match a different id");
+	});
+	(0, import_qunit.test)("not: eq on id excludes a FileDef by its url (the already-selected exclusion)", function(assert) {
+		assert.strictEqual(matchInstanceAgainstFilter(fileDef, { not: { eq: { id: `${testRealmURL}files/hello.md` } } }, api), "no-match", "excluding a file by its id removes it");
+	});
+});
+//#endregion