@tsdoctor/registry 0.1.0

package/index.d.ts

@@ -0,0 +1,990 @@
+import { Cause, Context, Duration, Effect, FileSystem, Layer, Option, Path, PlatformError, Schema } from "effect";
+import * as HttpClient from "effect/unstable/http/HttpClient";
+import { CompilerOptions } from "@effected/tsconfig-json";
+import { VirtualTypeScriptEnvironment } from "@typescript/vfs";
+import { Cache } from "@effected/store";
+import { AppDirs, AppDirsError } from "@effected/xdg";
+//#region src/PackageSpec.d.ts
+declare const PackageSpec_base: Schema.Class<PackageSpec, Schema.Struct<{
+  /** The npm package name (e.g. `"zod"`, `"@effect/schema"`). */
+  readonly name: Schema.String;
+  /** The version reference as requested: exact, range, or dist-tag. */
+  readonly version: Schema.String;
+}>, {}>;
+/**
+ * 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
+ */
+declare class PackageSpec extends PackageSpec_base {
+  /**
+   * 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: string): PackageSpec;
+  /**
+   * 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: string): string;
+  /**
+   * 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: string): Option.Option<PackageSpec>;
+  /** The `name@version` string form. */
+  toString(): string;
+  /**
+   * 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(): string;
+}
+//#endregion
+//#region src/PackageFetcher.d.ts
+declare const FetchError_base: Schema.Class<FetchError, Schema.TaggedStruct<"FetchError", {
+  /** The request URL. */
+  readonly url: Schema.String;
+  /** The HTTP status, when the failure has one. */
+  readonly status: Schema.optionalKey<Schema.Number>;
+  /** What failed, structurally. */
+  readonly kind: Schema.Literals<readonly ["transport", "status", "body", "schema"]>;
+  /** The underlying failure, preserved structurally. */
+  readonly cause: Schema.Defect;
+}>, Cause.YieldableError>;
+/**
+ * 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
+ */
+declare class FetchError extends FetchError_base {
+  get message(): string;
+}
+declare const PackageNotFoundError_base: Schema.Class<PackageNotFoundError, Schema.TaggedStruct<"PackageNotFoundError", {
+  /** The package name. */
+  readonly name: Schema.String;
+  /** The version reference that was requested. */
+  readonly version: Schema.String;
+}>, Cause.YieldableError>;
+/**
+ * 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
+ */
+declare class PackageNotFoundError extends PackageNotFoundError_base {
+  get message(): string;
+}
+declare const VersionNotFoundError_base: Schema.Class<VersionNotFoundError, Schema.TaggedStruct<"VersionNotFoundError", {
+  /** The package name. */
+  readonly name: Schema.String;
+  /** The requested reference: a range, dist-tag or exact version. */
+  readonly ref: Schema.String;
+  /** A bounded sample of the versions that ARE published. */
+  readonly available: Schema.$Array<Schema.String>;
+}>, Cause.YieldableError>;
+/**
+ * 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
+ */
+declare class VersionNotFoundError extends VersionNotFoundError_base {
+  get message(): string;
+}
+/**
+ * Version and dist-tag metadata for an npm package.
+ *
+ * @public
+ */
+interface PackageVersions {
+  /** Every published version string. */
+  readonly versions: ReadonlyArray<string>;
+  /** Dist-tags (`latest`, `next`, …) mapped to version strings. */
+  readonly tags: {
+    readonly [tag: string]: string;
+  };
+}
+/**
+ * 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
+ */
+declare const PackageManifest: Schema.Struct<{
+  readonly name: Schema.optionalKey<Schema.String>;
+  readonly version: Schema.optionalKey<Schema.String>;
+  readonly types: Schema.optionalKey<Schema.String>;
+  readonly typings: Schema.optionalKey<Schema.String>;
+  readonly main: Schema.optionalKey<Schema.String>;
+  readonly module: Schema.optionalKey<Schema.String>;
+  readonly exports: Schema.optionalKey<Schema.Union<readonly [Schema.String, Schema.$Record<Schema.String, Schema.Unknown>, Schema.$Array<Schema.Unknown>]>>;
+  readonly typesVersions: Schema.optionalKey<Schema.$Record<Schema.String, Schema.$Record<Schema.String, Schema.Union<readonly [Schema.$Array<Schema.String>, Schema.String]>>>>;
+  readonly dependencies: Schema.optionalKey<Schema.$Record<Schema.String, Schema.String>>;
+  readonly peerDependencies: Schema.optionalKey<Schema.$Record<Schema.String, Schema.String>>;
+  readonly devDependencies: Schema.optionalKey<Schema.$Record<Schema.String, Schema.String>>;
+}>;
+/**
+ * The decoded form of {@link (PackageManifest:variable)}.
+ *
+ * @public
+ */
+type PackageManifest = typeof PackageManifest.Type;
+/**
+ * The service shape {@link PackageFetcher} provides.
+ *
+ * @public
+ */
+interface PackageFetcherShape {
+  /** Fetch every published version and dist-tag for a package name. */
+  readonly getVersions: (name: string) => Effect.Effect<PackageVersions, FetchError>;
+  /** List the file paths a pinned package version publishes (leading `/` stripped). */
+  readonly getFileTree: (pkg: PackageSpec) => Effect.Effect<ReadonlyArray<string>, FetchError | PackageNotFoundError>;
+  /** Download one file's contents from the CDN. */
+  readonly downloadFile: (pkg: PackageSpec, path: string) => Effect.Effect<string, FetchError | PackageNotFoundError>;
+  /** Download and leniently decode a pinned version's `package.json`. */
+  readonly getPackageJson: (pkg: PackageSpec) => Effect.Effect<PackageManifest, FetchError | PackageNotFoundError>;
+  /**
+   * Download every declaration file a pinned version publishes, keyed by
+   * tree path.
+   *
+   * @remarks
+   * Concurrency 10, bounded by the materialization budget: more than the
+   * per-package file cap, or a cumulative body size past the byte cap, fails
+   * typed (`FetchError`, `kind: "body"`) rather than exhausting memory.
+   */
+  readonly getTypeFiles: (pkg: PackageSpec) => Effect.Effect<ReadonlyMap<string, string>, FetchError | PackageNotFoundError>;
+}
+declare const PackageFetcher_base: Context.ServiceClass<PackageFetcher, "type-registry-effect/PackageFetcher", PackageFetcherShape>;
+/**
+ * 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
+ */
+declare class PackageFetcher extends PackageFetcher_base {
+  /** The jsDelivr-backed layer; requires an `HttpClient`. */
+  static readonly layer: Layer.Layer<PackageFetcher, never, HttpClient.HttpClient>;
+}
+//#endregion
+//#region src/RegistryEvent.d.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
+ */
+declare const RegistryEvent: Schema.Union<readonly [Schema.TaggedStruct<"VersionResolved", {
+  readonly package: Schema.String;
+  readonly requested: Schema.String;
+  readonly resolved: Schema.String;
+}>, Schema.TaggedStruct<"VersionResolveFailed", {
+  readonly package: Schema.String;
+  readonly requested: Schema.String;
+  readonly kind: Schema.Literals<readonly ["not-found", "no-match", "network"]>;
+}>, Schema.TaggedStruct<"CacheHit", {
+  readonly package: Schema.String;
+  readonly version: Schema.String;
+  /** How long ago the entry was cached. */
+  readonly age: Schema.Duration;
+}>, Schema.TaggedStruct<"CacheStale", {
+  readonly package: Schema.String;
+  readonly version: Schema.String;
+}>, Schema.TaggedStruct<"CacheMiss", {
+  readonly package: Schema.String;
+  readonly version: Schema.String;
+}>, Schema.TaggedStruct<"FetchStart", {
+  readonly package: Schema.String;
+  readonly version: Schema.String;
+}>, Schema.TaggedStruct<"FetchFailed", {
+  readonly url: Schema.String;
+  readonly status: Schema.Number;
+  readonly bodySnippet: Schema.String;
+}>, Schema.TaggedStruct<"PackageLoaded", {
+  readonly package: Schema.String;
+  readonly version: Schema.String;
+  readonly files: Schema.Number;
+  readonly source: Schema.Literals<readonly ["cache", "network"]>;
+  readonly duration: Schema.Duration;
+}>, Schema.TaggedStruct<"PackageLoadFailed", {
+  readonly package: Schema.String;
+  readonly version: Schema.String;
+  readonly kind: Schema.Literals<readonly ["not-found", "version-range", "schema", "network", "cache", "unknown"]>;
+  /** The typed error itself, preserved structurally. */
+  readonly error: Schema.Defect;
+}>, Schema.TaggedStruct<"BatchStart", {
+  readonly total: Schema.Number;
+  readonly packages: Schema.$Array<Schema.String>;
+}>, Schema.TaggedStruct<"BatchComplete", {
+  readonly loaded: Schema.Number;
+  readonly failed: Schema.Number;
+  readonly total: Schema.Number;
+  readonly totalFiles: Schema.Number;
+  readonly duration: Schema.Duration;
+}>]>;
+/**
+ * The decoded form of {@link (RegistryEvent:variable)}: a tagged union the
+ * host narrows with `switch (event._tag)`.
+ *
+ * @public
+ */
+type RegistryEvent = typeof RegistryEvent.Type;
+/**
+ * The service shape {@link RegistryObserver} provides: a single `emit` the
+ * host implements.
+ *
+ * @public
+ */
+interface RegistryObserverShape {
+  /** Handle one {@link (RegistryEvent:type)}. */
+  readonly emit: (event: RegistryEvent) => Effect.Effect<void>;
+}
+declare const RegistryObserver_base: Context.ServiceClass<RegistryObserver, "type-registry-effect/RegistryObserver", RegistryObserverShape>;
+/**
+ * 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
+ */
+declare class RegistryObserver extends RegistryObserver_base {
+  /**
+   * 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: (event: RegistryEvent) => void): Layer.Layer<RegistryObserver>;
+  /**
+   * A no-op observer. Equivalent to providing nothing, but explicit — makes
+   * "events are intentionally dropped" visible in a composition.
+   */
+  static readonly layerNoop: Layer.Layer<RegistryObserver>;
+}
+//#endregion
+//#region src/Vfs.d.ts
+/**
+ * The package's currency type: a virtual file system mapping
+ * `node_modules/`-prefixed paths to file contents.
+ */
+/**
+ * A virtual file system: file paths (prefixed `node_modules/<package>/`)
+ * mapped to their string contents.
+ *
+ * @remarks
+ * This is the value every loading operation produces and every TypeScript
+ * integration consumes. Maps from multiple packages merge with {@link mergeVfs};
+ * `@typescript/vfs` consumes the merged map directly (see `TsEnvironment`).
+ *
+ * @public
+ */
+type Vfs = Map<string, string>;
+/**
+ * The v3 name for {@link Vfs}, kept as an alias for the consumer migration.
+ *
+ * @public
+ */
+type VirtualFileSystem = Vfs;
+/**
+ * Merge VFS maps left to right into a new map; later entries win on path
+ * collisions.
+ *
+ * @example
+ * ```ts
+ * import { mergeVfs } from "@tsdoctor/registry";
+ *
+ * const combined = mergeVfs(vfsA, vfsB);
+ * ```
+ *
+ * @public
+ */
+declare const mergeVfs: (...maps: ReadonlyArray<ReadonlyMap<string, string>>) => Vfs;
+/**
+ * Prefix every path in `entries` with `node_modules/<name>/`, normalizing
+ * away leading slashes.
+ *
+ * @public
+ */
+declare const prefixVfs: (name: string, entries: ReadonlyMap<string, string>) => Vfs;
+//#endregion
+//#region src/TsEnvironment.d.ts
+declare const TsEnvironmentError_base: Schema.Class<TsEnvironmentError, Schema.TaggedStruct<"TsEnvironmentError", {
+  /** The underlying failure, preserved structurally. */
+  readonly cause: Schema.Defect;
+}>, import("effect/Cause").YieldableError>;
+/**
+ * Raised when building a virtual TypeScript environment fails — including
+ * when the optional `typescript` / `@typescript/vfs` /
+ * `@effected/tsconfig-json` peers are not installed.
+ *
+ * @public
+ */
+declare class TsEnvironmentError extends TsEnvironmentError_base {
+  get message(): string;
+}
+/**
+ * Options for {@link TsEnvironment.make}.
+ *
+ * @public
+ */
+interface TsEnvironmentOptions {
+  /** The virtual file system to typecheck against. */
+  readonly vfs: Vfs;
+  /**
+   * Compiler options for the language service, in tsconfig JSON form
+   * (`{ target: "es2022" }`, not `ts.ScriptTarget.ES2022`). Enum-valued
+   * fields are converted to the compiler's numeric enums internally, so this
+   * type has no dependency on the `typescript` package.
+   */
+  readonly compilerOptions: CompilerOptions.Type;
+  /**
+   * The directory VFS paths are rooted under and the filesystem fallback
+   * root. Defaults to `process.cwd()` (which v3 hardcoded).
+   */
+  readonly projectRoot?: string;
+}
+/**
+ * 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
+ */
+declare class TsEnvironment {
+  private constructor();
+  /** Build a `VirtualTypeScriptEnvironment` over a {@link Vfs}. */
+  static make(options: TsEnvironmentOptions): Effect.Effect<VirtualTypeScriptEnvironment, TsEnvironmentError>;
+}
+//#endregion
+//#region src/TypeCache.d.ts
+declare const TypeCacheMetadata_base: Schema.Class<TypeCacheMetadata, Schema.Struct<{
+  /** The pinned version the files on disk belong to. */
+  readonly version: Schema.String;
+  /** When the package was cached. */
+  readonly cachedAt: Schema.DateTimeUtcFromString;
+  /** Time-to-live; absent = never expires. */
+  readonly ttl: Schema.optionalKey<Schema.DurationFromMillis>;
+}>, {}>;
+/**
+ * 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
+ */
+declare class TypeCacheMetadata extends TypeCacheMetadata_base {}
+declare const TypeCacheError_base: Schema.Class<TypeCacheError, Schema.TaggedStruct<"TypeCacheError", {
+  /** The cache operation that failed. */
+  readonly operation: Schema.Literals<readonly ["exists", "read", "write", "list", "readMetadata", "writeMetadata", "getVfs", "remove", "prune"]>;
+  /** The file path or metadata key involved. */
+  readonly path: Schema.String;
+  /** The underlying failure, preserved structurally. */
+  readonly cause: Schema.Defect;
+}>, import("effect/Cause").YieldableError>;
+/**
+ * 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
+ */
+declare class TypeCacheError extends TypeCacheError_base {
+  get message(): string;
+}
+/**
+ * Result of {@link TypeCacheShape.prune}: how many metadata entries were
+ * evicted and which packages they were.
+ *
+ * @public
+ */
+interface CachePruneResult {
+  /** How many expired metadata entries were removed. */
+  readonly count: number;
+  /** The packages whose cache directories were deleted. */
+  readonly removed: ReadonlyArray<{
+    readonly name: string;
+    readonly version: string;
+  }>;
+}
+/**
+ * The service shape {@link TypeCache} provides.
+ *
+ * @public
+ */
+interface TypeCacheShape {
+  /**
+   * Report whether the package's files exist on disk.
+   *
+   * @remarks
+   * A pure disk check — it does not consult metadata, so it distinguishes
+   * "files present" from "metadata live" (the stale-vs-miss ladder). Unlike
+   * v3, a filesystem failure surfaces as `TypeCacheError` instead of being
+   * laundered to `false`.
+   *
+   * "Files present" is trusted to mean "package complete" only because
+   * {@link TypeCacheShape.writePackage} promotes a staged tree atomically:
+   * the live directory appears only once every file is written, so a present
+   * directory is never a half-written one.
+   */
+  readonly exists: (pkg: PackageSpec) => Effect.Effect<boolean, TypeCacheError>;
+  /** Read one cached file's contents. */
+  readonly read: (pkg: PackageSpec, filePath: string) => Effect.Effect<string, TypeCacheError>;
+  /**
+   * Write one file into the package's cache directory.
+   *
+   * @remarks
+   * `filePath` is data from a CDN file tree: absolute paths and `..`
+   * segments are rejected as a typed `TypeCacheError` before any join — a
+   * hostile tree must not write outside `<cacheDir>/<name>/<version>/`.
+   *
+   * This is the low-level single-file primitive: it writes directly into the
+   * live directory and does not guard completeness.
+   * {@link TypeCacheShape.writePackage} is the atomic whole-package path the
+   * registry uses.
+   */
+  readonly write: (pkg: PackageSpec, filePath: string, content: string) => Effect.Effect<void, TypeCacheError>;
+  /**
+   * Write a package's entire file set atomically: stage every file in a
+   * sibling directory, then promote it onto the live directory in one
+   * `rename`.
+   *
+   * @remarks
+   * The invariant this method exists to hold: a reader either sees the
+   * package's previous complete state or its new complete state, never a
+   * half-written mixture. It works in three phases:
+   *
+   * 1. **Stage.** Files are written into a `.staging-<version>` directory that
+   *    is a *sibling* of the live `<cacheDir>/<name>/<version>/` dir (same
+   *    parent, so the final `rename` is same-filesystem and atomic). A
+   *    `.staging-*` sibling is invisible to reads, which operate on the live
+   *    directory specifically. Any leftover staging tree from a prior crash is
+   *    cleared first. Each `filePath` runs through the same path guard
+   *    {@link TypeCacheShape.write} uses (resolved against the staging root),
+   *    so a hostile tree cannot escape; a path-safety or IO failure here
+   *    aborts before promotion, leaving the live directory untouched.
+   * 2. **Promote.** The live directory is removed, then the staging directory
+   *    is renamed onto it. Because the whole directory is replaced rather than
+   *    merged, obsolete files from a previous, larger file set are dropped.
+   * 3. There is a tiny window between the remove and the rename where the live
+   *    directory is briefly absent. A concurrent reader that observes it there
+   *    classifies the package as a *miss* (via the stale-vs-miss ladder),
+   *    which self-heals on the next fetch — strictly better than observing a
+   *    partial tree and serving it as usable stale data.
+   *
+   * All failures map to a typed `TypeCacheError` with operation `"write"`.
+   */
+  readonly writePackage: (pkg: PackageSpec, files: Iterable<readonly [string, string]>) => Effect.Effect<void, TypeCacheError>;
+  /** List the package's cached files, relative to its cache directory. */
+  readonly listFiles: (pkg: PackageSpec) => Effect.Effect<ReadonlyArray<string>, TypeCacheError>;
+  /**
+   * Read the package's metadata entry.
+   *
+   * @remarks
+   * `Option.none()` when absent **or expired** — the store's TTL expiry
+   * evicts on read, which is what drives the stale-vs-miss distinction.
+   */
+  readonly readMetadata: (pkg: PackageSpec) => Effect.Effect<Option.Option<TypeCacheMetadata>, TypeCacheError>;
+  /** Write the package's metadata entry, forwarding its `ttl` to the store. */
+  readonly writeMetadata: (pkg: PackageSpec, metadata: TypeCacheMetadata) => Effect.Effect<void, TypeCacheError>;
+  /** Build the package's {@link Vfs}: every cached file keyed `node_modules/<name>/<path>`. */
+  readonly getVfs: (pkg: PackageSpec) => Effect.Effect<Vfs, TypeCacheError>;
+  /**
+   * Remove the package: metadata first, then files.
+   *
+   * @remarks
+   * The ordering is load-bearing. Files can outlive their metadata (TTL
+   * expiry evicts on read, leaving files behind), so the deletion cannot ride
+   * the store's transactional `onRemoved` callback — it only fires when a
+   * metadata row actually matched. Removing metadata first means a crash
+   * between the two steps leaves harmless orphaned files (a later refetch
+   * overwrites them), never a phantom cache hit.
+   */
+  readonly remove: (pkg: PackageSpec) => Effect.Effect<void, TypeCacheError>;
+  /**
+   * Evict every expired metadata entry and delete the corresponding
+   * directories.
+   *
+   * @remarks
+   * Deliberately best-effort, NOT transactional: file removals are side
+   * effects outside the SQL transaction, so a mid-loop rollback would
+   * restore all metadata while leaving earlier directories already deleted.
+   * Metadata is pruned first; per-directory removal failures are ignored (an
+   * orphaned directory is harmless — a later refetch overwrites it).
+   */
+  readonly prune: Effect.Effect<CachePruneResult, TypeCacheError>;
+}
+declare const TypeCache_base: Context.ServiceClass<TypeCache, "type-registry-effect/TypeCache", TypeCacheShape>;
+/**
+ * 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
+ */
+declare class TypeCache extends TypeCache_base {
+  /**
+   * 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: {
+    readonly cacheDir: string;
+  }): Layer.Layer<TypeCache, never, Cache | FileSystem.FileSystem | Path.Path>;
+  /**
+   * 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?: {
+    readonly namespace?: string;
+  }): Layer.Layer<TypeCache, AppDirsError, Cache | AppDirs | FileSystem.FileSystem | Path.Path>;
+}
+//#endregion
+//#region src/TypeResolver.d.ts
+declare const ResolvedModule_base: Schema.Class<ResolvedModule, Schema.Struct<{
+  /** The file path relative to the package root (no `./` prefix). */
+  readonly filePath: Schema.String;
+  /** Whether the path names a TypeScript declaration file. */
+  readonly isTypeDefinition: Schema.Boolean;
+  /** The package the path belongs to. */
+  readonly package: typeof PackageSpec;
+}>, {}>;
+/**
+ * A resolved module: the declaration file a specifier resolves to within a
+ * package.
+ *
+ * @public
+ */
+declare class ResolvedModule extends ResolvedModule_base {}
+/**
+ * Pure `package.json` → declaration-file resolution.
+ *
+ * @remarks
+ * Stateless pure functions — no service, no layer (v3's `Layer.succeed` over
+ * stateless functions was ceremony), and no fictional error channel: v3
+ * declared a `ResolutionError` its total implementation could never raise.
+ * Here {@link TypeResolver.resolveImport} is honest in the other direction
+ * too — it returns `Option.none()` where v3 fabricated a guessed fallback
+ * path, leaving fallback policy to the caller.
+ *
+ * All map inputs are untrusted CDN data; the machinery underneath is depth-
+ * guarded, wildcard-bounded and prototype-pollution-safe (see
+ * `internal/resolution.ts`), and every resolved path is validated to stay
+ * inside the package before a `ResolvedModule` is constructed.
+ *
+ * @public
+ */
+declare class TypeResolver {
+  private constructor();
+  /**
+   * Resolve an import specifier (`"zod"`, `"zod/lib/types"`) against a
+   * manifest.
+   *
+   * @remarks
+   * Resolution order: the `exports` map (`types` condition, then
+   * `import`/`default`, fallback arrays in order), then `typesVersions["*"]`
+   * (exact, then bounded wildcards), then — for the root specifier only —
+   * the top-level `types`/`typings` fields. `Option.none()` when the
+   * manifest offers no evidence for the subpath, or when the evidence names
+   * a path outside the package (hostile manifest — fails closed).
+   */
+  static resolveImport(specifier: string, manifest: PackageManifest, pkg: PackageSpec): Option.Option<ResolvedModule>;
+  /**
+   * Resolve the manifest's main type entry.
+   *
+   * @remarks
+   * Total by the documented `index.d.ts` convention floor: `types`/`typings`,
+   * then the root export's types condition, then a declaration-extension
+   * swap of `main`, then `index.d.ts`. A main path that escapes the package
+   * (hostile manifest) also falls to the floor rather than surviving.
+   */
+  static resolveMainEntry(manifest: PackageManifest, pkg: PackageSpec): ResolvedModule;
+  /**
+   * Enumerate every entry point that exposes type definitions: the main
+   * entry plus each `exports` subpath with a types-bearing condition,
+   * deduplicated by file path.
+   *
+   * @remarks
+   * Wildcard export keys (`"./*"`) are skipped: enumeration has no captured
+   * segment to substitute, so a pattern entry would emit a literal
+   * `dist/*.d.ts`. Pattern subpaths resolve through
+   * {@link TypeResolver.resolveImport}, which has the concrete specifier.
+   * Entries whose paths escape the package are skipped.
+   */
+  static resolveTypeEntries(manifest: PackageManifest, pkg: PackageSpec): ReadonlyArray<ResolvedModule>;
+  /**
+   * The conventional declaration-file path for a JavaScript file path
+   * (`lib/index.js` → `lib/index.d.ts`, `.mjs` → `.d.mts`, `.cjs` →
+   * `.d.cts`).
+   *
+   * @remarks
+   * The input is a tree path from the CDN — untrusted — so a path that is
+   * absolute or escapes the package yields `Option.none()` instead of a
+   * `ResolvedModule` that could reach a download URL.
+   */
+  static findTypeDefinition(jsFilePath: string, pkg: PackageSpec): Option.Option<ResolvedModule>;
+}
+//#endregion
+//#region src/TypeRegistry.d.ts
+declare const BatchLoadError_base: Schema.Class<BatchLoadError, Schema.TaggedStruct<"BatchLoadError", {
+  /** One entry per failed package, with its typed error preserved. */
+  readonly failures: Schema.$Array<Schema.Struct<{
+    readonly name: Schema.String;
+    readonly version: Schema.String;
+    readonly error: Schema.Defect;
+  }>>;
+}>, import("effect/Cause").YieldableError>;
+/**
+ * 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
+ */
+declare class BatchLoadError extends BatchLoadError_base {
+  get message(): string;
+}
+/**
+ * Options for {@link TypeRegistryShape.getPackageVfs} and
+ * {@link TypeRegistryShape.getVfs}.
+ *
+ * @public
+ */
+interface PackageVfsOptions {
+  /**
+   * Fetch from the CDN when the package is missing or stale. Defaults to
+   * `true`. With `false`, a stale entry is served from disk and a miss fails
+   * with `PackageNotFoundError`.
+   */
+  readonly autoFetch?: boolean;
+  /** Time-to-live recorded for newly cached entries; absent = never expires. */
+  readonly ttl?: Duration.Duration;
+}
+/**
+ * The service shape {@link TypeRegistry} provides.
+ *
+ * @public
+ */
+interface TypeRegistryShape {
+  /** Report whether the package's files are already on disk. */
+  readonly hasCached: (pkg: PackageSpec) => Effect.Effect<boolean, TypeCacheError>;
+  /** Fetch a pinned package's manifest and declaration files and cache them. */
+  readonly fetchAndCache: (pkg: PackageSpec, options?: {
+    readonly ttl?: Duration.Duration;
+  }) => Effect.Effect<void, FetchError | PackageNotFoundError | TypeCacheError>;
+  /**
+   * Build the {@link Vfs} for one package, fetching it first when missing or
+   * stale (the stale-vs-miss ladder: live metadata → hit; files on disk with
+   * no live metadata → stale, refetched when `autoFetch`, served as-is
+   * otherwise; nothing → miss, fetched or failed typed on
+   * `autoFetch: false`).
+   */
+  readonly getPackageVfs: (pkg: PackageSpec, options?: PackageVfsOptions) => Effect.Effect<Vfs, FetchError | PackageNotFoundError | TypeCacheError>;
+  /**
+   * Build a merged {@link Vfs} for several packages, best-effort.
+   *
+   * @remarks
+   * Loads concurrently (limit 5), accumulates per-package failures, merges
+   * the partial results, and fails — with a structured
+   * {@link BatchLoadError} — only when every package fails. An empty
+   * `packages` array is not an error: it yields an empty `Vfs`.
+   */
+  readonly getVfs: (packages: ReadonlyArray<PackageSpec>, options?: PackageVfsOptions) => Effect.Effect<Vfs, BatchLoadError>;
+  /**
+   * Resolve an import specifier against a cached package's manifest.
+   * `Option.none()` when the manifest offers no evidence for the subpath.
+   */
+  readonly resolveImport: (pkg: PackageSpec, specifier: string) => Effect.Effect<Option.Option<ResolvedModule>, TypeCacheError | FetchError>;
+  /** Enumerate a cached package's type entry points. */
+  readonly getTypeEntries: (pkg: PackageSpec) => Effect.Effect<ReadonlyArray<ResolvedModule>, TypeCacheError | FetchError>;
+  /**
+   * Resolve a version reference — dist-tag, exact version or semver range —
+   * to a pinned version string, locally.
+   *
+   * @remarks
+   * Dist-tags resolve through the CDN's tag map; exact versions match the
+   * published list; ranges resolve with `@effected/semver`
+   * (max-satisfying). No CDN `/resolve` endpoint, no error-prose parsing —
+   * an unmatched ref fails as a typed {@link VersionNotFoundError}.
+   */
+  readonly resolveVersion: (name: string, ref: string) => Effect.Effect<string, FetchError | VersionNotFoundError>;
+  /** Remove one package from the cache (metadata first, then files). */
+  readonly clearCache: (pkg: PackageSpec) => Effect.Effect<void, TypeCacheError>;
+  /** Evict every expired package from the cache. */
+  readonly pruneCache: Effect.Effect<CachePruneResult, TypeCacheError>;
+}
+declare const TypeRegistry_base: Context.ServiceClass<TypeRegistry, "type-registry-effect/TypeRegistry", TypeRegistryShape>;
+/**
+ * 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
+ */
+declare class TypeRegistry extends TypeRegistry_base {
+  /** The live facade over {@link TypeCache} and {@link PackageFetcher}. */
+  static readonly layer: Layer.Layer<TypeRegistry, never, TypeCache | PackageFetcher>;
+}
+//#endregion
+//#region src/VirtualPackage.d.ts
+declare const VirtualPackage_base: Schema.Class<VirtualPackage, Schema.Struct<{
+  /** The package name (e.g. `"@my-org/api-types"`). */
+  readonly name: Schema.String;
+  /** The package version. */
+  readonly version: Schema.String;
+  /** Entry file names (e.g. `"index.d.ts"`) mapped to declaration source. */
+  readonly entries: Schema.$ReadonlyMap<Schema.String, Schema.String>;
+}>, {}>;
+/**
+ * A synthetic npm package built from locally supplied TypeScript declaration
+ * content, for inclusion in a {@link Vfs} without fetching from the CDN.
+ *
+ * @remarks
+ * Useful when you have locally generated `.d.ts` files — API Extractor
+ * output, hand-written ambient declarations — and want them in the same VFS
+ * `TypeRegistry` builds from remote packages. Instances are transient: they
+ * are never persisted to the disk cache.
+ *
+ * The class is deliberately subclass-friendly (the rspress consumer extends
+ * it): construct via `VirtualPackage.make(...)` or the statics, and extend
+ * with `class Mine extends VirtualPackage { ... }`.
+ *
+ * @example
+ * ```ts
+ * import { VirtualPackage } from "@tsdoctor/registry";
+ *
+ * const pkg = VirtualPackage.create("@my-org/api-types", "1.0.0", "export interface User { id: string }");
+ * const vfs = pkg.toVfs();
+ * // node_modules/@my-org/api-types/package.json, node_modules/@my-org/api-types/index.d.ts
+ * ```
+ *
+ * @public
+ */
+declare class VirtualPackage extends VirtualPackage_base {
+  /**
+   * Single-entry factory: a virtual package whose sole entry point is
+   * `index.d.ts`.
+   */
+  static create(name: string, version: string, declarations: string): VirtualPackage;
+  /**
+   * Multi-entry factory: one `.d.ts` per entry point, exposed through a
+   * synthetic `exports` map.
+   *
+   * @remarks
+   * An empty entries map is developer wiring, not input — it would produce a
+   * package whose `types` points at a file that does not exist — so it
+   * throws at construction (defect posture), as does an entry set whose
+   * names collide after extension normalization (see
+   * {@link VirtualPackage.toVfs}).
+   */
+  static createMultiEntry(name: string, version: string, entries: ReadonlyMap<string, string>): VirtualPackage;
+  /**
+   * Load a single `.d.ts` file from disk as a virtual package with one
+   * `index.d.ts` entry.
+   *
+   * @remarks
+   * Reads through the platform-agnostic `FileSystem` service; the
+   * `PlatformError` surfaces typed.
+   */
+  static fromFile(name: string, version: string, filePath: string): Effect.Effect<VirtualPackage, PlatformError.PlatformError, FileSystem.FileSystem>;
+  /**
+   * The package's {@link Vfs}: a synthetic `package.json` plus every entry
+   * file, each path prefixed `node_modules/<name>/`.
+   *
+   * @remarks
+   * The `package.json` uses `types` for a single entry and an `exports` map
+   * for multiple entries, so TypeScript module resolution works against the
+   * generated VFS.
+   */
+  toVfs(): Vfs;
+  private toPackageJson;
+}
+//#endregion
+export { BatchLoadError, type CachePruneResult, FetchError, PackageFetcher, type PackageFetcherShape, PackageManifest, PackageNotFoundError, PackageSpec, type PackageVersions, type PackageVfsOptions, RegistryEvent, RegistryObserver, type RegistryObserverShape, ResolvedModule, TsEnvironment, TsEnvironmentError, type TsEnvironmentOptions, TypeCache, TypeCacheError, TypeCacheMetadata, type TypeCacheShape, TypeRegistry, type TypeRegistryShape, TypeResolver, VersionNotFoundError, type Vfs, type VirtualFileSystem, VirtualPackage, mergeVfs, prefixVfs };
+//# sourceMappingURL=index.d.ts.map