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

package/bundled-test-harness/assets/store-module-rebuild-test-HyphFJiF.js

@@ -0,0 +1,454 @@
+import { s as __toESM } from "./chunk-Rp0pCe6z.js";
+import { r as initializeDeferredDecorator, t as decorateFieldV2 } from "./runtime--fcdnjmJ-BoCBNIsz.js";
+import { Ar as testRealmURL, Po as isCardInstance } from "./runtime-common-ClpqhbwG.js";
+import { y as rri } from "./paths-BYHDgqsT.js";
+import { wt as setComponentTemplate } from "./cache-DtDz7X5V-Wn8jRDfL.js";
+import { H as templateFactory } from "./index-DaCZcoCY-CgzbilMy.js";
+import "./component-BJO47HTh.js";
+import { t as Component } from "./dist-CkA1rgqO.js";
+import { n as tracked } from "./tracking-800VJb8b.js";
+import "./template-factory-ds9s0u8l.js";
+import { n as getCard } from "./card-resource-JGLjQUy6.js";
+import { M as waitUntil, T as settled, o as waitFor } from "./dist-BOAdzfkP.js";
+import { t as require_qunit } from "./qunit-C-Foo4Nd.js";
+import { F as setupLocalIndexing, I as setupOnSave, M as setupCardLogs, P as setupIntegrationTestRealm, lt as setupRenderingTest, t as setupMockMatrix } from "./mock-matrix-DPQ0j2MD.js";
+import { r as getService } from "./dist-CPfIHBla.js";
+import { A as field, H as linksTo, a as CardDef, s as Component$1, w as contains } from "./card-api-Dzje0smT.js";
+import { t as string_default } from "./string-BHZZwNlZ.js";
+import { n as renderComponent } from "./render-component-B15Z0e2v.js";
+//#region tests/integration/store-module-rebuild-test.gts
+var import_qunit = /* @__PURE__ */ __toESM(require_qunit());
+(0, import_qunit.module)("Integration | Store | module rebuild", function(hooks) {
+	setupRenderingTest(hooks);
+	let loader;
+	let loaderService;
+	let storeService;
+	let realmService;
+	setupLocalIndexing(hooks);
+	setupOnSave(hooks);
+	setupCardLogs(hooks, async () => await loader.import("@cardstack/base/card-api"));
+	let mockMatrixUtils = setupMockMatrix(hooks, {
+		loggedInAs: "@testuser:localhost",
+		activeRealms: [testRealmURL],
+		autostart: true
+	});
+	hooks.beforeEach(async function() {
+		class Person extends CardDef {
+			static {
+				decorateFieldV2(this.prototype, "name", [field], function() {
+					return contains(string_default);
+				});
+			}
+			#name = (initializeDeferredDecorator(this, "name"), void 0);
+			static {
+				decorateFieldV2(this.prototype, "bestFriend", [field], function() {
+					return linksTo(() => Person);
+				});
+			}
+			#bestFriend = (initializeDeferredDecorator(this, "bestFriend"), void 0);
+		}
+		class Employee extends CardDef {
+			static displayName = "Employee";
+			static {
+				decorateFieldV2(this.prototype, "name", [field], function() {
+					return contains(string_default);
+				});
+			}
+			#name = (initializeDeferredDecorator(this, "name"), void 0);
+			static isolated = class Isolated extends Component$1 {
+				static {
+					setComponentTemplate(templateFactory({
+						"id": "wOdepAzY",
+						"block": "[[[10,0],[14,\"data-test-employee-badge\",\"\"],[12],[1,\"Employee: \"],[8,[30,1,[\"name\"]],null,null,null],[13]],[\"@fields\"],[]]",
+						"moduleName": "/home/runner/work/boxel/boxel/packages/host/tests/integration/store-module-rebuild-test.gts",
+						"isStrictMode": true
+					}), this);
+				}
+			};
+		}
+		loaderService = getService("loader-service");
+		loader = loaderService.loader;
+		storeService = getService("store");
+		realmService = getService("realm");
+		await setupIntegrationTestRealm({
+			mockMatrixUtils,
+			contents: {
+				"person.gts": { Person },
+				"employee.gts": { Employee },
+				"Person/hassan.json": new Person({ name: "Hassan" })
+			}
+		});
+		await realmService.login(testRealmURL);
+	});
+	function countRebuilds() {
+		let count = 0;
+		let original = loaderService.resetLoader;
+		loaderService.resetLoader = function(options) {
+			count++;
+			return original.call(loaderService, options);
+		};
+		return {
+			get count() {
+				return count;
+			},
+			restore() {
+				loaderService.resetLoader = original;
+			}
+		};
+	}
+	async function renderCard(id) {
+		class Driver {
+			static {
+				decorateFieldV2(this.prototype, "id", [tracked]);
+			}
+			#id = (initializeDeferredDecorator(this, "id"), void 0);
+		}
+		let driver = new Driver();
+		class ResourceConsumer extends Component {
+			resource = getCard(this, () => driver.id);
+			get renderedCard() {
+				return this.resource.card?.constructor.getComponent(this.resource.card);
+			}
+			static {
+				setComponentTemplate(templateFactory({
+					"id": "xU+ZT9Q9",
+					"block": "[[[41,[30,0,[\"resource\",\"card\"]],[[[1,\"  \"],[8,[30,0,[\"renderedCard\"]],[[16,\"data-test-rendered-card\",[30,0,[\"resource\",\"id\"]]]],null,null],[1,\"\\n\"]],[]],null]],[],[\"if\"]]",
+					"moduleName": "/home/runner/work/boxel/boxel/packages/host/tests/integration/store-module-rebuild-test.gts",
+					"isStrictMode": true
+				}), this);
+			}
+		}
+		await renderComponent(class TestDriver extends Component {
+			static {
+				setComponentTemplate(templateFactory({
+					"id": "VCXG7xoQ",
+					"block": "[[[8,[32,0],null,null,null]],[],[]]",
+					"moduleName": "/home/runner/work/boxel/boxel/packages/host/tests/integration/store-module-rebuild-test.gts",
+					"scope": () => [ResourceConsumer],
+					"isStrictMode": true
+				}), this);
+			}
+		});
+		driver.id = id;
+		await waitFor(`[data-test-rendered-card="${id}"]`, { timeout: 5e3 });
+	}
+	(0, import_qunit.test)("a burst of executable invalidations coalesces to at most two rebuilds", async function(assert) {
+		let hassan = `${testRealmURL}Person/hassan`;
+		await renderCard(hassan);
+		let personModule = `${testRealmURL}person.gts`;
+		assert.true(loaderService.loader.isModuleLoaded(personModule), "precondition: the person module is loaded");
+		let rebuilds = countRebuilds();
+		try {
+			let event = {
+				eventName: "index",
+				indexType: "incremental",
+				realmURL: testRealmURL,
+				invalidations: [personModule]
+			};
+			for (let i = 0; i < 6; i++) storeService.handleInvalidations(event);
+			await settled();
+		} finally {
+			rebuilds.restore();
+		}
+		let coalesced = rebuilds.count >= 1 && rebuilds.count <= 2;
+		assert.ok(coalesced, `6 rapid executable invalidations coalesce to at most 2 rebuilds (saw ${rebuilds.count})`);
+		await waitFor(`[data-test-rendered-card="${hassan}"]`, { timeout: 5e3 });
+		let instance = storeService.peek(hassan);
+		assert.true(isCardInstance(instance), "the open card is re-established after the burst");
+		assert.strictEqual(instance.name, "Hassan", "the re-established card reflects current server state");
+		assert.strictEqual(storeService.getReferenceCount(hassan), 1, "reference count stays balanced across the burst");
+	});
+	(0, import_qunit.test)("an isolated executable invalidation still triggers exactly one rebuild", async function(assert) {
+		let hassan = `${testRealmURL}Person/hassan`;
+		await renderCard(hassan);
+		let personModule = `${testRealmURL}person.gts`;
+		assert.true(loaderService.loader.isModuleLoaded(personModule), "precondition: the person module is loaded");
+		let rebuilds = countRebuilds();
+		try {
+			storeService.handleInvalidations({
+				eventName: "index",
+				indexType: "incremental",
+				realmURL: testRealmURL,
+				invalidations: [personModule]
+			});
+			await settled();
+		} finally {
+			rebuilds.restore();
+		}
+		assert.strictEqual(rebuilds.count, 1, "a single executable invalidation resets exactly once, as before");
+		await waitFor(`[data-test-rendered-card="${hassan}"]`, { timeout: 5e3 });
+		assert.true(isCardInstance(storeService.peek(hassan)), "the card is re-established after the single rebuild");
+	});
+	function captureTelemetry() {
+		let telemetry = getService("client-telemetry");
+		let captured = [];
+		telemetry.enableForTest();
+		let original = telemetry.recordEvent;
+		telemetry.recordEvent = function(evt) {
+			captured.push(evt);
+			return original.call(telemetry, evt);
+		};
+		return {
+			events(eventType) {
+				return captured.filter((e) => e.event_type === eventType);
+			},
+			summary() {
+				return captured.map((e) => e.event_type).join(",") || "<none>";
+			},
+			async waitForEvent(eventType) {
+				try {
+					await waitUntil(() => this.events(eventType).length > 0, { timeout: 1e4 });
+				} catch {}
+			},
+			restore() {
+				telemetry.recordEvent = original;
+				telemetry.teardown();
+			}
+		};
+	}
+	(0, import_qunit.test)("a rebuild emits a rebuild telemetry event describing the code change", async function(assert) {
+		await renderCard(`${testRealmURL}Person/hassan`);
+		let personModule = `${testRealmURL}person.gts`;
+		assert.true(loaderService.loader.isModuleLoaded(personModule), "precondition: the person module is loaded");
+		let telemetry = captureTelemetry();
+		try {
+			assert.true(getService("client-telemetry").isEnabled, "precondition: the instrument is armed");
+			storeService.handleInvalidations({
+				eventName: "index",
+				indexType: "incremental",
+				realmURL: testRealmURL,
+				invalidations: [personModule]
+			});
+			await telemetry.waitForEvent("rebuild");
+			await settled();
+		} finally {
+			telemetry.restore();
+		}
+		let rebuilds = telemetry.events("rebuild");
+		assert.strictEqual(rebuilds.length, 1, `one rebuild event is emitted (captured: ${telemetry.summary()})`);
+		let rebuild = rebuilds[0];
+		assert.strictEqual(rebuild.rebuild_source, "realm-event", "an event-driven rebuild names its source");
+		assert.strictEqual(rebuild.trigger_module, personModule, "the invalidated module is the scalar grouping key");
+		assert.deepEqual(rebuild.trigger_modules, [personModule], "the full trigger set names the invalidated module");
+		assert.strictEqual(rebuild.coalesced_events, 1, "an isolated edit reports a single coalesced event");
+		assert.strictEqual(rebuild.modules_refetched, 1, "the loaded module counts as refetched");
+		assert.strictEqual(rebuild.realm, testRealmURL, "the event is attributed to the realm that was written to");
+		assert.true(rebuild.cards_reloaded >= 1, `the open card graph is re-established (${rebuild.cards_reloaded} reloaded)`);
+	});
+	(0, import_qunit.test)("saving a module from the app rebuilds and reports it", async function(assert) {
+		let hassan = `${testRealmURL}Person/hassan`;
+		await renderCard(hassan);
+		let personModule = `${testRealmURL}person.gts`;
+		assert.true(loaderService.loader.isModuleLoaded(personModule), "precondition: the person module is loaded");
+		let cardService = getService("card-service");
+		let { content } = await cardService.getSource(rri(personModule));
+		let telemetry = captureTelemetry();
+		try {
+			await cardService.saveSource(new URL(personModule), content, "editor", { resetLoader: true });
+			assert.false(loaderService.loader.isModuleLoaded(personModule), "precondition: the write flushed the module out of the loader");
+			storeService.handleInvalidations({
+				eventName: "index",
+				indexType: "incremental",
+				realmURL: testRealmURL,
+				invalidations: [personModule]
+			});
+			await telemetry.waitForEvent("rebuild");
+			await settled();
+		} finally {
+			telemetry.restore();
+		}
+		let rebuilds = telemetry.events("rebuild");
+		assert.strictEqual(rebuilds.length, 1, `the invalidation after the write still rebuilds (captured: ${telemetry.summary()})`);
+		assert.strictEqual(rebuilds[0].trigger_module, personModule, "the saved module is named as the rebuild trigger");
+		assert.strictEqual(rebuilds[0].modules_refetched, 1, "the module the write flushed still counts as refetched");
+		await waitFor(`[data-test-rendered-card="${hassan}"]`, { timeout: 5e3 });
+		assert.true(isCardInstance(storeService.peek(hassan)), "the card is re-established after the rebuild");
+	});
+	(0, import_qunit.test)("a write-time rebuild reports the cards it re-established", async function(assert) {
+		await renderCard(`${testRealmURL}Person/hassan`);
+		let personModule = `${testRealmURL}person.gts`;
+		let telemetry = captureTelemetry();
+		try {
+			storeService.refreshReferencesForCodeChange("file write", {
+				triggerModule: personModule,
+				realm: testRealmURL
+			});
+			await telemetry.waitForEvent("rebuild");
+			await settled();
+		} finally {
+			telemetry.restore();
+		}
+		let rebuilds = telemetry.events("rebuild");
+		assert.strictEqual(rebuilds.length, 1, `one write-time rebuild is reported (captured: ${telemetry.summary()})`);
+		assert.true(rebuilds[0].cards_reloaded >= 1, `the re-established graph is counted (${rebuilds[0].cards_reloaded} reloaded)`);
+		assert.strictEqual(rebuilds[0].rebuild_source, "write", "the save is the source");
+	});
+	(0, import_qunit.test)("a code-mode save reports the rebuild it performs at write time", async function(assert) {
+		let personModule = `${testRealmURL}person.gts`;
+		await loaderService.loader.import(personModule);
+		let telemetry = captureTelemetry();
+		try {
+			storeService.refreshReferencesForCodeChange("file write", {
+				triggerModule: personModule,
+				realm: testRealmURL
+			});
+			await telemetry.waitForEvent("rebuild");
+			await settled();
+		} finally {
+			telemetry.restore();
+		}
+		let rebuilds = telemetry.events("rebuild");
+		assert.strictEqual(rebuilds.length, 1, `the write-time re-establishment is reported (captured: ${telemetry.summary()})`);
+		let rebuild = rebuilds[0];
+		assert.strictEqual(rebuild.rebuild_source, "write", "the source names the save");
+		assert.strictEqual(rebuild.trigger_module, personModule, "the saved module is the trigger");
+		assert.strictEqual(rebuild.realm, testRealmURL, "the event is attributed to the realm written to");
+		assert.strictEqual(rebuild.coalesced_events, 0, "no index event drove this rebuild");
+		assert.strictEqual(rebuild.modules_refetched, 0, "a write-sourced rebuild does not claim module re-imports it cannot measure");
+	});
+	(0, import_qunit.test)("a realm event carries its raw args minus the invalidation list", async function(assert) {
+		let hassan = `${testRealmURL}Person/hassan`;
+		await renderCard(hassan);
+		let telemetry = captureTelemetry();
+		try {
+			storeService.handleInvalidations({
+				eventName: "index",
+				indexType: "incremental",
+				realmURL: testRealmURL,
+				clientRequestId: "editor:test-request",
+				invalidations: [hassan]
+			});
+			await settled();
+		} finally {
+			telemetry.restore();
+		}
+		let events = telemetry.events("realm-event");
+		assert.strictEqual(events.length, 1, "one realm-event is emitted");
+		let args = events[0].event_args;
+		assert.strictEqual(args.eventName, "index", "the raw event name rides along");
+		assert.strictEqual(args.clientRequestId, "editor:test-request", "fields beyond the tracked ones are preserved");
+		assert.false("invalidations" in args, "the invalidation list is tracked separately, not duplicated");
+	});
+	(0, import_qunit.test)("a flush blinds every loaded module, not just the one written", async function(assert) {
+		await renderCard(`${testRealmURL}Person/hassan`);
+		let employeeModule = `${testRealmURL}employee.gts`;
+		await loaderService.loader.import(employeeModule);
+		assert.true(loaderService.loader.isModuleLoaded(employeeModule), "precondition: a second module is loaded");
+		let telemetry = captureTelemetry();
+		try {
+			loaderService.resetLoader({
+				clearFetchCache: true,
+				reason: "source-write",
+				codeChange: true
+			});
+			assert.false(loaderService.loader.isModuleLoaded(employeeModule), "precondition: the flush took the second module with it");
+			storeService.handleInvalidations({
+				eventName: "index",
+				indexType: "incremental",
+				realmURL: testRealmURL,
+				invalidations: [employeeModule]
+			});
+			await telemetry.waitForEvent("rebuild");
+			await settled();
+		} finally {
+			telemetry.restore();
+		}
+		assert.strictEqual(telemetry.events("rebuild").length, 1, `a module the flush discarded still rebuilds (captured: ${telemetry.summary()})`);
+	});
+	(0, import_qunit.test)("a flush during a rebuild is still picked up by the invalidation after it", async function(assert) {
+		await renderCard(`${testRealmURL}Person/hassan`);
+		let personModule = `${testRealmURL}person.gts`;
+		let employeeModule = `${testRealmURL}employee.gts`;
+		let telemetry = captureTelemetry();
+		try {
+			storeService.handleInvalidations({
+				eventName: "index",
+				indexType: "incremental",
+				realmURL: testRealmURL,
+				invalidations: [personModule]
+			});
+			await waitUntil(() => storeService.rebuildForCodeChange.isRunning, { timeout: 5e3 });
+			await loaderService.loader.import(employeeModule);
+			loaderService.resetLoader({
+				clearFetchCache: true,
+				reason: "file-resource-external-invalidation",
+				codeChange: true
+			});
+			await telemetry.waitForEvent("rebuild");
+			await settled();
+			let afterFirst = telemetry.events("rebuild").length;
+			storeService.handleInvalidations({
+				eventName: "index",
+				indexType: "incremental",
+				realmURL: testRealmURL,
+				invalidations: [employeeModule]
+			});
+			await waitUntil(() => telemetry.events("rebuild").length > afterFirst, { timeout: 1e4 }).catch(() => {});
+			await settled();
+			assert.true(telemetry.events("rebuild").length > afterFirst, `the invalidation after the rebuild still rebuilds (captured: ${telemetry.summary()})`);
+		} finally {
+			telemetry.restore();
+		}
+	});
+	(0, import_qunit.test)("an invalidation for a module nothing loaded does not rebuild", async function(assert) {
+		await renderCard(`${testRealmURL}Person/hassan`);
+		let telemetry = captureTelemetry();
+		try {
+			loaderService.resetLoader({
+				clearFetchCache: true,
+				reason: "source-write",
+				codeChange: true
+			});
+			storeService.handleInvalidations({
+				eventName: "index",
+				indexType: "incremental",
+				realmURL: testRealmURL,
+				invalidations: [`${testRealmURL}never-loaded.gts`]
+			});
+			await settled();
+		} finally {
+			telemetry.restore();
+		}
+		assert.strictEqual(telemetry.events("rebuild").length, 0, `a module nothing loaded does not rebuild (captured: ${telemetry.summary()})`);
+	});
+	(0, import_qunit.test)("a flush record does not survive a session boundary", async function(assert) {
+		let personModule = `${testRealmURL}person.gts`;
+		loaderService.resetLoader({
+			clearFetchCache: true,
+			reason: "source-write",
+			codeChange: true
+		});
+		assert.true(loaderService.wasModuleFlushedForCodeChange(personModule), "precondition: the flush recorded the module");
+		loaderService.resetState();
+		assert.false(loaderService.wasModuleFlushedForCodeChange(personModule), "the record is dropped when the loader crosses a session boundary");
+	});
+	(0, import_qunit.test)("an open editor flushing the loader first does not suppress the rebuild", async function(assert) {
+		let hassan = `${testRealmURL}Person/hassan`;
+		await renderCard(hassan);
+		let personModule = `${testRealmURL}person.gts`;
+		assert.true(loaderService.loader.isModuleLoaded(personModule), "precondition: the person module is loaded");
+		let telemetry = captureTelemetry();
+		try {
+			loaderService.resetLoader({
+				clearFetchCache: true,
+				reason: "file-resource-external-invalidation",
+				codeChange: true
+			});
+			assert.false(loaderService.loader.isModuleLoaded(personModule), "precondition: the flushed loader reports the module as not loaded");
+			storeService.handleInvalidations({
+				eventName: "index",
+				indexType: "incremental",
+				realmURL: testRealmURL,
+				invalidations: [personModule]
+			});
+			await telemetry.waitForEvent("rebuild");
+			await settled();
+		} finally {
+			telemetry.restore();
+		}
+		assert.strictEqual(telemetry.events("rebuild").length, 1, `the rebuild survives a flush by the other subscriber (captured: ${telemetry.summary()})`);
+		await waitFor(`[data-test-rendered-card="${hassan}"]`, { timeout: 5e3 });
+		assert.true(isCardInstance(storeService.peek(hassan)), "the card is re-established after the rebuild");
+	});
+});
+//#endregion

package/bundled-test-harness/assets/store-search-test-nUeJ5opb.js

@@ -0,0 +1,175 @@
+import { s as __toESM } from "./chunk-Rp0pCe6z.js";
+import { r as initializeDeferredDecorator, t as decorateFieldV2 } from "./runtime--fcdnjmJ-BoCBNIsz.js";
+import { $o as isFileMetaResource, Ar as testRealmURL, Dr as testRRI, Po as isCardInstance, Xo as isCardResource } from "./runtime-common-ClpqhbwG.js";
+import { T as baseFileRef, k as baseRef } from "./constants-CqKWhRfY.js";
+import { t as fileTreeFromIndex } from "./file-tree-from-index-BtOOMqnb.js";
+import { M as waitUntil } from "./dist-BOAdzfkP.js";
+import { t as require_qunit } from "./qunit-C-Foo4Nd.js";
+import { F as setupLocalIndexing, M as setupCardLogs, P as setupIntegrationTestRealm, lt as setupRenderingTest, t as setupMockMatrix } from "./mock-matrix-DPQ0j2MD.js";
+import { r as getService } from "./dist-CPfIHBla.js";
+import { A as field, a as CardDef, w as contains } from "./card-api-Dzje0smT.js";
+import { t as string_default } from "./string-BHZZwNlZ.js";
+//#region tests/integration/store-search-test.gts
+var import_qunit = /* @__PURE__ */ __toESM(require_qunit());
+(0, import_qunit.module)("Integration | store search public API", function(hooks) {
+	setupRenderingTest(hooks);
+	let loader;
+	let realm;
+	let storeService;
+	setupLocalIndexing(hooks);
+	setupCardLogs(hooks, async () => await loader.import("@cardstack/base/card-api"));
+	let mockMatrixUtils = setupMockMatrix(hooks, {
+		loggedInAs: "@testuser:localhost",
+		activeRealms: [testRealmURL],
+		autostart: true
+	});
+	let bookRef = {
+		module: testRRI("book"),
+		name: "Book"
+	};
+	hooks.beforeEach(async function() {
+		loader = getService("loader-service").loader;
+		storeService = getService("store");
+		class Book extends CardDef {
+			static displayName = "Book";
+			static {
+				decorateFieldV2(this.prototype, "title", [field], function() {
+					return contains(string_default);
+				});
+			}
+			#title = (initializeDeferredDecorator(this, "title"), void 0);
+			static {
+				decorateFieldV2(this.prototype, "status", [field], function() {
+					return contains(string_default);
+				});
+			}
+			#status = (initializeDeferredDecorator(this, "status"), void 0);
+		}
+		({realm} = await setupIntegrationTestRealm({
+			mockMatrixUtils,
+			contents: {
+				"book.gts": { Book },
+				"books/1.json": new Book({
+					title: "Mango",
+					status: "ready"
+				}),
+				"books/2.json": new Book({
+					title: "Van Gogh",
+					status: "draft"
+				}),
+				"files/hello.txt": "Hello world",
+				"files/notes/today.txt": "Some notes"
+			}
+		}));
+	});
+	(0, import_qunit.test)("search returns instances only and hydrates them into the store", async function(assert) {
+		let instances = await storeService.search({ filter: { type: bookRef } }, [testRealmURL]);
+		assert.strictEqual(instances.length, 2, "both books are returned");
+		for (let instance of instances) {
+			assert.true(isCardInstance(instance), "the result is a card instance");
+			assert.strictEqual(storeService.peek(instance.id), instance, "the instance is resident in the store");
+		}
+		assert.deepEqual(instances.map((instance) => instance.title).sort(), ["Mango", "Van Gogh"]);
+	});
+	(0, import_qunit.test)("search with a BaseDef type filter stays pinned to card instances", async function(assert) {
+		let instances = await storeService.search({ filter: { type: baseRef } }, [testRealmURL]);
+		assert.true(instances.every((instance) => isCardInstance(instance)), "every result is a card instance — no plain files, no dual-indexed `.json` file rows");
+		assert.deepEqual(instances.map((instance) => instance.title).sort(), ["Mango", "Van Gogh"]);
+	});
+	(0, import_qunit.test)("search with includeMeta returns the single { instances, meta } shape", async function(assert) {
+		let result = await storeService.searchWithMeta({ filter: { type: bookRef } }, [testRealmURL]);
+		assert.deepEqual(Object.keys(result).sort(), ["instances", "meta"]);
+		assert.strictEqual(result.meta.page.total, 2);
+		assert.true(result.instances.every((instance) => isCardInstance(instance)), "every result is a card instance");
+	});
+	(0, import_qunit.test)("search and searchEntries find the realm a registered prefix names", async function(assert) {
+		let { virtualNetwork } = getService("network");
+		virtualNetwork.addRealmMapping("@test/mapped/", testRealmURL);
+		try {
+			let { meta } = await storeService.searchWithMeta({}, ["@test/mapped/"]);
+			assert.strictEqual(meta.page.total, 2, "search finds the books");
+			let doc = await storeService.searchEntries({
+				scope: "cards",
+				fields: { entry: ["item"] }
+			}, ["@test/mapped/"]);
+			assert.deepEqual(doc.data.map((entry) => entry.id).sort(), [`${testRealmURL}books/1`, `${testRealmURL}books/2`], "searchEntries finds the books");
+		} finally {
+			virtualNetwork.removeRealmMapping("@test/mapped/");
+		}
+	});
+	(0, import_qunit.test)("search rejects the removed asData path", async function(assert) {
+		await assert.rejects(storeService.search({
+			filter: { type: bookRef },
+			asData: true
+		}, [testRealmURL]), /instances only.*searchEntries/);
+	});
+	(0, import_qunit.test)("searchEntries returns the raw entry wire format without hydrating", async function(assert) {
+		let doc = await storeService.searchEntries({
+			filter: { "item.on": bookRef },
+			fields: { entry: ["item"] }
+		}, [testRealmURL]);
+		assert.strictEqual(doc.data.length, 2, "both books are returned");
+		for (let entry of doc.data) {
+			assert.strictEqual(entry.type, "entry");
+			assert.strictEqual(entry.relationships.item?.data.type, "card", "the entry links its item serialization");
+			assert.strictEqual(entry.relationships.item?.data.id, entry.id, "the entry and its item share the bare card URL");
+			assert.strictEqual(storeService.peek(entry.id), void 0, "searchEntries deposits nothing in the store");
+		}
+		let items = (doc.included ?? []).filter((resource) => isCardResource(resource));
+		assert.strictEqual(items.length, 2, "the full items ride in included");
+		assert.deepEqual(items.map((item) => item.attributes?.title).sort(), ["Mango", "Van Gogh"], "the items are full serializations");
+		assert.true(items.every((item) => !("sparseFields" in item.meta)), "a full item carries no sparseFields marker");
+	});
+	(0, import_qunit.test)("searchEntries returns field-limited items per the sparse fieldset", async function(assert) {
+		let items = ((await storeService.searchEntries({
+			filter: { "item.on": bookRef },
+			fields: { entry: ["item.title"] }
+		}, [testRealmURL])).included ?? []).filter((resource) => isCardResource(resource));
+		assert.strictEqual(items.length, 2);
+		for (let item of items) {
+			assert.deepEqual(item.meta.sparseFields, ["title"], "the sparse marker records the requested fields");
+			assert.deepEqual(Object.keys(item.attributes ?? {}), ["title"], "only the requested attributes ride along");
+		}
+	});
+	(0, import_qunit.test)("searchEntries returns file-meta items for a file query", async function(assert) {
+		let doc = await storeService.searchEntries({
+			filter: { "item.on": baseFileRef },
+			fields: { entry: ["item"] }
+		}, [testRealmURL]);
+		let fileURLs = doc.data.map((entry) => entry.id);
+		assert.true(fileURLs.includes(`${testRealmURL}files/hello.txt`), "the file entry id is its canonical URL");
+		assert.true((doc.included ?? []).some((resource) => isFileMetaResource(resource)), "file-meta items ride in included");
+	});
+	(0, import_qunit.test)("a file is matchable by eq on its id (the unified card/file identity key)", async function(assert) {
+		let fileURL = `${testRealmURL}files/hello.txt`;
+		let doc = await storeService.searchEntries({
+			filter: {
+				"item.on": baseFileRef,
+				eq: { "item.id": fileURL }
+			},
+			fields: { entry: ["item"] }
+		}, [testRealmURL]);
+		assert.deepEqual(doc.data.map((entry) => entry.id), [fileURL], "exactly the file with that id is returned");
+	});
+	(0, import_qunit.test)("the file tree consumer works via searchEntries", async function(assert) {
+		let fileTree = fileTreeFromIndex(storeService, () => testRealmURL);
+		fileTree.entries;
+		await waitUntil(() => !fileTree.isLoading && fileTree.entries.length > 0);
+		let files = fileTree.entries.find((entry) => entry.name === "files");
+		assert.strictEqual(files?.kind, "directory");
+		let names = [...files?.children?.keys() ?? []];
+		assert.deepEqual(names.sort(), ["hello.txt", "notes"]);
+		assert.strictEqual(files?.children?.get("notes")?.children?.get("today.txt")?.kind, "file");
+	});
+	(0, import_qunit.test)("the file tree updates live on an incremental index event", async function(assert) {
+		let fileTree = fileTreeFromIndex(storeService, () => testRealmURL);
+		fileTree.entries;
+		await waitUntil(() => !fileTree.isLoading && fileTree.entries.length > 0);
+		await realm.write("files/added-later.txt", "fresh");
+		await waitUntil(() => {
+			return fileTree.entries.find((entry) => entry.name === "files")?.children?.has("added-later.txt");
+		});
+		assert.true(fileTree.entries.find((entry) => entry.name === "files")?.children?.has("added-later.txt"), "the new file appears after the incremental index event");
+	});
+});
+//#endregion