@tsdoctor/registry 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 C. Spencer Beggs
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/PackageFetcher.js

@@ -0,0 +1,241 @@
+import { MAX_TYPE_BYTES_PER_PACKAGE, MAX_TYPE_FILES_PER_PACKAGE } from "./internal/limits.js";
+import { FileTreeResponse, TYPE_FILE_PATTERN, VersionsResponse, fileTreeUrl, fileUrl, packageJsonUrl, versionsUrl } from "./internal/jsdelivr.js";
+import { emit } from "./RegistryEvent.js";
+import { Cause, Context, Duration, Effect, Layer, Ref, Schedule, Schema } from "effect";
+import * as HttpClient from "effect/unstable/http/HttpClient";
+import * as HttpClientError from "effect/unstable/http/HttpClientError";
+
+//#region src/PackageFetcher.ts
+/**
+* Raised when an HTTP request or response fails at the jsDelivr boundary.
+*
+* @remarks
+* `kind` classifies the failure structurally — `transport` (connection,
+* timeout), `status` (non-2xx, with `status` populated), `body` (reading or
+* bounding the body) or `schema` (response validation) — and `status` is a
+* structured field, so classification consumers branch on typed data. v3
+* folded the HTTP status into a message string and substring-matched `"404"`
+* back out of it.
+*
+* @public
+*/
+var FetchError = class extends Schema.TaggedError()("FetchError", {
+	/** The request URL. */
+	url: Schema.String,
+	/** The HTTP status, when the failure has one. */
+	status: Schema.optionalKey(Schema.Number),
+	/** What failed, structurally. */
+	kind: Schema.Literals([
+		"transport",
+		"status",
+		"body",
+		"schema"
+	]),
+	/** The underlying failure, preserved structurally. */
+	cause: Schema.Defect()
+}) {
+	get message() {
+		const statusPart = this.status !== void 0 ? ` (HTTP ${this.status})` : "";
+		return `Fetch ${this.kind} failure${statusPart} for ${this.url}`;
+	}
+};
+/**
+* Raised when a pinned package version does not exist on the CDN (HTTP 404).
+*
+* @remarks
+* The 404 → `PackageNotFoundError` promotion happens on the typed
+* `FetchError` `status` field. Also raised by `TypeRegistry.getPackageVfs`
+* on a cache miss with `autoFetch: false`.
+*
+* @public
+*/
+var PackageNotFoundError = class extends Schema.TaggedError()("PackageNotFoundError", {
+	/** The package name. */
+	name: Schema.String,
+	/** The version reference that was requested. */
+	version: Schema.String
+}) {
+	get message() {
+		return `Package ${this.name}@${this.version} was not found`;
+	}
+};
+/**
+* Raised when local version resolution finds no published version matching
+* the requested reference.
+*
+* @remarks
+* Raised by `TypeRegistry.resolveVersion` — typed, with the requested ref and
+* bounded available-version context. v3 detected this case by
+* substring-matching CDN error prose.
+*
+* @public
+*/
+var VersionNotFoundError = class extends Schema.TaggedError()("VersionNotFoundError", {
+	/** The package name. */
+	name: Schema.String,
+	/** The requested reference: a range, dist-tag or exact version. */
+	ref: Schema.String,
+	/** A bounded sample of the versions that ARE published. */
+	available: Schema.Array(Schema.String)
+}) {
+	get message() {
+		return `No published version of ${this.name} matches "${this.ref}"`;
+	}
+};
+/**
+* The lenient `package.json` subset the type resolver reads.
+*
+* @remarks
+* Deliberately NOT `@effected/package-json`: its schemas validate strictly
+* (branded names, SPDX licenses), and the manifests this package decodes come
+* off a CDN and include every historical malformation npm ever published.
+* Validation here is lenient and scoped to exactly the fields resolution
+* needs.
+*
+* @public
+*/
+const PackageManifest = Schema.Struct({
+	name: Schema.optionalKey(Schema.String),
+	version: Schema.optionalKey(Schema.String),
+	types: Schema.optionalKey(Schema.String),
+	typings: Schema.optionalKey(Schema.String),
+	main: Schema.optionalKey(Schema.String),
+	module: Schema.optionalKey(Schema.String),
+	exports: Schema.optionalKey(Schema.Union([
+		Schema.String,
+		Schema.Record(Schema.String, Schema.Unknown),
+		Schema.Array(Schema.Unknown)
+	])),
+	typesVersions: Schema.optionalKey(Schema.Record(Schema.String, Schema.Record(Schema.String, Schema.Union([Schema.Array(Schema.String), Schema.String])))),
+	dependencies: Schema.optionalKey(Schema.Record(Schema.String, Schema.String)),
+	peerDependencies: Schema.optionalKey(Schema.Record(Schema.String, Schema.String)),
+	devDependencies: Schema.optionalKey(Schema.Record(Schema.String, Schema.String))
+});
+const retrySchedule = Schedule.exponential(Duration.millis(100));
+/**
+* Deadline for materializing a response body. `Effect.timeout` on the request
+* ends once headers arrive; without a second deadline a stalled body stream
+* would hang a fiber indefinitely.
+*/
+const bodyTimeout = Duration.seconds(30);
+/** Retry only failures that can be transient: transport errors and timeouts. */
+const isTransient = (error) => Cause.isTimeoutError(error) || HttpClientError.isHttpClientError(error) && error.reason._tag === "TransportError";
+const make = Effect.gen(function* () {
+	const http = yield* HttpClient.HttpClient;
+	const fetchOk = (url) => http.get(url).pipe(Effect.timeout(Duration.seconds(30)), Effect.retry({
+		schedule: retrySchedule,
+		times: 3,
+		while: isTransient
+	}), Effect.mapError((cause) => new FetchError({
+		url,
+		kind: "transport",
+		cause
+	})), Effect.flatMap((response) => response.status >= 200 && response.status < 300 ? Effect.succeed(response) : response.text.pipe(Effect.timeout(bodyTimeout), Effect.match({
+		onFailure: (readFailure) => ({
+			bodySnippet: "",
+			cause: readFailure
+		}),
+		onSuccess: (body) => {
+			const bodySnippet = body.slice(0, 200);
+			return {
+				bodySnippet,
+				cause: bodySnippet
+			};
+		}
+	}), Effect.flatMap(({ bodySnippet, cause }) => emit({
+		_tag: "FetchFailed",
+		url,
+		status: response.status,
+		bodySnippet
+	}).pipe(Effect.andThen(Effect.fail(new FetchError({
+		url,
+		status: response.status,
+		kind: "status",
+		cause
+	}))))))));
+	const fetchText = (url) => fetchOk(url).pipe(Effect.flatMap((response) => response.text.pipe(Effect.timeout(bodyTimeout), Effect.mapError((cause) => new FetchError({
+		url,
+		kind: "body",
+		cause
+	})))));
+	const fetchJson = (url, schema) => fetchOk(url).pipe(Effect.flatMap((response) => response.json.pipe(Effect.timeout(bodyTimeout), Effect.mapError((cause) => new FetchError({
+		url,
+		kind: "body",
+		cause
+	})))), Effect.flatMap((data) => Schema.decodeUnknownEffect(schema)(data).pipe(Effect.mapError((cause) => new FetchError({
+		url,
+		kind: "schema",
+		cause
+	})))));
+	/** Promote a typed 404 into the package-level not-found error. */
+	const promote404 = (pkg) => (error) => error.status === 404 ? new PackageNotFoundError({
+		name: pkg.name,
+		version: pkg.version
+	}) : error;
+	/** The decoded flat tree, with names normalized and per-file sizes kept. */
+	const fetchTree = (pkg) => fetchJson(fileTreeUrl(pkg), FileTreeResponse).pipe(Effect.mapError(promote404(pkg)), Effect.map((tree) => tree.files.map((file) => ({
+		name: file.name.replace(/^\/+/, ""),
+		size: file.size
+	}))));
+	const getFileTree = Effect.fn("PackageFetcher.getFileTree")(function* (pkg) {
+		return (yield* fetchTree(pkg)).map((file) => file.name);
+	});
+	const downloadFile = Effect.fn("PackageFetcher.downloadFile")(function* (pkg, filePath) {
+		const url = yield* Effect.try({
+			try: () => fileUrl(pkg, filePath),
+			catch: (cause) => new FetchError({
+				url: fileTreeUrl(pkg),
+				kind: "transport",
+				cause
+			})
+		});
+		return yield* fetchText(url).pipe(Effect.mapError(promote404(pkg)));
+	});
+	const getPackageJson = Effect.fn("PackageFetcher.getPackageJson")(function* (pkg) {
+		return yield* fetchJson(packageJsonUrl(pkg), PackageManifest).pipe(Effect.mapError(promote404(pkg)));
+	});
+	const getVersions = Effect.fn("PackageFetcher.getVersions")(function* (name) {
+		return yield* fetchJson(versionsUrl(name), VersionsResponse);
+	});
+	const overBudget = (pkg, detail) => new FetchError({
+		url: fileTreeUrl(pkg),
+		kind: "body",
+		cause: new Error(detail)
+	});
+	return {
+		getVersions,
+		getFileTree,
+		downloadFile,
+		getPackageJson,
+		getTypeFiles: Effect.fn("PackageFetcher.getTypeFiles")(function* (pkg) {
+			const typeFiles = (yield* fetchTree(pkg)).filter((file) => TYPE_FILE_PATTERN.test(file.name));
+			if (typeFiles.length > 5e3) return yield* Effect.fail(overBudget(pkg, `package publishes ${typeFiles.length} declaration files, over the ${MAX_TYPE_FILES_PER_PACKAGE}-file budget`));
+			const declaredBytes = typeFiles.reduce((total, file) => total + (file.size ?? 0), 0);
+			if (declaredBytes > 67108864) return yield* Effect.fail(overBudget(pkg, `declared declaration files total ${declaredBytes} bytes, over the byte budget`));
+			const encoder = new TextEncoder();
+			const budget = yield* Ref.make(0);
+			const entries = yield* Effect.forEach(typeFiles, (file) => downloadFile(pkg, file.name).pipe(Effect.tap((content) => Ref.updateAndGet(budget, (total) => total + encoder.encode(content).length).pipe(Effect.flatMap((total) => total > 67108864 ? Effect.fail(overBudget(pkg, `declaration files exceed the ${MAX_TYPE_BYTES_PER_PACKAGE}-byte budget`)) : Effect.void))), Effect.map((content) => [file.name, content])), { concurrency: 10 });
+			return new Map(entries);
+		})
+	};
+});
+/**
+* The jsDelivr CDN client.
+*
+* @remarks
+* Requests time out after 30 seconds; transport and timeout failures retry
+* up to 3 times with exponential back-off (starting at 100 ms). Non-2xx
+* responses fail fast with a typed status and emit a `FetchFailed` event
+* carrying the status and a body snippet. If a second registry backend ever
+* appears it arrives as another layer for this service — the service seam is
+* the extension point.
+*
+* @public
+*/
+var PackageFetcher = class PackageFetcher extends Context.Service()("type-registry-effect/PackageFetcher") {
+	/** The jsDelivr-backed layer; requires an `HttpClient`. */
+	static layer = Layer.effect(PackageFetcher, make);
+};
+
+//#endregion
+export { FetchError, PackageFetcher, PackageManifest, PackageNotFoundError, VersionNotFoundError };

package/PackageSpec.js

@@ -0,0 +1,182 @@
+import { Option, Schema } from "effect";
+
+//#region src/PackageSpec.ts
+/**
+* Node.js built-in base module names, used by
+* {@link PackageSpec.normalizeSpecifier} to map built-in specifiers to the
+* `node` types package. Matched against the specifier's FIRST path segment,
+* so every built-in subpath (`fs/promises`, `readline/promises`,
+* `util/types`, …) normalizes without enumerating them.
+*/
+const NODE_BUILTINS = /* @__PURE__ */ new Set([
+	"assert",
+	"async_hooks",
+	"buffer",
+	"child_process",
+	"cluster",
+	"console",
+	"constants",
+	"crypto",
+	"dgram",
+	"diagnostics_channel",
+	"dns",
+	"domain",
+	"events",
+	"fs",
+	"http",
+	"http2",
+	"https",
+	"inspector",
+	"module",
+	"net",
+	"os",
+	"path",
+	"perf_hooks",
+	"process",
+	"punycode",
+	"querystring",
+	"readline",
+	"repl",
+	"stream",
+	"string_decoder",
+	"timers",
+	"tls",
+	"trace_events",
+	"tty",
+	"url",
+	"util",
+	"v8",
+	"vm",
+	"wasi",
+	"worker_threads",
+	"zlib"
+]);
+/**
+* A single name segment: no separators, no `@`, no whitespace, no cache-key
+* or URL delimiters (`:` is the cacheKey delimiter — a version containing it
+* would defeat `parseCacheKey`; `?`/`#` would truncate CDN URLs), and not a
+* relative path component. Deliberately lenient beyond that — the CDN serves
+* every historical malformation npm ever published — but strict enough that a
+* name or version can never escape its cache directory when joined into a
+* path.
+*/
+const SAFE_SEGMENT = /^(?!\.{1,2}$)[^/\\@\s:?#]+$/;
+/** `name` or `@scope/name`, each segment {@link SAFE_SEGMENT}-shaped. */
+const NAME_PATTERN = /^(@(?!\.{1,2}\/)[^/\\@\s:?#]+\/)?(?!\.{1,2}$)[^/\\@\s:?#]+$/;
+/**
+* Identifies a package at a version reference.
+*
+* @remarks
+* `version` is the reference **as requested** — an exact version, a range or
+* a dist-tag — and is pinned later by `TypeRegistry.resolveVersion`. Both
+* fields are validated just enough that they can never traverse outside a
+* cache directory when joined into a path; otherwise validation is lenient
+* (CDN reality).
+*
+* Construct via `PackageSpec.make({ name, version })` or
+* {@link PackageSpec.fromString} — never `new`.
+*
+* @example
+* ```ts
+* import { PackageSpec } from "@tsdoctor/registry";
+*
+* const pkg = PackageSpec.fromString("zod@3.23.8");
+* console.log(pkg.name, pkg.version, pkg.cacheKey);
+* // => "zod" "3.23.8" "zod:3.23.8"
+* ```
+*
+* @public
+*/
+var PackageSpec = class PackageSpec extends Schema.Class("PackageSpec")({
+	/** The npm package name (e.g. `"zod"`, `"@effect/schema"`). */
+	name: Schema.String.check(Schema.isPattern(NAME_PATTERN)),
+	/** The version reference as requested: exact, range, or dist-tag. */
+	version: Schema.String.check(Schema.isPattern(SAFE_SEGMENT))
+}) {
+	/**
+	* Parse a `name@version` specifier (`"zod@3.23.8"`, `"@scope/pkg@^1.0.0"`).
+	*
+	* @remarks
+	* A specifier without a version part defaults to `"latest"`. An invalid
+	* specifier is developer wiring, not input — it throws (defect posture),
+	* exactly like `PackageSpec.make` with invalid fields.
+	*/
+	static fromString(spec) {
+		const at = spec.lastIndexOf("@");
+		if (at > 0) return PackageSpec.make({
+			name: spec.slice(0, at),
+			version: spec.slice(at + 1)
+		});
+		return PackageSpec.make({
+			name: spec,
+			version: "latest"
+		});
+	}
+	/**
+	* Extract the npm package name from an arbitrary import specifier.
+	*
+	* @remarks
+	* `node:` specifiers and Node built-ins normalize to `"node"` (the
+	* `@types/node` convention); scoped specifiers keep scope and name but drop
+	* deep-import segments; bare specifiers keep only the first path segment.
+	*
+	* @example
+	* ```ts
+	* import { PackageSpec } from "@tsdoctor/registry";
+	*
+	* PackageSpec.normalizeSpecifier("node:fs");                // "node"
+	* PackageSpec.normalizeSpecifier("@effect/platform/Http"); // "@effect/platform"
+	* PackageSpec.normalizeSpecifier("lodash/fp");              // "lodash"
+	* ```
+	*/
+	static normalizeSpecifier(specifier) {
+		if (specifier.startsWith("node:")) return "node";
+		if (specifier.startsWith("@")) {
+			const parts = specifier.split("/");
+			if (parts.length >= 2) return `${parts[0]}/${parts[1]}`;
+			return specifier;
+		}
+		const firstSlash = specifier.indexOf("/");
+		const base = firstSlash === -1 ? specifier : specifier.slice(0, firstSlash);
+		if (NODE_BUILTINS.has(base)) return "node";
+		return base;
+	}
+	/**
+	* Parse a {@link PackageSpec.cacheKey} back into a spec.
+	*
+	* @remarks
+	* Scoped keys (leading `@`) have three colon segments, unscoped keys two.
+	* `Option.none()` for keys matching neither shape — the metadata store may
+	* hold keys this package never wrote.
+	*/
+	static parseCacheKey(key) {
+		const parts = key.split(":");
+		const candidate = key.startsWith("@") ? parts.length === 3 ? {
+			name: `${parts[0]}/${parts[1]}`,
+			version: parts[2]
+		} : void 0 : parts.length === 2 ? {
+			name: parts[0],
+			version: parts[1]
+		} : void 0;
+		if (candidate === void 0 || !NAME_PATTERN.test(candidate.name) || !SAFE_SEGMENT.test(candidate.version)) return Option.none();
+		return Option.some(PackageSpec.make(candidate));
+	}
+	/** The `name@version` string form. */
+	toString() {
+		return `${this.name}@${this.version}`;
+	}
+	/**
+	* The colon-delimited metadata-store key: `@scope:name:version` for scoped
+	* packages, `name:version` otherwise.
+	*
+	* @remarks
+	* The scheme mirrors v3's on-disk layout but there is no compat contract
+	* with databases written by `type-registry-effect` — nothing was published.
+	*/
+	get cacheKey() {
+		return this.name.startsWith("@") ? `${this.name.replace("/", ":")}:${this.version}` : `${this.name}:${this.version}`;
+	}
+};
+
+//#endregion
+export { PackageSpec };

package/README.md

@@ -0,0 +1,94 @@
+# @tsdoctor/registry
+
+[![npm](https://img.shields.io/npm/v/@tsdoctor/registry?label=npm&color=cb3837)](https://www.npmjs.com/package/@tsdoctor/registry)
+[![License: MIT](https://img.shields.io/badge/License-MIT-4caf50.svg)](https://opensource.org/licenses/MIT)
+[![Node.js %3E%3D24.11.0](https://img.shields.io/badge/Node.js-%3E%3D24.11.0-5fa04e.svg)](https://nodejs.org/)
+[![TypeScript 6.0](https://img.shields.io/badge/TypeScript-6.0-3178c6.svg)](https://www.typescriptlang.org/)
+
+TypeScript virtual file systems for Effect: fetch, cache and resolve type definitions from npm via the jsDelivr CDN, and build `@typescript/vfs` environments for Twoslash-style documentation tooling.
+
+## Why @tsdoctor/registry
+
+Documentation tooling that typechecks code samples needs the declaration files for whatever packages those samples import, and needs them without a real `node_modules`. Fetching them by hand means writing a CDN client, a disk cache with expiry, and a module resolver that understands `exports`, `typesVersions` and the legacy `types` field. This package is those three things behind one service, with typed errors and no hidden IO — every filesystem, HTTP and database dependency is provided by you at the edge.
+
+## Install
+
+```bash
+npm install @tsdoctor/registry effect @effect/platform-node @effected/store @effected/semver
+```
+
+```bash
+pnpm add @tsdoctor/registry effect @effect/platform-node @effected/store @effected/semver
+```
+
+Requires Node.js >=24.11.0. Those four peers are required. The rest are optional and pull in only with the feature that uses them:
+
+```bash
+# for TypeCache.layerXdg
+npm install @effected/xdg
+# for TsEnvironment.make
+npm install @effected/tsconfig-json typescript @typescript/vfs
+```
+
+Every dependency here is a peer rather than a bundled dependency, including `@effected/semver`, whose types appear in no exported signature. That is deliberate: each `@effected/*` package pins an exact `effect` version as its own peer, so bundling one would create a second resolution site that can land on a different `effect` build than yours and fail at import. As peers they all resolve in your closure, against your `effect`.
+
+Install `@effected/store` such that it resolves to one copy. `Cache` is keyed by package identity, so a duplicated install gives your `Cache.layerSqlite` a different key than the one `TypeCache` asks for, and the requirement goes unsatisfied with no error at the install site.
+
+## Quick start
+
+Everything composes at the edge: this package builds no `FileSystem`, `HttpClient` or `Cache` layer of its own, so you pick the implementations.
+
+```ts
+import { mkdtempSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { NodeFileSystem } from "@effect/platform-node";
+import { Cache } from "@effected/store";
+import { Effect, Layer, Path } from "effect";
+import * as FetchHttpClient from "effect/unstable/http/FetchHttpClient";
+import { PackageFetcher, PackageSpec, TypeCache, TypeRegistry } from "@tsdoctor/registry";
+
+const RegistryLayer = TypeRegistry.layer.pipe(
+  Layer.provideMerge(
+    Layer.mergeAll(TypeCache.layer({ cacheDir: mkdtempSync(join(tmpdir(), "types-")) }), PackageFetcher.layer),
+  ),
+  Layer.provide(Layer.mergeAll(Cache.layerTest(), NodeFileSystem.layer, Path.layer, FetchHttpClient.layer)),
+);
+
+const program = Effect.gen(function* () {
+  const registry = yield* TypeRegistry;
+  const version = yield* registry.resolveVersion("zod", "^3.23.0");
+  const vfs = yield* registry.getPackageVfs(PackageSpec.make({ name: "zod", version }));
+  console.log(version, vfs.size);
+  // the pinned version matching the range, then the file count (both vary by package)
+  return vfs;
+});
+
+await Effect.runPromise(program.pipe(Effect.provide(RegistryLayer)));
+```
+
+`Cache.layerTest()` keeps the metadata plane in memory. For a persistent cache, swap it for `Cache.layerSqlite` and root the files under the XDG cache directory with `TypeCache.layerXdg` — see [getting started](docs/01-getting-started.md).
+
+## Features
+
+- `TypeRegistry` — the facade over cache, fetcher and resolver: `getVfs`, `getPackageVfs`, `fetchAndCache`, `resolveVersion`, `resolveImport`, `getTypeEntries`, `hasCached`, `clearCache`, `pruneCache`.
+- `TypeCache` — a two-plane cache: declaration files on disk, per-package metadata in an `@effected/store` `Cache` with native TTL expiry and pruning.
+- `PackageFetcher` — the jsDelivr-backed CDN client, requiring only an `HttpClient`.
+- `TypeResolver` — static resolution of import specifiers and type entry points against a package manifest, covering `exports`, `typesVersions` and legacy fields.
+- `TsEnvironment` — builds a `VirtualTypeScriptEnvironment` over a VFS from tsconfig-JSON compiler options, loading the optional `typescript` peers lazily so a consumer that never calls it never loads the compiler.
+- `VirtualPackage` — synthesizes a package from locally supplied declaration content, for API Extractor output and hand-written ambient types.
+- `RegistryEvent` and `RegistryObserver` — an opt-in, zero-cost progress channel; the library logs nothing on its own.
+- Typed errors throughout: `FetchError`, `PackageNotFoundError`, `VersionNotFoundError`, `TypeCacheError`, `BatchLoadError`, `TsEnvironmentError`.
+
+## Documentation
+
+- [Getting started](docs/01-getting-started.md) — install, peer dependencies, and the edge-wiring recipes for temporary and XDG-rooted caches.
+- [Caching](docs/02-caching.md) — the two-plane cache, TTL and the stale-vs-miss ladder, pruning, and choosing a cache root.
+- [Observability](docs/03-observability.md) — the `RegistryEvent` catalogue, wiring an observer, and the tracing spans each method opens.
+- [Architecture](docs/04-architecture.md) — how the services compose, why composition happens at the edge, and the error model.
+- [API reference](docs/05-api-reference.md) — every exported service, schema, helper and error.
+- [Troubleshooting](docs/06-troubleshooting.md) — missing services, optional peers, cache permissions and CDN failures.
+
+## License
+
+[MIT](LICENSE)

package/RegistryEvent.js

@@ -0,0 +1,146 @@
+import { Context, Effect, Layer, Option, Schema } from "effect";
+
+//#region src/RegistryEvent.ts
+/**
+* Discriminated union of typed progress events emitted during registry
+* operations.
+*
+* @remarks
+* The consumer-facing progress surface. Emission is opt-in and zero-cost:
+* internal call sites resolve the {@link RegistryObserver} via
+* `Effect.serviceOption`, so no requirement is added to any signature and
+* absence is a no-op. The library performs no `Effect.log` of its own — the
+* host owns presentation.
+*
+* Schema-backed (the store `CacheEventPayload` precedent) because events
+* cross the library/host boundary and hosts ship them to telemetry. Narrow
+* with `switch (event._tag)` or `Match`.
+*
+* @public
+*/
+const RegistryEvent = Schema.Union([
+	Schema.TaggedStruct("VersionResolved", {
+		package: Schema.String,
+		requested: Schema.String,
+		resolved: Schema.String
+	}),
+	Schema.TaggedStruct("VersionResolveFailed", {
+		package: Schema.String,
+		requested: Schema.String,
+		kind: Schema.Literals([
+			"not-found",
+			"no-match",
+			"network"
+		])
+	}),
+	Schema.TaggedStruct("CacheHit", {
+		package: Schema.String,
+		version: Schema.String,
+		/** How long ago the entry was cached. */
+		age: Schema.Duration
+	}),
+	Schema.TaggedStruct("CacheStale", {
+		package: Schema.String,
+		version: Schema.String
+	}),
+	Schema.TaggedStruct("CacheMiss", {
+		package: Schema.String,
+		version: Schema.String
+	}),
+	Schema.TaggedStruct("FetchStart", {
+		package: Schema.String,
+		version: Schema.String
+	}),
+	Schema.TaggedStruct("FetchFailed", {
+		url: Schema.String,
+		status: Schema.Number,
+		bodySnippet: Schema.String
+	}),
+	Schema.TaggedStruct("PackageLoaded", {
+		package: Schema.String,
+		version: Schema.String,
+		files: Schema.Number,
+		source: Schema.Literals(["cache", "network"]),
+		duration: Schema.Duration
+	}),
+	Schema.TaggedStruct("PackageLoadFailed", {
+		package: Schema.String,
+		version: Schema.String,
+		kind: Schema.Literals([
+			"not-found",
+			"version-range",
+			"schema",
+			"network",
+			"cache",
+			"unknown"
+		]),
+		/** The typed error itself, preserved structurally. */
+		error: Schema.Defect()
+	}),
+	Schema.TaggedStruct("BatchStart", {
+		total: Schema.Number,
+		packages: Schema.Array(Schema.String)
+	}),
+	Schema.TaggedStruct("BatchComplete", {
+		loaded: Schema.Number,
+		failed: Schema.Number,
+		total: Schema.Number,
+		totalFiles: Schema.Number,
+		duration: Schema.Duration
+	})
+]);
+/**
+* The opt-in registry event observer.
+*
+* @remarks
+* Providing no observer layer is the default and costs nothing — every
+* internal emission site resolves this service via `Effect.serviceOption`
+* and no-ops on absence. Events here are progress reporting for a host UI —
+* a push callback with no subscription lifecycle or `Scope`, usable from
+* non-Effect hosts. (The store `Cache` exposes a `PubSub` instead because
+* its events are intrinsic to an eviction-bearing store; the two postures
+* are deliberate and should not be unified.)
+*
+* @example
+* ```ts
+* import { RegistryObserver } from "@tsdoctor/registry";
+*
+* const ObserverLayer = RegistryObserver.layerCallback((event) => {
+*   if (event._tag === "PackageLoadFailed") console.warn(event.package, event.kind);
+* });
+* ```
+*
+* @public
+*/
+var RegistryObserver = class RegistryObserver extends Context.Service()("type-registry-effect/RegistryObserver") {
+	/**
+	* Build an observer layer from a plain callback — the lowest-friction
+	* bridge for non-Effect hosts.
+	*
+	* @remarks
+	* A throwing callback is a programmer bug and stays a defect; it is not
+	* laundered into any typed error channel.
+	*/
+	static layerCallback(onEvent) {
+		return Layer.succeed(RegistryObserver, { emit: (event) => Effect.sync(() => onEvent(event)) });
+	}
+	/**
+	* A no-op observer. Equivalent to providing nothing, but explicit — makes
+	* "events are intentionally dropped" visible in a composition.
+	*/
+	static layerNoop = Layer.succeed(RegistryObserver, { emit: () => Effect.void });
+};
+/**
+* Emit a {@link (RegistryEvent:type)} to the host's observer, if one is
+* provided. Internal emission sites use this; it adds no requirement to the
+* caller's signature and is a no-op when no observer layer is in scope.
+*
+* @internal
+*/
+const emit = (event) => Effect.serviceOption(RegistryObserver).pipe(Effect.flatMap(Option.match({
+	onNone: () => Effect.void,
+	onSome: (observer) => observer.emit(event)
+})));
+
+//#endregion
+export { RegistryEvent, RegistryObserver, emit };