@danypops/pi-packed 0.19.7 → 0.19.10

package/service/test/domain.test.ts

@@ -0,0 +1,291 @@
+import { describe, expect, it } from "bun:test";
+import { mkdirSync, mkdtempSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { AuthenticatedRpcClient } from "@danypops/vehicle-client/rpc-client";
+import { createApp, type OperationInputs, type OperationName, type OperationOutputs } from "../src/daemon/service.ts";
+import { checkUpdates, loadUpdates, saveUpdates, startWatcher } from "../src/daemon/watcher.ts";
+import { catalogStatus } from "../src/packages/catalog.ts";
+import { dbPath, openDb, replaceAll } from "../src/packages/db.ts";
+import {
+	isPinnedNpmSource,
+	npmPackageName,
+	readInstalledPackages,
+	readInstalledPackagesAcrossScopes,
+	readResolvedVersion,
+	splitNpmSource,
+} from "../src/packages/installed.ts";
+import type { Installer, PkgInfo, Registry, SearchPage, UpdateOutcome, UpdatesSnapshot } from "../src/packages/package.ts";
+
+function writePiHome(settings: unknown, nodeModules: Record<string, string> = {}): string {
+	const dir = mkdtempSync(join(tmpdir(), "packed-pihome-"));
+	writeFileSync(join(dir, "settings.json"), JSON.stringify(settings));
+	for (const [name, version] of Object.entries(nodeModules)) {
+		const pkgDir = join(dir, "npm", "node_modules", name);
+		mkdirSync(pkgDir, { recursive: true });
+		writeFileSync(join(pkgDir, "package.json"), JSON.stringify({ version }));
+	}
+	return dir;
+}
+
+describe("splitNpmSource", () => {
+	it("splits on last non-scope @", () => {
+		expect(splitNpmSource("foo@1.2.3")).toEqual(["foo", "1.2.3"]);
+		expect(splitNpmSource("@scope/pkg@1.0.0")).toEqual(["@scope/pkg", "1.0.0"]);
+		expect(splitNpmSource("foo")).toEqual(["foo", ""]);
+		expect(splitNpmSource("@scope/pkg")).toEqual(["@scope/pkg", ""]);
+	});
+});
+
+describe("isPinnedNpmSource", () => {
+	it("true only for an npm: source with an exact version suffix", () => {
+		expect(isPinnedNpmSource("npm:foo@1.2.3")).toBe(true);
+		expect(isPinnedNpmSource("npm:@scope/pkg@1.2.3")).toBe(true);
+		expect(isPinnedNpmSource("npm:foo")).toBe(false);
+		expect(isPinnedNpmSource("npm:@scope/pkg")).toBe(false);
+		expect(isPinnedNpmSource("git:github.com/u/r@main")).toBe(false);
+		expect(isPinnedNpmSource("https://example.com/pkg.tgz")).toBe(false);
+	});
+});
+
+describe("npmPackageName", () => {
+	it("extracts the bare name for npm: sources, pinned or not", () => {
+		expect(npmPackageName("npm:foo@1.2.3")).toBe("foo");
+		expect(npmPackageName("npm:@scope/pkg@1.2.3")).toBe("@scope/pkg");
+		expect(npmPackageName("npm:@scope/pkg")).toBe("@scope/pkg");
+	});
+
+	it("undefined for non-npm sources", () => {
+		expect(npmPackageName("git:github.com/u/r@main")).toBeUndefined();
+		expect(npmPackageName("https://example.com/pkg.tgz")).toBeUndefined();
+	});
+});
+
+describe("readResolvedVersion", () => {
+	it("reads the real on-disk version regardless of pinning", () => {
+		const home = writePiHome({ packages: [] }, { "@scope/pkg": "3.4.5", plain: "1.0.0" });
+		expect(readResolvedVersion(home, "npm:@scope/pkg@9.9.9")).toBe("3.4.5");
+		expect(readResolvedVersion(home, "npm:@scope/pkg")).toBe("3.4.5");
+		expect(readResolvedVersion(home, "npm:plain")).toBe("1.0.0");
+	});
+
+	it("undefined for a non-npm source or a package missing from node_modules", () => {
+		const home = writePiHome({ packages: [] });
+		expect(readResolvedVersion(home, "git:github.com/u/r@main")).toBeUndefined();
+		expect(readResolvedVersion(home, "npm:never-installed")).toBeUndefined();
+	});
+});
+
+describe("readInstalledPackages", () => {
+	it("parses string and object forms, resolves unpinned from node_modules", () => {
+		const home = writePiHome(
+			{
+				packages: [
+					"npm:pi-extension-manager@0.8.2",
+					"npm:@scope/pinned@1.0.0",
+					"npm:unpinned",
+					"git:github.com/u/r",
+					{ source: "npm:obj-form@2.0.0" },
+				],
+			},
+			{ unpinned: "0.5.0" },
+		);
+		expect(readInstalledPackages(home)).toEqual([
+			{ name: "pi-extension-manager", pinned: "0.8.2", installed: undefined },
+			{ name: "@scope/pinned", pinned: "1.0.0", installed: undefined },
+			{ name: "unpinned", pinned: undefined, installed: "0.5.0" },
+			{ name: "obj-form", pinned: "2.0.0", installed: undefined },
+		]);
+	});
+
+	it("missing settings → empty", () => {
+		expect(readInstalledPackages(mkdtempSync(join(tmpdir(), "packed-")))).toEqual([]);
+	});
+});
+
+describe("readInstalledPackagesAcrossScopes", () => {
+	it("tags every entry with its scope and is global-only without a projectRoot", () => {
+		const home = writePiHome({ packages: ["npm:pi-global@1.0.0"] });
+		expect(readInstalledPackagesAcrossScopes(home)).toEqual([
+			{ name: "pi-global", pinned: "1.0.0", installed: undefined, scope: "global" },
+		]);
+	});
+
+	it("reproduces the real jittor gap: a stale project-scoped pin is invisible to a global-only read, visible once project scope is included", () => {
+		const home = writePiHome({ packages: ["npm:pi-global@1.0.0"] });
+		const projectRoot = mkdtempSync(join(tmpdir(), "packed-project-"));
+		const projectHome = join(projectRoot, ".pi");
+		mkdirSync(projectHome, { recursive: true });
+		writeFileSync(join(projectHome, "settings.json"), JSON.stringify({ packages: ["npm:papyrus@0.21.2"] }));
+
+		expect(readInstalledPackages(home).map((pkg) => pkg.name)).not.toContain("papyrus");
+		const merged = readInstalledPackagesAcrossScopes(home, projectRoot);
+		expect(merged).toEqual([
+			{ name: "pi-global", pinned: "1.0.0", installed: undefined, scope: "global" },
+			{ name: "papyrus", pinned: "0.21.2", installed: undefined, scope: "project" },
+		]);
+	});
+
+	it("is unaffected by a missing project settings file", () => {
+		const home = writePiHome({ packages: ["npm:pi-global@1.0.0"] });
+		const projectRoot = mkdtempSync(join(tmpdir(), "packed-project-"));
+		expect(readInstalledPackagesAcrossScopes(home, projectRoot)).toEqual([
+			{ name: "pi-global", pinned: "1.0.0", installed: undefined, scope: "global" },
+		]);
+	});
+});
+
+describe("checkUpdates (mirror-based)", () => {
+	it("flags drift only", () => {
+		const latest = (name: string) => ({ "pi-extension-manager": "0.9.0", "pi-lsp": "1.0.0" })[name];
+		const updates = checkUpdates(latest, [
+			{ name: "pi-extension-manager", pinned: "0.8.2" },
+			{ name: "pi-lsp", installed: "1.0.0" },
+		]);
+		expect(updates).toHaveLength(1);
+		expect(updates[0]).toMatchObject({ name: "pi-extension-manager", installed: "0.8.2", latest: "0.9.0" });
+	});
+
+	it("packages missing from the mirror are skipped", () => {
+		const updates = checkUpdates(() => undefined, [{ name: "gone", pinned: "1.0.0" }]);
+		expect(updates).toEqual([]);
+	});
+
+	it("carries scope through so a project-scoped drift entry is distinguishable from a global one", () => {
+		const latest = (name: string) => ({ papyrus: "0.38.1" })[name];
+		const updates = checkUpdates(latest, [{ name: "papyrus", pinned: "0.21.2", scope: "project" }]);
+		expect(updates).toEqual([
+			{ name: "papyrus", installed: "0.21.2", latest: "0.38.1", detectedAt: updates[0]!.detectedAt, scope: "project" },
+		]);
+	});
+
+	// Real, screenshot-confirmed bug: the mirror's own "latest" can lag
+	// behind what's actually installed (a stale sync, or the installed
+	// package genuinely jumped ahead). A plain !== check can't tell that
+	// apart from real drift and flags a permanent, un-clearable "update"
+	// pointing at an OLDER version than what's already installed.
+	it("never flags a package whose installed version is already ahead of the mirrored latest", () => {
+		const latest = (name: string) => ({ "pi-papyrus": "0.38.4" })[name];
+		const updates = checkUpdates(latest, [{ name: "pi-papyrus", installed: "0.41.0" }]);
+		expect(updates).toEqual([]);
+	});
+
+	it("still flags a genuine downgrade-to-latest scenario correctly using real semver ordering, not string equality", () => {
+		// 0.9.0 vs 0.10.0 -- string comparison would call these "different"
+		// either way, but semver must recognize 0.10.0 as newer, not just "not equal".
+		const latest = (name: string) => ({ "pi-lsp": "0.10.0" })[name];
+		const updates = checkUpdates(latest, [{ name: "pi-lsp", installed: "0.9.0" }]);
+		expect(updates).toEqual([{ name: "pi-lsp", installed: "0.9.0", latest: "0.10.0", detectedAt: updates[0]!.detectedAt }]);
+	});
+
+	it("falls back to inequality for non-semver values (a git ref or a literal dist-tag) since they aren't comparable at all", () => {
+		const latest = (name: string) => ({ "pi-git-pkg": "latest" })[name];
+		const updates = checkUpdates(latest, [{ name: "pi-git-pkg", installed: "latest" }]);
+		expect(updates).toEqual([]); // same non-semver string -- not different, not flagged
+	});
+});
+
+class NoopRegistry implements Registry {
+	async search(): Promise<SearchPage> {
+		return { results: [], total: 0 };
+	}
+	async searchPage(): Promise<SearchPage> {
+		return { results: [], total: 0 };
+	}
+	async searchAll() {
+		return [];
+	}
+	async info(name: string): Promise<PkgInfo> {
+		return { name, version: "1.0.0" };
+	}
+}
+
+class NoopInstaller implements Installer {
+	async install() {
+		return "ok";
+	}
+	async remove() {
+		return "ok";
+	}
+	async update(): Promise<UpdateOutcome> {
+		return { output: "ok", reloadRequired: false, alreadyUpToDate: true, pinned: false };
+	}
+}
+
+describe("package.updates.project (daemon RPC wiring)", () => {
+	it("computes a live, cross-scope drift check on demand, distinct from package.updates' own persisted global-only snapshot", async () => {
+		const home = mkdtempSync(join(tmpdir(), "packed-updates-project-"));
+		writeFileSync(join(home, "settings.json"), JSON.stringify({ packages: ["npm:pi-global@1.0.0"] }));
+		const projectRoot = mkdtempSync(join(tmpdir(), "packed-updates-project-root-"));
+		const projectHome = join(projectRoot, ".pi");
+		mkdirSync(projectHome, { recursive: true });
+		writeFileSync(join(projectHome, "settings.json"), JSON.stringify({ packages: ["npm:papyrus@0.21.2"] }));
+		const stateDir = mkdtempSync(join(tmpdir(), "packed-updates-project-state-"));
+		const db = openDb(dbPath(stateDir));
+		replaceAll(
+			db,
+			[
+				{ name: "pi-global", version: "1.0.0" },
+				{ name: "papyrus", version: "0.38.1" },
+			],
+			"test",
+		);
+		db.close();
+		const app = createApp({ reg: new NoopRegistry(), inst: new NoopInstaller(), token: "test-token", stateDir, piHome: home });
+		const client = new AuthenticatedRpcClient<OperationName, OperationInputs, OperationOutputs>("http://packed.test", "test-token", {
+			label: "Packed",
+			transport: (request) => app.fetch(request),
+		});
+
+		const globalSnapshot = await client.call("package.updates", {});
+		expect(globalSnapshot.updates).toEqual([]);
+
+		const result = await client.call("package.updates.project", { projectRoot });
+		expect(result.updates).toEqual([
+			{ name: "papyrus", installed: "0.21.2", latest: "0.38.1", detectedAt: result.updates[0]!.detectedAt, scope: "project" },
+		]);
+	});
+});
+
+describe("updates store", () => {
+	it("roundtrips", async () => {
+		const dir = mkdtempSync(join(tmpdir(), "packed-"));
+		const snap = { checkedAt: new Date().toISOString(), updates: [{ name: "a", installed: "1", latest: "2", detectedAt: "" }] };
+		await saveUpdates(dir, snap);
+		expect(await loadUpdates(dir)).toEqual(snap);
+		expect(await loadUpdates(join(dir, "nope"))).toBeUndefined();
+	});
+});
+
+describe("watcher producer", () => {
+	it("writes a snapshot on tick", async () => {
+		const dir = mkdtempSync(join(tmpdir(), "packed-"));
+		const stop = startWatcher(
+			() => "0.9.0",
+			dir,
+			() => [{ name: "pi-extension-manager", pinned: "0.8.2" }],
+			{ intervalMs: 60_000 },
+		);
+		const deadline = Date.now() + 2000;
+		let snap: UpdatesSnapshot | undefined;
+		while (Date.now() < deadline) {
+			snap = await loadUpdates(dir);
+			if (snap?.updates.length) break;
+			await Bun.sleep(25);
+		}
+		stop();
+		expect(snap?.updates[0]?.latest).toBe("0.9.0");
+	});
+});
+
+describe("catalog status", () => {
+	it("stale when unsynced, fresh after sync", () => {
+		const dir = mkdtempSync(join(tmpdir(), "packed-"));
+		expect(catalogStatus(dir, 6 * 3_600_000).stale).toBe(true);
+		const db = openDb(`${dir}/packed.db`);
+		replaceAll(db, [{ name: "a", version: "1" }], "test");
+		db.close();
+		expect(catalogStatus(dir, 6 * 3_600_000).stale).toBe(false);
+		expect(catalogStatus(dir, -1).stale).toBe(true);
+	});
+});

package/service/test/fixtures/install-validation/broken-package/extension/index.ts

@@ -0,0 +1,3 @@
+export default function brokenFixtureExtension(_pi: unknown) {
+	throw new Error("brokenFixtureExtension deliberately fails during registration");
+}

package/service/test/fixtures/install-validation/broken-package/package.json

@@ -0,0 +1,8 @@
+{
+	"name": "packed-install-validation-fixture-broken",
+	"version": "1.0.0",
+	"private": true,
+	"pi": {
+		"extensions": ["extension/index.ts"]
+	}
+}

package/service/test/fixtures/install-validation/healthy-package/extension/index.ts

@@ -0,0 +1,3 @@
+export default function healthyFixtureExtension(pi: { registerCommand: (name: string, def: unknown) => void }) {
+	pi.registerCommand("healthy-fixture", { description: "registers cleanly", handler: async () => {} });
+}

package/service/test/fixtures/install-validation/healthy-package/package.json

@@ -0,0 +1,8 @@
+{
+	"name": "packed-install-validation-fixture-healthy",
+	"version": "1.0.0",
+	"private": true,
+	"pi": {
+		"extensions": ["extension/index.ts"]
+	}
+}

package/service/test/fixtures/install-validation/no-manifest-package/package.json

@@ -0,0 +1,5 @@
+{
+	"name": "packed-install-validation-fixture-no-manifest",
+	"version": "1.0.0",
+	"private": true
+}

package/service/test/index.test.ts

@@ -0,0 +1,353 @@
+import { afterAll, beforeAll, describe, expect, it } from "bun:test";
+import { mkdtempSync, readFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import type { Server } from "bun";
+import { buildIndex, generateIndex, indexPath, indexStatus, readIndex, writeIndex } from "../src/index/build-index.ts";
+import { dbPath, openDb, replaceAll } from "../src/packages/db.ts";
+import { HttpRegistry } from "../src/registry/registry.ts";
+
+// Guards the "never bulk GitHub calls" constraint against regression: a
+// future edit could easily start threading a GitHub-commit fetcher through
+// buildIndex the same way scoreTarget does. A source-level check catches
+// that before it ships, independent of whatever fixture happens to be
+// running in the behavioral tests below.
+describe("index/build-index.ts never touches GitHub", () => {
+	it("does not import commit-freshness.ts's GitHub-facing exports", () => {
+		const source = readFileSync(new URL("../src/index/build-index.ts", import.meta.url), "utf8");
+		// Matches a real import specifier or a real call, not prose mentioning
+		// the file/function names in a comment (this file's own doc comment
+		// legitimately explains *why* it avoids commit-freshness.ts).
+		expect(source).not.toMatch(/from\s+["'][^"']*commit-freshness(?:\.ts)?["']|\b(?:githubLastCommitAt|createGithubLastCommitAt)\s*\(/);
+	});
+});
+
+// Real HTTP adapter against a fake npm upstream (Bun.serve) -- same pattern
+// core.test.ts's HttpRegistry suite uses. No mocked fetch, no fake
+// registry class: buildIndex runs against the real HttpRegistry.
+describe("buildIndex", () => {
+	let server: Server<undefined>;
+	let registry: HttpRegistry;
+	let catalogDir: string;
+	let fetchedUrls: string[];
+
+	beforeAll(() => {
+		catalogDir = mkdtempSync(join(tmpdir(), "packed-index-catalog-"));
+		const db = openDb(dbPath(catalogDir));
+		replaceAll(
+			db,
+			[
+				{ name: "pi-alpha", version: "1.0.0" },
+				{ name: "pi-beta", version: "2.0.0" },
+				{ name: "pi-missing", version: "0.0.1" }, // 404s -- must be skipped, not fatal
+			],
+			"npm:keywords:pi-package",
+		);
+		db.close();
+
+		const infoDocs: Record<string, unknown> = {
+			"pi-alpha": {
+				name: "pi-alpha",
+				version: "1.0.0",
+				description: "alpha package for pi",
+				license: "MIT",
+				repository: { type: "git", url: "git+https://github.com/x/pi-alpha.git" },
+				keywords: ["pi-package"],
+				pi: { extensions: ["./src/index.ts"] },
+				dist: { integrity: "sha512-a" },
+			},
+			"pi-beta": {
+				name: "pi-beta",
+				version: "2.0.0",
+				description: "beta package for pi",
+				license: "MIT",
+				keywords: ["pi-package"],
+			},
+		};
+		const modifiedDocs: Record<string, string> = {
+			"pi-alpha": "2026-01-01T00:00:00.000Z",
+			"pi-beta": "2026-02-01T00:00:00.000Z",
+			"@earendil-works/pi-coding-agent": "2026-03-01T00:00:00.000Z",
+		};
+
+		server = Bun.serve({
+			port: 0,
+			fetch(req) {
+				const url = new URL(req.url);
+				const name = decodeURIComponent(url.pathname.replace(/^\//, "").replace(/\/latest$/, ""));
+				if (url.pathname.endsWith("/latest")) {
+					const doc = infoDocs[name];
+					return doc ? Response.json(doc) : new Response("not found", { status: 404 });
+				}
+				if (url.pathname.startsWith("/downloads/point/")) {
+					return Response.json({ downloads: 5 });
+				}
+				const modified = modifiedDocs[name];
+				return modified ? Response.json({ modified }) : new Response("not found", { status: 404 });
+			},
+		});
+		registry = new HttpRegistry(`http://127.0.0.1:${server.port}`, 250, 0, 1, `http://127.0.0.1:${server.port}`);
+	});
+
+	afterAll(() => server.stop(true));
+
+	it("builds one entry per cataloged package, skipping a lookup failure rather than failing the whole run", async () => {
+		const index = await buildIndex(registry, catalogDir, { delayMs: 0, currentPiVersion: async () => "0.83.0" });
+		expect(index.packages.map((p) => p.name).sort()).toEqual(["pi-alpha", "pi-beta"]); // pi-missing skipped
+		expect(typeof index.generatedAt).toBe("string");
+		const alpha = index.packages.find((p) => p.name === "pi-alpha")!;
+		expect(alpha.dimensions.trust.status).not.toBe("unknown");
+		expect(alpha.dimensions.discoverability.evidence).toContain("pi-package keyword");
+	});
+
+	it("never calls GitHub, even for a candidate declaring a github.com repository -- freshness always falls back to the npm publish-date proxy", async () => {
+		const realFetch = globalThis.fetch;
+		fetchedUrls = [];
+		globalThis.fetch = ((input: RequestInfo | URL, init?: RequestInit) => {
+			fetchedUrls.push(typeof input === "string" ? input : input instanceof URL ? input.href : input.url);
+			return realFetch(input, init);
+		}) as typeof fetch;
+		try {
+			const index = await buildIndex(registry, catalogDir, { delayMs: 0, currentPiVersion: async () => "0.83.0" });
+			expect(fetchedUrls.some((u) => u.includes("github"))).toBe(false);
+			const alpha = index.packages.find((p) => p.name === "pi-alpha")!;
+			// pi-alpha declares a real github.com repository, yet freshness must
+			// still be sourced from the npm publish-date proxy, never a commit.
+			expect(alpha.dimensions.freshness.evidence.some((e) => e.includes("npm publish date"))).toBe(true);
+			expect(alpha.dimensions.freshness.evidence.some((e) => e.includes("last real commit"))).toBe(false);
+		} finally {
+			globalThis.fetch = realFetch;
+		}
+	});
+});
+
+describe("buildIndex bounds", () => {
+	it("never calls downloads() -- confirmed live to trigger npm's 429s at real catalog scale -- and truncates past maxPackages, marking the result", async () => {
+		const dir = mkdtempSync(join(tmpdir(), "packed-index-bounds-"));
+		const db = openDb(dbPath(dir));
+		replaceAll(
+			db,
+			[
+				{ name: "pi-one", version: "1.0.0" },
+				{ name: "pi-two", version: "1.0.0" },
+				{ name: "pi-three", version: "1.0.0" },
+			],
+			"test",
+		);
+		db.close();
+		let downloadsCalled = false;
+		const server = Bun.serve({
+			port: 0,
+			fetch(req) {
+				const url = new URL(req.url);
+				if (url.pathname.startsWith("/downloads/")) {
+					downloadsCalled = true;
+					return Response.json({ downloads: 1 });
+				}
+				if (url.pathname.endsWith("/latest")) return Response.json({ name: url.pathname.split("/")[1], version: "1.0.0" });
+				return new Response("not found", { status: 404 });
+			},
+		});
+		try {
+			const reg = new HttpRegistry(`http://127.0.0.1:${server.port}`, 250, 0, 1, `http://127.0.0.1:${server.port}`);
+			const index = await buildIndex(reg, dir, { delayMs: 0, maxPackages: 2 });
+			expect(index.packages).toHaveLength(2); // 3 cataloged, bounded to 2
+			expect(index.truncated).toBe(true);
+			expect(downloadsCalled).toBe(false);
+		} finally {
+			server.stop(true);
+		}
+	});
+
+	it("collapses two concurrent callers into one run -- confirmed live to matter: the daemon's own maintenance tick and an on-demand CLI build overlapping compounded into a shutdown the daemon's SIGTERM grace period couldn't outlast", async () => {
+		const dir = mkdtempSync(join(tmpdir(), "packed-index-concurrent-"));
+		const db = openDb(dbPath(dir));
+		replaceAll(db, [{ name: "pi-one", version: "1.0.0" }], "test");
+		db.close();
+		let infoCalls = 0;
+		const server = Bun.serve({
+			port: 0,
+			async fetch(req) {
+				const url = new URL(req.url);
+				if (url.pathname.endsWith("/latest")) {
+					infoCalls++;
+					await Bun.sleep(30);
+					return Response.json({ name: "pi-one", version: "1.0.0" });
+				}
+				return new Response("not found", { status: 404 });
+			},
+		});
+		try {
+			const reg = new HttpRegistry(`http://127.0.0.1:${server.port}`, 250, 0, 1, `http://127.0.0.1:${server.port}`);
+			const [a, b] = await Promise.all([buildIndex(reg, dir, { delayMs: 0 }), buildIndex(reg, dir, { delayMs: 0 })]);
+			expect(a).toBe(b); // the very same result object -- one real run, not two
+			expect(infoCalls).toBe(1); // never doubled
+		} finally {
+			server.stop(true);
+		}
+	});
+});
+
+describe("buildIndex incremental delta scanning", () => {
+	it("partitions the catalog into New/Changed/Unchanged against the prior index -- Unchanged makes zero live registry calls, New and Changed do", async () => {
+		const dir = mkdtempSync(join(tmpdir(), "packed-index-delta-"));
+		const db = openDb(dbPath(dir));
+		replaceAll(
+			db,
+			[
+				{ name: "pi-new", version: "1.0.0", date: "2026-03-01T00:00:00.000Z" }, // absent from prior index
+				{ name: "pi-changed", version: "2.0.0", date: "2026-04-01T00:00:00.000Z" }, // date advanced since last scan
+				{ name: "pi-unchanged", version: "1.5.0", date: "2026-01-01T00:00:00.000Z" }, // date identical to last scan
+			],
+			"test",
+		);
+		db.close();
+
+		const priorIndex = {
+			generatedAt: "2026-02-01T00:00:00.000Z",
+			packages: [
+				{
+					name: "pi-changed",
+					version: "1.9.0",
+					date: "2026-01-01T00:00:00.000Z",
+					dimensions: { discoverability: { status: "ready" as const, met: 1, total: 1, evidence: ["stale"], actions: [] } } as never,
+				},
+				{
+					name: "pi-unchanged",
+					version: "1.5.0",
+					date: "2026-01-01T00:00:00.000Z",
+					dimensions: {
+						discoverability: { status: "ready" as const, met: 1, total: 1, evidence: ["carried forward"], actions: [] },
+					} as never,
+				},
+			],
+			truncated: false,
+		};
+		await writeIndex(indexPath(dir), priorIndex);
+
+		const calledInfo: string[] = [];
+		const server = Bun.serve({
+			port: 0,
+			fetch(req) {
+				const url = new URL(req.url);
+				if (url.pathname.endsWith("/latest")) {
+					const name = decodeURIComponent(url.pathname.replace(/^\//, "").replace(/\/latest$/, ""));
+					calledInfo.push(name);
+					return Response.json({ name, version: name === "pi-changed" ? "2.0.0" : "1.0.0", description: "real fixture" });
+				}
+				return new Response("not found", { status: 404 });
+			},
+		});
+		try {
+			const reg = new HttpRegistry(`http://127.0.0.1:${server.port}`, 250, 0, 1, `http://127.0.0.1:${server.port}`);
+			const index = await buildIndex(reg, dir, { delayMs: 0 });
+
+			// Unchanged never triggered a live info() call, and its prior
+			// dimensions/date are preserved verbatim.
+			expect(calledInfo.sort()).toEqual(["pi-changed", "pi-new"]);
+			const unchanged = index.packages.find((p) => p.name === "pi-unchanged")!;
+			expect(unchanged.dimensions.discoverability.evidence).toEqual(["carried forward"]);
+			expect(unchanged.date).toBe("2026-01-01T00:00:00.000Z");
+
+			// Changed and New both got a real, fresh score.
+			const changed = index.packages.find((p) => p.name === "pi-changed")!;
+			expect(changed.version).toBe("2.0.0");
+			expect(changed.date).toBe("2026-04-01T00:00:00.000Z");
+			const fresh = index.packages.find((p) => p.name === "pi-new")!;
+			expect(fresh.date).toBe("2026-03-01T00:00:00.000Z");
+			expect(index.packages).toHaveLength(3);
+		} finally {
+			server.stop(true);
+		}
+	});
+
+	it("maxPackages bounds only the New+Changed live-call queue -- Unchanged entries beyond that count still complete", async () => {
+		const dir = mkdtempSync(join(tmpdir(), "packed-index-delta-bound-"));
+		const db = openDb(dbPath(dir));
+		// 5 unchanged entries alone already exceed maxPackages: 1 below.
+		replaceAll(
+			db,
+			[
+				{ name: "pi-a", version: "1.0.0", date: "2026-01-01T00:00:00.000Z" },
+				{ name: "pi-b", version: "1.0.0", date: "2026-01-01T00:00:00.000Z" },
+				{ name: "pi-c", version: "1.0.0", date: "2026-01-01T00:00:00.000Z" },
+				{ name: "pi-d", version: "1.0.0", date: "2026-01-01T00:00:00.000Z" },
+				{ name: "pi-e", version: "1.0.0", date: "2026-01-01T00:00:00.000Z" },
+			],
+			"test",
+		);
+		db.close();
+		const priorIndex = {
+			generatedAt: "2026-01-01T00:00:00.000Z",
+			packages: ["pi-a", "pi-b", "pi-c", "pi-d", "pi-e"].map((name) => ({
+				name,
+				version: "1.0.0",
+				date: "2026-01-01T00:00:00.000Z",
+				dimensions: {} as never,
+			})),
+			truncated: false,
+		};
+		await writeIndex(indexPath(dir), priorIndex);
+		let liveCalls = 0;
+		const server = Bun.serve({
+			port: 0,
+			fetch() {
+				liveCalls++;
+				return new Response("not found", { status: 404 });
+			},
+		});
+		try {
+			const reg = new HttpRegistry(`http://127.0.0.1:${server.port}`, 250, 0, 1, `http://127.0.0.1:${server.port}`);
+			const index = await buildIndex(reg, dir, { delayMs: 0, maxPackages: 1 });
+			expect(index.packages).toHaveLength(5); // all 5 Unchanged carried forward despite maxPackages: 1
+			expect(index.truncated).toBe(false); // nothing needed live scoring, so nothing was truncated
+			expect(liveCalls).toBe(0);
+		} finally {
+			server.stop(true);
+		}
+	});
+});
+
+describe("index persistence", () => {
+	it("writes, reads, and reports staleness", async () => {
+		const dir = mkdtempSync(join(tmpdir(), "packed-index-store-"));
+		const path = indexPath(dir);
+		expect(readIndex(path)).toBeUndefined();
+		expect(indexStatus(path, 1_000).stale).toBe(true);
+
+		const index = {
+			generatedAt: new Date().toISOString(),
+			packages: [{ name: "pi-alpha", version: "1.0.0", dimensions: {} as never }],
+			truncated: false,
+		};
+		await writeIndex(path, index);
+		expect(readIndex(path)).toEqual(index);
+		expect(indexStatus(path, 60_000)).toMatchObject({ stale: false, packageCount: 1 });
+
+		const old = { generatedAt: new Date(Date.now() - 100_000).toISOString(), packages: [], truncated: false };
+		await writeIndex(path, old);
+		expect(indexStatus(path, 1_000).stale).toBe(true);
+	});
+
+	it("generateIndex builds and writes in one call", async () => {
+		const dir = mkdtempSync(join(tmpdir(), "packed-index-generate-"));
+		const db = openDb(dbPath(dir));
+		replaceAll(db, [{ name: "pi-alpha", version: "1.0.0" }], "npm:keywords:pi-package");
+		db.close();
+		const server = Bun.serve({
+			port: 0,
+			fetch(req) {
+				const url = new URL(req.url);
+				if (url.pathname === "/pi-alpha/latest") return Response.json({ name: "pi-alpha", version: "1.0.0" });
+				return new Response("not found", { status: 404 });
+			},
+		});
+		try {
+			const reg = new HttpRegistry(`http://127.0.0.1:${server.port}`, 250, 0, 1, `http://127.0.0.1:${server.port}`);
+			const index = await generateIndex(reg, dir, indexPath(dir), { delayMs: 0 });
+			expect(readIndex(indexPath(dir))).toEqual(index);
+		} finally {
+			server.stop(true);
+		}
+	});
+});