@tsdoctor/registry 0.1.0

package/TsEnvironment.js

@@ -0,0 +1,95 @@
+import { isTypeDefinition } from "./internal/resolution.js";
+import { Effect, Schema } from "effect";
+
+//#region src/TsEnvironment.ts
+/**
+* Raised when building a virtual TypeScript environment fails — including
+* when the optional `typescript` / `@typescript/vfs` /
+* `@effected/tsconfig-json` peers are not installed.
+*
+* @public
+*/
+var TsEnvironmentError = class extends Schema.TaggedError()("TsEnvironmentError", { 
+/** The underlying failure, preserved structurally. */
+cause: Schema.Defect() }) {
+	get message() {
+		return "Failed to create the virtual TypeScript environment";
+	}
+};
+/**
+* The `@typescript/vfs` seam: builds a `VirtualTypeScriptEnvironment` over a
+* {@link Vfs} plus the TypeScript default lib files.
+*
+* @remarks
+* The ONLY module touching the optional `typescript` / `@typescript/vfs` /
+* `@effected/tsconfig-json` peers, and it loads all three lazily inside
+* {@link TsEnvironment.make} — a consumer that never calls it never loads
+* the compiler, and a missing peer fails typed as
+* {@link TsEnvironmentError} instead of crashing at import time. Keep every
+* one of them behind that dynamic `import()`: a static value import here is
+* reachable from `index.ts`, so it would turn an omitted optional peer into
+* an `ERR_MODULE_NOT_FOUND` on the entry graph for consumers who never
+* touch this module. Only the type-only `CompilerOptions` import is safe
+* statically, because it erases. The underlying `createDefaultMapFromNodeModules` /
+* `createFSBackedSystem` read the real filesystem through TypeScript's own
+* `sys`, outside the Effect `FileSystem` service — accepted and documented;
+* this module is why the package is integrated tier on its own surface.
+*
+* No cache map (v3's `createTypeScriptCache` returned a one-entry `Map`
+* keyed by `JSON.stringify(compilerOptions)`): a consumer that wants keyed
+* reuse holds its own map.
+*
+* `VirtualTypeScriptEnvironment` is deliberately not re-exported — import
+* the type from `@typescript/vfs`, which consumers of this module already
+* declare.
+*
+* @example
+* ```ts
+* import { TsEnvironment } from "@tsdoctor/registry";
+*
+* const environment = TsEnvironment.make({
+*   vfs,
+*   compilerOptions: { strict: true, target: "es2022" },
+* });
+* ```
+*
+* @public
+*/
+var TsEnvironment = class {
+	constructor() {}
+	/** Build a `VirtualTypeScriptEnvironment` over a {@link Vfs}. */
+	static make(options) {
+		return Effect.gen(function* () {
+			const [tsModule, tsVfs, { TsEnumCodec }] = yield* Effect.tryPromise({
+				try: () => Promise.all([
+					import("typescript"),
+					import("@typescript/vfs"),
+					import("@effected/tsconfig-json")
+				]),
+				catch: (cause) => new TsEnvironmentError({ cause })
+			});
+			return yield* Effect.try({
+				try: () => {
+					const typescript = tsModule.default;
+					const projectRoot = options.projectRoot ?? process.cwd();
+					const compilerOptions = TsEnumCodec.encodeCompilerOptions(options.compilerOptions);
+					const executing = typescript.sys?.getExecutingFilePath?.();
+					const libDirectory = executing === void 0 ? void 0 : executing.slice(0, Math.max(executing.lastIndexOf("/"), executing.lastIndexOf("\\")));
+					const system = new Map(tsVfs.createDefaultMapFromNodeModules(compilerOptions, typescript, libDirectory));
+					const rootFiles = [];
+					for (const [path, content] of options.vfs) {
+						const rooted = path.startsWith("/") ? path : `${projectRoot}/${path}`;
+						system.set(rooted, content);
+						if (isTypeDefinition(rooted)) rootFiles.push(rooted);
+					}
+					const sys = tsVfs.createFSBackedSystem(system, projectRoot, typescript, libDirectory);
+					return tsVfs.createVirtualTypeScriptEnvironment(sys, rootFiles, typescript, compilerOptions);
+				},
+				catch: (cause) => new TsEnvironmentError({ cause })
+			});
+		}).pipe(Effect.withSpan("TsEnvironment.make"));
+	}
+};
+
+//#endregion
+export { TsEnvironment, TsEnvironmentError };

package/TypeCache.js

@@ -0,0 +1,256 @@
+import { isSafeRelativePath } from "./internal/resolution.js";
+import { PackageSpec } from "./PackageSpec.js";
+import { Context, Effect, FileSystem, Layer, Option, Path, Schema } from "effect";
+import { Cache } from "@effected/store";
+
+//#region src/TypeCache.ts
+/**
+* Per-package cache metadata: the pinned version, when it was cached and how
+* long it lives.
+*
+* @remarks
+* Stored JSON-encoded in the metadata plane (`@effected/store`'s `Cache`);
+* `ttl` is also forwarded to the store's native TTL so expiry happens there
+* (evict-on-read, bulk prune). An absent `ttl` means the entry never expires.
+*
+* @public
+*/
+var TypeCacheMetadata = class extends Schema.Class("TypeCacheMetadata")({
+	/** The pinned version the files on disk belong to. */
+	version: Schema.String,
+	/** When the package was cached. */
+	cachedAt: Schema.DateTimeUtcFromString,
+	/** Time-to-live; absent = never expires. */
+	ttl: Schema.optionalKey(Schema.DurationFromMillis)
+}) {};
+/** JSON codec for the metadata plane's stored bytes. */
+const MetadataFromJson = Schema.fromJsonString(TypeCacheMetadata);
+/**
+* Raised when a cache operation fails: disk IO, metadata-store IO, or a file
+* path that tries to escape the cache directory.
+*
+* @remarks
+* `cause` carries the underlying failure structurally (a `PlatformError`,
+* the store's `CacheError`, or a `SchemaError` from metadata decoding); v3
+* flattened everything to `message: String(error)`.
+*
+* @public
+*/
+var TypeCacheError = class extends Schema.TaggedError()("TypeCacheError", {
+	/** The cache operation that failed. */
+	operation: Schema.Literals([
+		"exists",
+		"read",
+		"write",
+		"list",
+		"readMetadata",
+		"writeMetadata",
+		"getVfs",
+		"remove",
+		"prune"
+	]),
+	/** The file path or metadata key involved. */
+	path: Schema.String,
+	/** The underlying failure, preserved structurally. */
+	cause: Schema.Defect()
+}) {
+	get message() {
+		return `Type cache ${this.operation} failed for "${this.path}"`;
+	}
+};
+const make = (cacheDir) => Effect.gen(function* () {
+	const fs = yield* FileSystem.FileSystem;
+	const cache = yield* Cache;
+	const path = yield* Path.Path;
+	const pkgDir = (pkg) => path.join(cacheDir, pkg.name, pkg.version);
+	const stagingDir = (pkg) => path.join(cacheDir, pkg.name, `.staging-${pkg.version}`);
+	const fail = (operation, target) => (cause) => new TypeCacheError({
+		operation,
+		path: target,
+		cause
+	});
+	const safeJoin = (operation, root, filePath) => isSafeRelativePath(filePath) ? Effect.succeed(path.join(root, filePath)) : Effect.fail(new TypeCacheError({
+		operation,
+		path: filePath,
+		cause: /* @__PURE__ */ new Error("path escapes the package cache directory")
+	}));
+	const safePath = (operation, pkg, filePath) => safeJoin(operation, pkgDir(pkg), filePath);
+	const listRecursive = (dir, relativeTo, depth) => Effect.gen(function* () {
+		if (depth > 256) return yield* Effect.fail(fail("list", dir)(/* @__PURE__ */ new Error("cache tree exceeds the nesting-depth limit")));
+		const entries = yield* fs.readDirectory(dir).pipe(Effect.mapError(fail("list", dir)));
+		const files = [];
+		for (const entry of entries) {
+			const fullPath = path.join(dir, entry);
+			if ((yield* fs.stat(fullPath).pipe(Effect.mapError(fail("list", fullPath)))).type === "Directory") files.push(...yield* listRecursive(fullPath, relativeTo, depth + 1));
+			else files.push(path.relative(relativeTo, fullPath));
+		}
+		return files;
+	});
+	return {
+		exists: Effect.fn("TypeCache.exists")(function* (pkg) {
+			return yield* fs.exists(pkgDir(pkg)).pipe(Effect.mapError(fail("exists", pkgDir(pkg))));
+		}),
+		read: Effect.fn("TypeCache.read")(function* (pkg, filePath) {
+			const fullPath = yield* safePath("read", pkg, filePath);
+			return yield* fs.readFileString(fullPath).pipe(Effect.mapError(fail("read", fullPath)));
+		}),
+		write: Effect.fn("TypeCache.write")(function* (pkg, filePath, content) {
+			const fullPath = yield* safePath("write", pkg, filePath);
+			const dirPath = path.dirname(fullPath);
+			yield* fs.makeDirectory(dirPath, { recursive: true }).pipe(Effect.mapError(fail("write", dirPath)));
+			yield* fs.writeFileString(fullPath, content).pipe(Effect.mapError(fail("write", fullPath)));
+		}),
+		writePackage: Effect.fn("TypeCache.writePackage")(function* (pkg, files) {
+			const staging = stagingDir(pkg);
+			const live = pkgDir(pkg);
+			yield* fs.remove(staging, {
+				recursive: true,
+				force: true
+			}).pipe(Effect.mapError(fail("write", staging)));
+			yield* fs.makeDirectory(staging, { recursive: true }).pipe(Effect.mapError(fail("write", staging)));
+			for (const [filePath, content] of files) {
+				const fullPath = yield* safeJoin("write", staging, filePath);
+				const dirPath = path.dirname(fullPath);
+				yield* fs.makeDirectory(dirPath, { recursive: true }).pipe(Effect.mapError(fail("write", dirPath)));
+				yield* fs.writeFileString(fullPath, content).pipe(Effect.mapError(fail("write", fullPath)));
+			}
+			yield* fs.remove(live, {
+				recursive: true,
+				force: true
+			}).pipe(Effect.mapError(fail("write", live)));
+			yield* fs.rename(staging, live).pipe(Effect.mapError(fail("write", live)));
+		}),
+		listFiles: Effect.fn("TypeCache.listFiles")(function* (pkg) {
+			return yield* listRecursive(pkgDir(pkg), pkgDir(pkg), 0);
+		}),
+		readMetadata: Effect.fn("TypeCache.readMetadata")(function* (pkg) {
+			const key = pkg.cacheKey;
+			const entry = yield* cache.get(key).pipe(Effect.mapError(fail("readMetadata", key)));
+			if (Option.isNone(entry)) return Option.none();
+			const decoded = yield* Schema.decodeUnknownEffect(MetadataFromJson)(new TextDecoder().decode(entry.value.value)).pipe(Effect.mapError(fail("readMetadata", key)));
+			return Option.some(decoded);
+		}),
+		writeMetadata: Effect.fn("TypeCache.writeMetadata")(function* (pkg, metadata) {
+			const key = pkg.cacheKey;
+			const encoded = yield* Schema.encodeEffect(MetadataFromJson)(metadata).pipe(Effect.mapError(fail("writeMetadata", key)));
+			yield* cache.set({
+				key,
+				value: new TextEncoder().encode(encoded),
+				contentType: "application/json",
+				tags: [pkg.name],
+				...metadata.ttl !== void 0 ? { ttl: metadata.ttl } : {}
+			}).pipe(Effect.mapError(fail("writeMetadata", key)));
+		}),
+		getVfs: Effect.fn("TypeCache.getVfs")(function* (pkg) {
+			const dir = pkgDir(pkg);
+			const files = yield* listRecursive(dir, dir, 0);
+			const vfs = /* @__PURE__ */ new Map();
+			for (const file of files) {
+				const fullPath = path.join(dir, file);
+				const content = yield* fs.readFileString(fullPath).pipe(Effect.mapError(fail("getVfs", fullPath)));
+				vfs.set(`node_modules/${pkg.name}/${file.replace(/\\/g, "/")}`, content);
+			}
+			return vfs;
+		}),
+		remove: Effect.fn("TypeCache.remove")(function* (pkg) {
+			const key = pkg.cacheKey;
+			const dir = pkgDir(pkg);
+			yield* cache.invalidate(key).pipe(Effect.mapError(fail("remove", key)));
+			yield* fs.remove(dir, {
+				recursive: true,
+				force: true
+			}).pipe(Effect.mapError(fail("remove", dir)));
+		}),
+		prune: Effect.gen(function* () {
+			const result = yield* cache.prune().pipe(Effect.mapError(fail("prune", cacheDir)));
+			const removed = [];
+			for (const key of result.keys) {
+				const parsed = PackageSpec.parseCacheKey(key);
+				if (Option.isNone(parsed)) continue;
+				const dir = pkgDir(parsed.value);
+				if (yield* fs.remove(dir, {
+					recursive: true,
+					force: true
+				}).pipe(Effect.as(true), Effect.orElseSucceed(() => false))) removed.push({
+					name: parsed.value.name,
+					version: parsed.value.version
+				});
+			}
+			return {
+				count: result.count,
+				removed
+			};
+		}).pipe(Effect.withSpan("TypeCache.prune"))
+	};
+});
+/**
+* The two-plane cache for fetched type definitions: files on disk under
+* `<cacheDir>/<name>/<version>/`, metadata in `@effected/store`'s `Cache`
+* with native TTL expiry.
+*
+* @remarks
+* The layer statics are parameterized factories — bind the built layer to a
+* `const` and provide that, or two provide sites mint two caches (the layer
+* memoization discipline). The metadata plane is swappable in tests: store's
+* `Cache.layerTest` (`:memory:`) satisfies {@link TypeCache.layer} with no
+* real database file.
+*
+* @example
+* ```ts
+* import { TypeCache } from "@tsdoctor/registry";
+*
+* const TypeCacheLayer = TypeCache.layer({ cacheDir: "/var/cache/my-app/types" });
+* ```
+*
+* @public
+*/
+var TypeCache = class TypeCache extends Context.Service()("type-registry-effect/TypeCache") {
+	/**
+	* A cache rooted at an explicit directory.
+	*
+	* @remarks
+	* `cacheDir` must be an absolute path — a relative one is developer wiring
+	* and dies at layer construction.
+	*/
+	static layer(options) {
+		return Layer.effect(TypeCache, Effect.gen(function* () {
+			if (!(yield* Path.Path).isAbsolute(options.cacheDir)) return yield* Effect.die(/* @__PURE__ */ new Error(`TypeCache.layer: cacheDir must be an absolute path, received "${options.cacheDir}"`));
+			return yield* make(options.cacheDir);
+		}));
+	}
+	/**
+	* A cache rooted under the application's XDG cache directory:
+	* `<AppDirs cache>/<namespace>/`.
+	*
+	* @remarks
+	* Uses `AppDirs.ensureCache`, which also discharges the store's recorded
+	* constraint that the database directory must exist before
+	* `SqliteClient.layer` is built. This package never builds the store layer
+	* itself — the consumer composes `Cache.layerSqlite` (or `layerTest`) at
+	* the edge.
+	*/
+	static layerXdg(options) {
+		const namespace = options?.namespace ?? "ts-vfs";
+		return Layer.effect(TypeCache, Effect.gen(function* () {
+			if (namespace.length === 0 || /[/\\]/.test(namespace) || namespace === "." || namespace === "..") return yield* Effect.die(/* @__PURE__ */ new Error(`TypeCache.layerXdg: \`namespace\` must be a single path component, received ${JSON.stringify(namespace)}`));
+			const xdg = yield* Effect.tryPromise({
+				try: () => import("@effected/xdg"),
+				catch: (cause) => new Error("TypeCache.layerXdg requires the optional `@effected/xdg` peer to be installed", { cause })
+			}).pipe(Effect.orDie);
+			const appDirs = yield* xdg.AppDirs;
+			const fs = yield* FileSystem.FileSystem;
+			const path = yield* Path.Path;
+			const base = yield* appDirs.ensureCache;
+			const cacheDir = path.join(base, namespace);
+			yield* fs.makeDirectory(cacheDir, { recursive: true }).pipe(Effect.mapError((cause) => new xdg.AppDirsError({
+				directory: "cache",
+				path: cacheDir,
+				cause
+			})));
+			return yield* make(cacheDir);
+		}));
+	}
+};
+
+//#endregion
+export { TypeCache, TypeCacheError, TypeCacheMetadata };

package/TypeRegistry.js

@@ -0,0 +1,276 @@
+import { packageJsonUrl } from "./internal/jsdelivr.js";
+import { emit } from "./RegistryEvent.js";
+import { FetchError, PackageFetcher, PackageManifest, PackageNotFoundError, VersionNotFoundError } from "./PackageFetcher.js";
+import { TypeCache, TypeCacheMetadata } from "./TypeCache.js";
+import { TypeResolver } from "./TypeResolver.js";
+import { mergeVfs } from "./Vfs.js";
+import { Context, DateTime, Effect, Layer, Option, Schema, Semaphore } from "effect";
+import { Range, SemVer } from "@effected/semver";
+
+//#region src/TypeRegistry.ts
+/**
+* Raised by {@link TypeRegistryShape.getVfs} when **every** requested package
+* fails.
+*
+* @remarks
+* Carries the per-package failures structurally. v3 abused
+* `PackageNotFoundError` for this case, with a comma-joined `name` and an
+* empty `version`.
+*
+* @public
+*/
+var BatchLoadError = class extends Schema.TaggedError()("BatchLoadError", { 
+/** One entry per failed package, with its typed error preserved. */
+failures: Schema.Array(Schema.Struct({
+	name: Schema.String,
+	version: Schema.String,
+	error: Schema.Defect()
+})) }) {
+	get message() {
+		return `Failed to load type definitions for all ${this.failures.length} requested package(s)`;
+	}
+};
+/**
+* Classify a per-package load failure into a stable `PackageLoadFailed`
+* event kind — from typed error tags and structured fields, never from
+* message substrings (v3's `classifyLoadError` did substring matching over
+* stringified errors; it is dead).
+*/
+const classify = (error) => {
+	if (typeof error !== "object" || error === null || !("_tag" in error)) return "unknown";
+	switch (error._tag) {
+		case "PackageNotFoundError": return "not-found";
+		case "VersionNotFoundError": return "version-range";
+		case "TypeCacheError": return "cache";
+		case "FetchError": {
+			const fetchError = error;
+			if (fetchError.status === 404) return "not-found";
+			if (fetchError.kind === "schema") return "schema";
+			return "network";
+		}
+		default: return "unknown";
+	}
+};
+const make = Effect.gen(function* () {
+	const cache = yield* TypeCache;
+	const fetcher = yield* PackageFetcher;
+	const mutations = yield* Semaphore.make(1);
+	const fetchAndCacheImpl = (pkg, options) => Effect.gen(function* () {
+		yield* emit({
+			_tag: "FetchStart",
+			package: pkg.name,
+			version: pkg.version
+		});
+		const manifest = yield* fetcher.getPackageJson(pkg);
+		const typeFiles = yield* fetcher.getTypeFiles(pkg);
+		const files = [["package.json", JSON.stringify(manifest, null, 2)]];
+		for (const [filePath, content] of typeFiles) {
+			const normalized = filePath.replace(/^\/+/, "");
+			if (normalized !== "package.json") files.push([normalized, content]);
+		}
+		const now = yield* DateTime.now;
+		yield* mutations.withPermits(1)(Effect.gen(function* () {
+			yield* cache.writePackage(pkg, files);
+			yield* cache.writeMetadata(pkg, TypeCacheMetadata.make({
+				version: pkg.version,
+				cachedAt: now,
+				...options?.ttl !== void 0 ? { ttl: options.ttl } : {}
+			}));
+		}));
+	});
+	const getPackageVfsImpl = (pkg, options) => Effect.gen(function* () {
+		const autoFetch = options?.autoFetch ?? true;
+		const [duration, result] = yield* Effect.timed(Effect.gen(function* () {
+			const metadata = yield* cache.readMetadata(pkg);
+			const diskExists = yield* cache.exists(pkg);
+			let source = "cache";
+			if (Option.isSome(metadata) && diskExists) {
+				const now = yield* DateTime.now;
+				yield* emit({
+					_tag: "CacheHit",
+					package: pkg.name,
+					version: pkg.version,
+					age: DateTime.distance(metadata.value.cachedAt, now)
+				});
+			} else if (Option.isNone(metadata) && diskExists) {
+				yield* emit({
+					_tag: "CacheStale",
+					package: pkg.name,
+					version: pkg.version
+				});
+				if (autoFetch) {
+					yield* fetchAndCacheImpl(pkg, options);
+					source = "network";
+				}
+			} else if (autoFetch) {
+				yield* emit({
+					_tag: "CacheMiss",
+					package: pkg.name,
+					version: pkg.version
+				});
+				yield* fetchAndCacheImpl(pkg, options);
+				source = "network";
+			} else return yield* Effect.fail(new PackageNotFoundError({
+				name: pkg.name,
+				version: pkg.version
+			}));
+			return {
+				vfs: yield* cache.getVfs(pkg),
+				source
+			};
+		}));
+		yield* emit({
+			_tag: "PackageLoaded",
+			package: pkg.name,
+			version: pkg.version,
+			files: result.vfs.size,
+			source: result.source,
+			duration
+		});
+		return result.vfs;
+	});
+	const readManifest = (pkg) => Effect.gen(function* () {
+		const content = yield* cache.read(pkg, "package.json");
+		const parsed = yield* Effect.try({
+			try: () => JSON.parse(content),
+			catch: (cause) => new FetchError({
+				url: packageJsonUrl(pkg),
+				kind: "schema",
+				cause
+			})
+		});
+		return yield* Schema.decodeUnknownEffect(PackageManifest)(parsed).pipe(Effect.mapError((cause) => new FetchError({
+			url: packageJsonUrl(pkg),
+			kind: "schema",
+			cause
+		})));
+	});
+	return {
+		hasCached: Effect.fn("TypeRegistry.hasCached")(function* (pkg) {
+			return yield* cache.exists(pkg);
+		}),
+		fetchAndCache: Effect.fn("TypeRegistry.fetchAndCache")(function* (pkg, options) {
+			return yield* fetchAndCacheImpl(pkg, options);
+		}),
+		getPackageVfs: Effect.fn("TypeRegistry.getPackageVfs")(function* (pkg, options) {
+			return yield* getPackageVfsImpl(pkg, options);
+		}),
+		getVfs: Effect.fn("TypeRegistry.getVfs")(function* (packages, options) {
+			yield* emit({
+				_tag: "BatchStart",
+				total: packages.length,
+				packages: packages.map((pkg) => pkg.toString())
+			});
+			const [duration, results] = yield* Effect.timed(Effect.forEach(packages, (pkg) => getPackageVfsImpl(pkg, options).pipe(Effect.map((vfs) => ({
+				ok: true,
+				pkg,
+				vfs
+			})), Effect.catch((error) => emit({
+				_tag: "PackageLoadFailed",
+				package: pkg.name,
+				version: pkg.version,
+				kind: classify(error),
+				error
+			}).pipe(Effect.as({
+				ok: false,
+				pkg,
+				error
+			})))), { concurrency: 5 }));
+			const succeeded = results.filter((result) => result.ok);
+			const failed = results.filter((result) => !result.ok);
+			const merged = mergeVfs(...succeeded.map((result) => result.vfs));
+			yield* emit({
+				_tag: "BatchComplete",
+				loaded: succeeded.length,
+				failed: failed.length,
+				total: packages.length,
+				totalFiles: merged.size,
+				duration
+			});
+			if (failed.length === packages.length && packages.length > 0) return yield* Effect.fail(new BatchLoadError({ failures: failed.map((result) => ({
+				name: result.pkg.name,
+				version: result.pkg.version,
+				error: result.error
+			})) }));
+			return merged;
+		}),
+		resolveImport: Effect.fn("TypeRegistry.resolveImport")(function* (pkg, specifier) {
+			const manifest = yield* readManifest(pkg);
+			return TypeResolver.resolveImport(specifier, manifest, pkg);
+		}),
+		getTypeEntries: Effect.fn("TypeRegistry.getTypeEntries")(function* (pkg) {
+			const manifest = yield* readManifest(pkg);
+			return TypeResolver.resolveTypeEntries(manifest, pkg);
+		}),
+		resolveVersion: Effect.fn("TypeRegistry.resolveVersion")(function* (name, ref) {
+			const resolved = yield* Effect.gen(function* () {
+				const meta = yield* fetcher.getVersions(name);
+				if (Object.hasOwn(meta.tags, ref)) {
+					const tagged = meta.tags[ref];
+					if (typeof tagged === "string") return tagged;
+				}
+				if (meta.versions.includes(ref)) return ref;
+				const range = yield* Range.parse(ref).pipe(Effect.mapError(() => new VersionNotFoundError({
+					name,
+					ref,
+					available: meta.versions.slice(0, 20)
+				})));
+				const published = yield* Effect.forEach(meta.versions, (version) => SemVer.parse(version).pipe(Effect.option));
+				const best = Range.maxSatisfying(published.filter(Option.isSome).map((option) => option.value), range);
+				if (Option.isNone(best)) return yield* Effect.fail(new VersionNotFoundError({
+					name,
+					ref,
+					available: meta.versions.slice(0, 20)
+				}));
+				return best.value.toString();
+			}).pipe(Effect.tapError((error) => emit({
+				_tag: "VersionResolveFailed",
+				package: name,
+				requested: ref,
+				kind: error._tag === "VersionNotFoundError" ? "no-match" : error.status === 404 ? "not-found" : "network"
+			})));
+			yield* emit({
+				_tag: "VersionResolved",
+				package: name,
+				requested: ref,
+				resolved
+			});
+			return resolved;
+		}),
+		clearCache: Effect.fn("TypeRegistry.clearCache")(function* (pkg) {
+			return yield* mutations.withPermits(1)(cache.remove(pkg));
+		}),
+		pruneCache: mutations.withPermits(1)(cache.prune).pipe(Effect.withSpan("TypeRegistry.pruneCache"))
+	};
+});
+/**
+* The facade: one service collapsing the cache, fetcher and resolver behind
+* the operations documentation tooling actually calls.
+*
+* @remarks
+* `yield* TypeRegistry` replaces the v3 floating-function namespace (which
+* the rspress consumer immediately re-wrapped in its own service). Per-method
+* error unions stay precise. Compose at the edge: platform layers + store
+* `Cache.layerSqlite` + `TypeCache.layerXdg` + `PackageFetcher.layer` +
+* `TypeRegistry.layer`.
+*
+* @example
+* ```ts
+* import { PackageSpec, TypeRegistry } from "@tsdoctor/registry";
+* import { Effect } from "effect";
+*
+* const program = Effect.gen(function* () {
+*   const registry = yield* TypeRegistry;
+*   return yield* registry.getVfs([PackageSpec.fromString("zod@3.23.8")]);
+* });
+* ```
+*
+* @public
+*/
+var TypeRegistry = class TypeRegistry extends Context.Service()("type-registry-effect/TypeRegistry") {
+	/** The live facade over {@link TypeCache} and {@link PackageFetcher}. */
+	static layer = Layer.effect(TypeRegistry, make);
+};
+
+//#endregion
+export { BatchLoadError, TypeRegistry };