runtime-resolver 0.1.0 → 0.2.0

package/index.d.ts

@@ -1,10 +1,47 @@
 import { Context } from 'effect';
-import type { Effect } from 'effect';
+import { DateTime } from 'effect';
+import { Effect } from 'effect';
+import type { EmptyCacheError } from 'semver-effect';
 import { Equals } from 'effect/Types';
+import type { InvalidRangeError } from 'semver-effect';
+import type { InvalidVersionError } from 'semver-effect';
 import { Layer } from 'effect';
+import { Option } from 'effect';
+import { Ref } from 'effect';
 import { Schema } from 'effect';
+import { SemVer } from 'semver-effect';
+import type { UnsatisfiedRangeError } from 'semver-effect';
+import { VersionCache } from 'semver-effect';
 import { YieldableError } from 'effect/Cause';
 
+/**
+ * Raised when a GitHub authentication attempt fails.
+ *
+ * This error is produced by the {@link GitHubTokenAuth} and
+ * {@link GitHubAppAuth} layers when the supplied credentials are rejected by
+ * the GitHub API or when required configuration values (e.g. a token or app
+ * private key) are missing from the environment.
+ *
+ * @see {@link GitHubTokenAuth}
+ * @see {@link GitHubAppAuth}
+ *
+ * @example
+ * ```typescript
+ * import { Effect } from "effect";
+ * import type { AuthenticationError } from "./AuthenticationError.js";
+ * import { resolveNode } from "../resolvers/node.js";
+ *
+ * const program = resolveNode(">=20").pipe(
+ *   Effect.catchTag("AuthenticationError", (err: AuthenticationError) =>
+ *     Effect.logError(
+ *       `Auth failed via ${err.method}: ${err.message}`
+ *     ).pipe(Effect.andThen(Effect.fail(err)))
+ *   )
+ * );
+ * ```
+ *
+ * @public
+ */
 export declare class AuthenticationError extends AuthenticationErrorBase<{
     readonly method: "token" | "app";
     readonly message: string;
@@ -18,81 +55,478 @@ export declare class AuthenticationError extends AuthenticationErrorBase<{
  * `Data.TaggedError(...)`, TypeScript emits an un-nameable `_base` symbol in
  * the declaration file. Splitting the base into a named export gives the
  * bundler a stable reference.
+ *
+ * @privateRemarks
+ * This base constant must remain a named export so that api-extractor can
+ * resolve the extends clause of {@link AuthenticationError} to a stable
+ * declaration. Without it the bundled `.d.ts` would contain an anonymous
+ * `_base` symbol that cannot be referenced by downstream consumers.
  */
 export declare const AuthenticationErrorBase: new <A extends Record<string, any> = {}>(args: Equals<A, {}> extends true ? void : { readonly [P in keyof A as P extends "_tag" ? never : P]: A[P]; }) => YieldableError & {
     readonly _tag: "AuthenticationError";
 } & Readonly<A>;
 
 /**
- * Service interface for resolving Bun runtime versions.
+ * Provides the {@link BunReleaseCache} service using the "Auto" cache strategy.
+ *
+ * Attempts to fetch live release data from the GitHub API via
+ * {@link BunVersionFetcher}. If the fetch fails for any reason — authentication
+ * errors, network errors, parse errors, or rate-limit errors — it silently falls
+ * back to the bundled default release data so the layer always succeeds.
+ *
+ * Use this strategy when you want the freshest data when available but can
+ * tolerate slightly stale bundled data in degraded environments.
+ *
+ * The three Bun cache strategy layers are:
+ * - `AutoBunCacheLive` — tries API first, falls back to bundled defaults on any error
+ * - {@link FreshBunCacheLive} — requires live API data, fails with `FreshnessError` if unavailable
+ * - {@link OfflineBunCacheLive} — uses only bundled defaults, no network I/O
+ *
+ * @see {@link BunReleaseCache}
+ * @see {@link FreshBunCacheLive}
+ * @see {@link OfflineBunCacheLive}
+ * @public
+ */
+export declare const AutoBunCacheLive: Layer.Layer<BunReleaseCache, never, BunVersionFetcher>;
+
+/**
+ * Provides the {@link DenoReleaseCache} service using the "Auto" cache strategy.
+ *
+ * Attempts to fetch live release data from the GitHub API via
+ * {@link DenoVersionFetcher}. If the fetch fails for any reason — authentication
+ * errors, network errors, parse errors, or rate-limit errors — it silently falls
+ * back to the bundled default release data so the layer always succeeds.
+ *
+ * Use this strategy when you want the freshest data when available but can
+ * tolerate slightly stale bundled data in degraded environments.
+ *
+ * The three Deno cache strategy layers are:
+ * - `AutoDenoCacheLive` — tries API first, falls back to bundled defaults on any error
+ * - {@link FreshDenoCacheLive} — requires live API data, fails with `FreshnessError` if unavailable
+ * - {@link OfflineDenoCacheLive} — uses only bundled defaults, no network I/O
+ *
+ * @see {@link DenoReleaseCache}
+ * @see {@link FreshDenoCacheLive}
+ * @see {@link OfflineDenoCacheLive}
+ * @public
+ */
+export declare const AutoDenoCacheLive: Layer.Layer<DenoReleaseCache, never, DenoVersionFetcher>;
+
+/**
+ * Provides the {@link NodeReleaseCache} service using the "Auto" cache strategy.
+ *
+ * Attempts to fetch live release data from `nodejs.org/dist/index.json` via
+ * {@link NodeVersionFetcher} and the release schedule from the `nodejs/Release`
+ * repository via {@link NodeScheduleFetcher}. If either fetch fails — due to
+ * network errors or parse errors — the layer silently falls back to bundled
+ * default data (both version list and schedule) so it always succeeds.
+ *
+ * Node.js requires both a version fetcher and a schedule fetcher because LTS and
+ * maintenance phase information is tracked separately from the version index.
+ *
+ * The three Node cache strategy layers are:
+ * - `AutoNodeCacheLive` — tries API first, falls back to bundled defaults on any error
+ * - {@link FreshNodeCacheLive} — requires live API data, fails with `FreshnessError` if unavailable
+ * - {@link OfflineNodeCacheLive} — uses only bundled defaults, no network I/O
+ *
+ * @see {@link NodeReleaseCache}
+ * @see {@link FreshNodeCacheLive}
+ * @see {@link OfflineNodeCacheLive}
+ * @public
+ */
+export declare const AutoNodeCacheLive: Layer.Layer<NodeReleaseCache, never, NodeVersionFetcher | NodeScheduleFetcher>;
+
+/**
+ * A Bun release entry with a parsed {@link SemVer.SemVer} version and an
+ * Effect {@link DateTime.DateTime} publication date.
+ *
+ * `BunRelease` extends `Data.TaggedClass` so instances support structural
+ * equality comparison and can be used safely inside Effect data structures.
+ * Construct instances via the {@link BunRelease.fromInput} factory rather than
+ * calling `new BunRelease(...)` directly, as the factory validates the version
+ * string through `SemVer.fromString`.
+ *
+ * @see {@link BunReleaseCache}
+ * @see {@link BunResolver}
+ * @see {@link RuntimeReleaseInput}
+ *
+ * @example
+ * ```typescript
+ * import { Effect } from "effect";
+ * import type { BunRelease } from "./bun-release.js";
+ * import { BunRelease as BunReleaseClass } from "./bun-release.js";
+ *
+ * const program = BunReleaseClass.fromInput({ version: "1.1.0", date: "2024-03-01" }).pipe(
+ *   Effect.map((release: BunRelease) => {
+ *     console.log(release.version.major); // 1
+ *     console.log(release.version.minor); // 1
+ *     console.log(release._tag);          // "BunRelease"
+ *   }),
+ * );
+ *
+ * Effect.runPromise(program);
+ * ```
+ *
+ * @public
+ */
+export declare class BunRelease extends BunReleaseBase<{
+    readonly version: SemVer.SemVer;
+    readonly date: DateTime.DateTime;
+}> {
+    /**
+     * Create a {@link BunRelease} from lean string inputs.
+     *
+     * Parses `input.version` via `SemVer.fromString` and constructs the
+     * publication date with `DateTime.unsafeMake`. Falls back to the current
+     * timestamp when `input.date` is an empty string (rare in production data).
+     *
+     * @param input - A {@link RuntimeReleaseInput} object with raw string fields.
+     * @returns An `Effect` that succeeds with a `BunRelease` or fails with an
+     *   `InvalidVersionError` when the version string cannot be parsed.
+     */
+    static fromInput(input: RuntimeReleaseInput): Effect.Effect<BunRelease, InvalidVersionError>;
+}
+
+/**
+ * @internal
+ *
+ * Exported for declaration bundling (api-extractor). When `export *`
+ * re-exports a class whose `extends` expression is an inline call like
+ * `Data.TaggedClass(...)`, TypeScript emits an un-nameable `_base` symbol in
+ * the declaration file. Splitting the base into a named export gives the
+ * bundler a stable reference.
+ *
+ * @privateRemarks
+ * This base constant must remain a named export so that api-extractor can
+ * resolve the extends clause of {@link BunRelease} to a stable declaration.
+ * Without it the bundled `.d.ts` would contain an anonymous `_base` symbol
+ * that cannot be referenced by downstream consumers.
+ */
+export declare const BunReleaseBase: new <A extends Record<string, any> = {}>(args: Equals<A, {}> extends true ? void : { readonly [P in keyof A as P extends "_tag" ? never : P]: A[P]; }) => Readonly<A> & {
+    readonly _tag: "BunRelease";
+};
+
+/**
+ * Specialisation of {@link RuntimeCache} for Bun release objects.
+ *
+ * @see {@link BunRelease}
+ * @see {@link RuntimeCache}
+ * @see {@link AutoBunCacheLive}
+ * @see {@link FreshBunCacheLive}
+ * @see {@link OfflineBunCacheLive}
+ *
+ * @public
+ */
+export declare type BunReleaseCache = RuntimeCache<BunRelease>;
+
+/**
+ * Service tag and companion object for {@link BunReleaseCache}.
+ *
+ * Acts as both the TypeScript service interface (via the type alias above) and
+ * the Effect dependency tag used for dependency injection. Yield this tag
+ * inside `Effect.gen` to access the cache implementation provided by one of
+ * the cache layers.
+ *
+ * @example
+ * ```typescript
+ * import type { BunRelease } from "runtime-resolver";
+ * import { BunReleaseCache, OfflineBunCacheLive } from "runtime-resolver";
+ * import { Effect } from "effect";
+ *
+ * const program = Effect.gen(function* () {
+ * 	const cache = yield* BunReleaseCache;
+ * 	const releases = yield* cache.releases();
+ * 	console.log(releases.length);
+ * });
+ *
+ * Effect.runPromise(program.pipe(Effect.provide(OfflineBunCacheLive)));
+ * ```
+ *
+ * @see {@link AutoBunCacheLive}
+ * @see {@link FreshBunCacheLive}
+ * @see {@link OfflineBunCacheLive}
+ *
+ * @public
+ */
+export declare const BunReleaseCache: Context.Tag<BunReleaseCache, BunReleaseCache>;
+
+/**
+ * Low-level layer that constructs the {@link BunReleaseCache} service backed by
+ * a `SemVerVersionCache` instance from `semver-effect`.
+ *
+ * This layer wires up the cache storage but does not populate it with any
+ * release data. Callers are responsible for loading releases after construction.
+ * In normal usage you should prefer the higher-level cache strategy layers
+ * instead of using this layer directly:
+ * - {@link AutoBunCacheLive} — API with fallback to bundled defaults
+ * - {@link FreshBunCacheLive} — API only, fails if unavailable
+ * - {@link OfflineBunCacheLive} — bundled defaults only
+ *
+ * @see {@link BunReleaseCache}
+ * @see {@link createRuntimeCache}
+ * @internal
+ */
+export declare const BunReleaseCacheLive: Layer.Layer<BunReleaseCache, never, VersionCache>;
+
+/**
+ * Service interface for resolving Bun runtime versions against the cached
+ * release index.
+ *
+ * @see {@link BunResolverLive}
+ * @see {@link resolveBun}
+ * @see {@link BunResolverOptions}
+ * @see {@link ResolvedVersions}
+ *
+ * @public
  */
 export declare interface BunResolver {
+    /**
+     * Resolves Bun versions according to `options` and returns a
+     * {@link ResolvedVersions} object containing the matching version list,
+     * the latest version string, and the data source indicator.
+     *
+     * Fails with {@link BunResolverError} when no version can be resolved and
+     * no `defaultVersion` was provided.
+     *
+     * @param options - Optional resolution constraints.
+     *
+     * @see {@link BunResolverOptions}
+     */
     readonly resolve: (options?: BunResolverOptions) => Effect.Effect<ResolvedVersions, BunResolverError>;
-    readonly resolveVersion: (versionOrRange: string) => Effect.Effect<string, BunResolverError>;
 }
 
 /**
- * BunResolver tag for dependency injection.
+ * Service tag and companion object for {@link BunResolver}.
  *
- * @internal Uses GenericTag to avoid generating un-nameable `_base` types
- * that break the declaration bundler (api-extractor) when re-exported via
- * `export *`.
+ * Acts as both the TypeScript service interface and the Effect dependency tag
+ * used for dependency injection (companion object pattern). Yield this tag
+ * inside `Effect.gen` to obtain the resolver implementation provided by
+ * {@link BunResolverLive}.
+ *
+ * For a one-shot Promise-based API see {@link resolveBun}.
+ *
+ * @example
+ * ```typescript
+ * import type { ResolvedVersions } from "runtime-resolver";
+ * import { BunResolver, BunResolverLive } from "runtime-resolver";
+ * import { Effect } from "effect";
+ *
+ * const program = Effect.gen(function* () {
+ * 	const resolver = yield* BunResolver;
+ * 	const result = yield* resolver.resolve({ semverRange: "^1.0.0", increments: "minor" });
+ * 	console.log(result.latest);
+ * 	console.log(result.versions);
+ * });
+ *
+ * Effect.runPromise(program.pipe(Effect.provide(BunResolverLive)));
+ * ```
+ *
+ * @see {@link BunResolverLive}
+ * @see {@link resolveBun}
+ *
+ * @public
  */
 export declare const BunResolver: Context.Tag<BunResolver, BunResolver>;
 
-export declare type BunResolverError = AuthenticationError | NetworkError | ParseError | RateLimitError | VersionNotFoundError | InvalidInputError | FreshnessError | CacheError;
+/**
+ * Union of all typed errors that {@link BunResolver.resolve} can fail with.
+ *
+ * @see {@link VersionNotFoundError}
+ *
+ * @public
+ */
+export declare type BunResolverError = VersionNotFoundError;
 
-export declare const BunResolverLive: Layer.Layer<BunResolver, never, GitHubClient | VersionCache>;
+/**
+ * Provides the {@link BunResolver} service backed by a {@link BunReleaseCache}.
+ *
+ * This layer composes with any of the three Bun cache strategy layers to form
+ * a complete resolver stack. It implements semver range filtering and increment
+ * grouping (latest per major, latest per minor, or all patch versions) using
+ * the releases already loaded into the cache.
+ *
+ * @example
+ * ```ts
+ * import { BunResolverLive, AutoBunCacheLive, BunVersionFetcherLive, GitHubClientLive, GitHubAutoAuth } from "runtime-resolver";
+ * import type { ResolvedVersions } from "runtime-resolver";
+ * import { BunResolver } from "runtime-resolver";
+ * import { Effect, Layer } from "effect";
+ *
+ * const GitHubLayer = GitHubClientLive.pipe(Layer.provide(GitHubAutoAuth));
+ * const CacheLayer = AutoBunCacheLive.pipe(Layer.provide(BunVersionFetcherLive.pipe(Layer.provide(GitHubLayer))));
+ * const ResolverLayer = BunResolverLive.pipe(Layer.provide(CacheLayer));
+ *
+ * const program = Effect.gen(function* () {
+ *   const resolver = yield* BunResolver;
+ *   const result = yield* resolver.resolve({ semverRange: "^1.0.0" });
+ *   console.log(result.latest);
+ * });
+ *
+ * Effect.runPromise(program.pipe(Effect.provide(ResolverLayer)));
+ * ```
+ *
+ * @see {@link BunResolver}
+ * @see {@link BunReleaseCache}
+ * @see {@link AutoBunCacheLive}
+ * @see {@link FreshBunCacheLive}
+ * @see {@link OfflineBunCacheLive}
+ * @public
+ */
+export declare const BunResolverLive: Layer.Layer<BunResolver, never, BunReleaseCache>;
 
+/**
+ * Options accepted by {@link BunResolver.resolve}.
+ *
+ * All fields are optional; omitting them causes the resolver to fall back to
+ * its built-in defaults (latest stable release, `"latest"` increment
+ * granularity).
+ *
+ * @see {@link BunResolver}
+ * @see {@link Increments}
+ * @see {@link ResolvedVersions}
+ *
+ * @public
+ */
 export declare interface BunResolverOptions {
+    /**
+     * A semver range string used to constrain which Bun releases are
+     * considered (e.g. `"^1.0.0"` or `">=1.1.0 <2.0.0"`).
+     *
+     * When omitted all cached releases are eligible.
+     */
     readonly semverRange?: string;
+    /**
+     * A fallback version string returned when no release satisfies
+     * `semverRange`. Must be a valid semver version (e.g. `"1.0.0"`).
+     *
+     * When omitted and no match is found the effect fails with
+     * {@link VersionNotFoundError}.
+     */
     readonly defaultVersion?: string;
+    /**
+     * Controls the granularity of the version list included in
+     * {@link ResolvedVersions.versions}.
+     *
+     * - `"latest"` — only the single highest matching version.
+     * - `"minor"` — the latest patch for every minor line.
+     * - `"patch"` — every individual patch release.
+     *
+     * Defaults to `"latest"` when omitted.
+     *
+     * @see {@link Increments}
+     */
     readonly increments?: Increments;
-    readonly freshness?: Freshness;
 }
 
-export declare type CachedData = CachedNodeData | CachedTagData;
-
-export declare const CachedNodeData: Schema.Struct<{
-    versions: Schema.Array$<Schema.Struct<{
-        version: typeof Schema.String;
-        date: typeof Schema.String;
-        files: Schema.Array$<typeof Schema.String>;
-        npm: Schema.optional<typeof Schema.String>;
-        v8: Schema.optional<typeof Schema.String>;
-        uv: Schema.optional<typeof Schema.String>;
-        zlib: Schema.optional<typeof Schema.String>;
-        openssl: Schema.optional<typeof Schema.String>;
-        modules: Schema.optional<typeof Schema.String>;
-        lts: Schema.Union<[Schema.Literal<[false]>, typeof Schema.String]>;
-        security: typeof Schema.Boolean;
-    }>>;
-    schedule: Schema.Record$<typeof Schema.String, Schema.Struct<{
-        start: typeof Schema.String;
-        lts: Schema.optional<typeof Schema.String>;
-        maintenance: Schema.optional<typeof Schema.String>;
-        end: typeof Schema.String;
-        codename: Schema.optional<typeof Schema.String>;
-    }>>;
-}>;
+/**
+ * Service interface for fetching Bun release data from the GitHub API.
+ *
+ * Retrieves both the parsed semver version list and the raw release input
+ * records needed to populate a {@link BunReleaseCache}. The live
+ * implementation queries the `oven-sh/bun` GitHub repository via
+ * {@link GitHubClient}.
+ *
+ * @see {@link BunVersionFetcherLive}
+ * @see {@link BunReleaseCache}
+ * @see {@link AuthenticationError}
+ * @see {@link NetworkError}
+ * @see {@link ParseError}
+ * @see {@link RateLimitError}
+ *
+ * @public
+ */
+export declare interface BunVersionFetcher {
+    /**
+     * Fetches all available Bun releases from the GitHub API and returns both
+     * the parsed semver version objects and the raw release input records.
+     *
+     * Fails with:
+     * - {@link AuthenticationError} — missing or invalid GitHub credentials.
+     * - {@link NetworkError} — the upstream request could not be completed.
+     * - {@link ParseError} — the response payload could not be decoded.
+     * - {@link RateLimitError} — the GitHub API rate limit was exceeded.
+     */
+    readonly fetch: () => Effect.Effect<{
+        readonly versions: ReadonlyArray<SemVer.SemVer>;
+        readonly inputs: ReadonlyArray<RuntimeReleaseInput>;
+    }, AuthenticationError | NetworkError | ParseError | RateLimitError>;
+}
 
-export declare type CachedNodeData = typeof CachedNodeData.Type;
-
-export declare const CachedTagData: Schema.Struct<{
-    tags: Schema.Array$<Schema.Struct<{
-        name: typeof Schema.String;
-        zipball_url: typeof Schema.String;
-        tarball_url: typeof Schema.String;
-        commit: Schema.Struct<{
-            sha: typeof Schema.String;
-            url: typeof Schema.String;
-        }>;
-        node_id: typeof Schema.String;
-    }>>;
-}>;
+/**
+ * Service tag and companion object for {@link BunVersionFetcher}.
+ *
+ * Acts as both the TypeScript service interface and the Effect dependency tag
+ * used for dependency injection (companion object pattern). Yield this tag
+ * inside `Effect.gen` to access the fetcher implementation provided by
+ * {@link BunVersionFetcherLive}.
+ *
+ * @example
+ * ```typescript
+ * import type { RuntimeReleaseInput } from "runtime-resolver";
+ * import { BunVersionFetcher, BunVersionFetcherLive, GitHubAutoAuth } from "runtime-resolver";
+ * import { Effect } from "effect";
+ *
+ * const program = Effect.gen(function* () {
+ * 	const fetcher = yield* BunVersionFetcher;
+ * 	const { versions, inputs } = yield* fetcher.fetch();
+ * 	console.log(`Fetched ${versions.length} Bun releases`);
+ * });
+ *
+ * Effect.runPromise(
+ * 	program.pipe(Effect.provide(BunVersionFetcherLive), Effect.provide(GitHubAutoAuth)),
+ * );
+ * ```
+ *
+ * @see {@link BunVersionFetcherLive}
+ *
+ * @public
+ */
+export declare const BunVersionFetcher: Context.Tag<BunVersionFetcher, BunVersionFetcher>;
 
-export declare type CachedTagData = typeof CachedTagData.Type;
+/**
+ * Provides the {@link BunVersionFetcher} service using the live GitHub API.
+ *
+ * Fetches Bun releases from the `oven-sh/bun` GitHub repository using the
+ * provided {@link GitHubClient}. Draft releases and pre-releases are excluded.
+ * Tag names are normalized by stripping the `bun-` prefix and any leading `v`
+ * or `V` before parsing as semver.
+ *
+ * This layer is a required dependency of {@link AutoBunCacheLive} and
+ * {@link FreshBunCacheLive}. It is not needed by {@link OfflineBunCacheLive}.
+ *
+ * @see {@link BunVersionFetcher}
+ * @see {@link GitHubClient}
+ * @see {@link AutoBunCacheLive}
+ * @see {@link FreshBunCacheLive}
+ * @public
+ */
+export declare const BunVersionFetcherLive: Layer.Layer<BunVersionFetcher, never, GitHubClient>;
 
+/**
+ * Raised when a cache read or write operation fails.
+ *
+ * This error surfaces when the local on-disk version cache cannot be accessed
+ * or updated. The `operation` field distinguishes between failures that occur
+ * while loading cached data (`"read"`) and failures that occur while
+ * persisting new data (`"write"`).
+ *
+ * @example
+ * ```typescript
+ * import { Effect } from "effect";
+ * import type { CacheError } from "./CacheError.js";
+ * import { resolveNode } from "../resolvers/node.js";
+ *
+ * const program = resolveNode(">=20").pipe(
+ *   Effect.catchTag("CacheError", (err: CacheError) =>
+ *     Effect.logWarning(
+ *       `Cache ${err.operation} failed: ${err.message}`
+ *     ).pipe(Effect.andThen(Effect.fail(err)))
+ *   )
+ * );
+ * ```
+ *
+ * @public
+ */
 export declare class CacheError extends CacheErrorBase<{
     readonly operation: "read" | "write";
     readonly message: string;
@@ -102,41 +536,494 @@ export declare class CacheError extends CacheErrorBase<{
 /**
  * @internal
  * Exported for declaration bundling — see AuthenticationError.ts for details.
+ *
+ * @privateRemarks
+ * This base constant must remain a named export so that api-extractor can
+ * resolve the extends clause of {@link CacheError} to a stable declaration.
+ * Without it the bundled `.d.ts` would contain an anonymous `_base` symbol
+ * that cannot be referenced by downstream consumers.
  */
 export declare const CacheErrorBase: new <A extends Record<string, any> = {}>(args: Equals<A, {}> extends true ? void : { readonly [P in keyof A as P extends "_tag" ? never : P]: A[P]; }) => YieldableError & {
     readonly _tag: "CacheError";
 } & Readonly<A>;
 
 /**
- * Service interface for resolving Deno runtime versions.
+ * Factory that creates a {@link RuntimeCache} implementation backed by
+ * `semver-effect`'s `VersionCache`.
+ *
+ * The returned `Effect` must be executed within an Effect context that provides
+ * a `SemVerVersionCache` service (i.e., it requires `SemVerVersionCache` in its
+ * environment). The cache maintains an internal lookup map from version string
+ * to the full release object so that resolved semver versions can be
+ * round-tripped back to their typed release records.
+ *
+ * This factory is used internally by {@link BunReleaseCacheLive},
+ * {@link DenoReleaseCacheLive}, and {@link NodeReleaseCacheLive} to build their
+ * respective cache service implementations. Prefer those higher-level layers
+ * over calling this factory directly.
+ *
+ * Note: `load` is not concurrency-safe. Callers must not invoke it concurrently.
+ * In practice this constraint is upheld because `load` is only called from layer
+ * setup and `NodeReleaseCacheLive.loadFromInputs`, both of which are serialized
+ * by the Effect runtime.
+ *
+ * @typeParam R - The runtime release type stored in the cache. Must extend
+ *   {@link RuntimeRelease}.
+ *
+ * @see {@link RuntimeCache}
+ * @see {@link BunReleaseCacheLive}
+ * @see {@link DenoReleaseCacheLive}
+ * @see {@link NodeReleaseCacheLive}
+ * @public
+ */
+export declare const createRuntimeCache: <R extends RuntimeRelease>() => Effect.Effect<RuntimeCache<R>, never, VersionCache>;
+
+/**
+ * A Deno release entry with a parsed {@link SemVer.SemVer} version and an
+ * Effect {@link DateTime.DateTime} publication date.
+ *
+ * `DenoRelease` extends `Data.TaggedClass` so instances support structural
+ * equality comparison and can be used safely inside Effect data structures.
+ * Construct instances via the {@link DenoRelease.fromInput} factory rather than
+ * calling `new DenoRelease(...)` directly, as the factory validates the version
+ * string through `SemVer.fromString`.
+ *
+ * @see {@link DenoReleaseCache}
+ * @see {@link DenoResolver}
+ * @see {@link RuntimeReleaseInput}
+ *
+ * @example
+ * ```typescript
+ * import { Effect } from "effect";
+ * import type { DenoRelease } from "./deno-release.js";
+ * import { DenoRelease as DenoReleaseClass } from "./deno-release.js";
+ *
+ * const program = DenoReleaseClass.fromInput({ version: "1.44.0", date: "2024-05-23" }).pipe(
+ *   Effect.map((release: DenoRelease) => {
+ *     console.log(release.version.major); // 1
+ *     console.log(release.version.minor); // 44
+ *     console.log(release._tag);          // "DenoRelease"
+ *   }),
+ * );
+ *
+ * Effect.runPromise(program);
+ * ```
+ *
+ * @public
+ */
+export declare class DenoRelease extends DenoReleaseBase<{
+    readonly version: SemVer.SemVer;
+    readonly date: DateTime.DateTime;
+}> {
+    /**
+     * Create a {@link DenoRelease} from lean string inputs.
+     *
+     * Parses `input.version` via `SemVer.fromString` and constructs the
+     * publication date with `DateTime.unsafeMake`. Falls back to the current
+     * timestamp when `input.date` is an empty string (rare in production data).
+     *
+     * @param input - A {@link RuntimeReleaseInput} object with raw string fields.
+     * @returns An `Effect` that succeeds with a `DenoRelease` or fails with an
+     *   `InvalidVersionError` when the version string cannot be parsed.
+     */
+    static fromInput(input: RuntimeReleaseInput): Effect.Effect<DenoRelease, InvalidVersionError>;
+}
+
+/**
+ * @internal
+ *
+ * Exported for declaration bundling (api-extractor). When `export *`
+ * re-exports a class whose `extends` expression is an inline call like
+ * `Data.TaggedClass(...)`, TypeScript emits an un-nameable `_base` symbol in
+ * the declaration file. Splitting the base into a named export gives the
+ * bundler a stable reference.
+ *
+ * @privateRemarks
+ * This base constant must remain a named export so that api-extractor can
+ * resolve the extends clause of {@link DenoRelease} to a stable declaration.
+ * Without it the bundled `.d.ts` would contain an anonymous `_base` symbol
+ * that cannot be referenced by downstream consumers.
+ */
+export declare const DenoReleaseBase: new <A extends Record<string, any> = {}>(args: Equals<A, {}> extends true ? void : { readonly [P in keyof A as P extends "_tag" ? never : P]: A[P]; }) => Readonly<A> & {
+    readonly _tag: "DenoRelease";
+};
+
+/**
+ * Specialisation of {@link RuntimeCache} for Deno release objects.
+ *
+ * @see {@link DenoRelease}
+ * @see {@link RuntimeCache}
+ * @see {@link AutoDenoCacheLive}
+ * @see {@link FreshDenoCacheLive}
+ * @see {@link OfflineDenoCacheLive}
+ *
+ * @public
+ */
+export declare type DenoReleaseCache = RuntimeCache<DenoRelease>;
+
+/**
+ * Service tag and companion object for {@link DenoReleaseCache}.
+ *
+ * Acts as both the TypeScript service interface (via the type alias above) and
+ * the Effect dependency tag used for dependency injection. Yield this tag
+ * inside `Effect.gen` to access the cache implementation provided by one of
+ * the cache layers.
+ *
+ * @example
+ * ```typescript
+ * import type { DenoRelease } from "runtime-resolver";
+ * import { DenoReleaseCache, OfflineDenoCacheLive } from "runtime-resolver";
+ * import { Effect } from "effect";
+ *
+ * const program = Effect.gen(function* () {
+ * 	const cache = yield* DenoReleaseCache;
+ * 	const latest = yield* cache.latest();
+ * 	console.log(latest.version.toString());
+ * });
+ *
+ * Effect.runPromise(program.pipe(Effect.provide(OfflineDenoCacheLive)));
+ * ```
+ *
+ * @see {@link AutoDenoCacheLive}
+ * @see {@link FreshDenoCacheLive}
+ * @see {@link OfflineDenoCacheLive}
+ *
+ * @public
+ */
+export declare const DenoReleaseCache: Context.Tag<DenoReleaseCache, DenoReleaseCache>;
+
+/**
+ * Low-level layer that constructs the {@link DenoReleaseCache} service backed by
+ * a `SemVerVersionCache` instance from `semver-effect`.
+ *
+ * This layer wires up the cache storage but does not populate it with any
+ * release data. Callers are responsible for loading releases after construction.
+ * In normal usage you should prefer the higher-level cache strategy layers
+ * instead of using this layer directly:
+ * - {@link AutoDenoCacheLive} — API with fallback to bundled defaults
+ * - {@link FreshDenoCacheLive} — API only, fails if unavailable
+ * - {@link OfflineDenoCacheLive} — bundled defaults only
+ *
+ * @see {@link DenoReleaseCache}
+ * @see {@link createRuntimeCache}
+ * @internal
+ */
+export declare const DenoReleaseCacheLive: Layer.Layer<DenoReleaseCache, never, VersionCache>;
+
+/**
+ * Service interface for resolving Deno runtime versions against the cached
+ * release index.
+ *
+ * @see {@link DenoResolverLive}
+ * @see {@link resolveDeno}
+ * @see {@link DenoResolverOptions}
+ * @see {@link ResolvedVersions}
+ *
+ * @public
  */
 export declare interface DenoResolver {
+    /**
+     * Resolves Deno versions according to `options` and returns a
+     * {@link ResolvedVersions} object containing the matching version list,
+     * the latest version string, and the data source indicator.
+     *
+     * Fails with {@link DenoResolverError} when no version can be resolved and
+     * no `defaultVersion` was provided.
+     *
+     * @param options - Optional resolution constraints.
+     *
+     * @see {@link DenoResolverOptions}
+     */
     readonly resolve: (options?: DenoResolverOptions) => Effect.Effect<ResolvedVersions, DenoResolverError>;
-    readonly resolveVersion: (versionOrRange: string) => Effect.Effect<string, DenoResolverError>;
 }
 
 /**
- * @internal Uses GenericTag — see BunResolver.ts for rationale.
+ * Service tag and companion object for {@link DenoResolver}.
+ *
+ * Acts as both the TypeScript service interface and the Effect dependency tag
+ * used for dependency injection (companion object pattern). Yield this tag
+ * inside `Effect.gen` to obtain the resolver implementation provided by
+ * {@link DenoResolverLive}.
+ *
+ * For a one-shot Promise-based API see {@link resolveDeno}.
+ *
+ * @example
+ * ```typescript
+ * import type { ResolvedVersions } from "runtime-resolver";
+ * import { DenoResolver, DenoResolverLive } from "runtime-resolver";
+ * import { Effect } from "effect";
+ *
+ * const program = Effect.gen(function* () {
+ * 	const resolver = yield* DenoResolver;
+ * 	const result = yield* resolver.resolve({ semverRange: "^2.0.0", increments: "minor" });
+ * 	console.log(result.latest);
+ * 	console.log(result.versions);
+ * });
+ *
+ * Effect.runPromise(program.pipe(Effect.provide(DenoResolverLive)));
+ * ```
+ *
+ * @see {@link DenoResolverLive}
+ * @see {@link resolveDeno}
+ *
+ * @public
  */
 export declare const DenoResolver: Context.Tag<DenoResolver, DenoResolver>;
 
-export declare type DenoResolverError = AuthenticationError | NetworkError | ParseError | RateLimitError | VersionNotFoundError | InvalidInputError | FreshnessError | CacheError;
+/**
+ * Union of all typed errors that {@link DenoResolver.resolve} can fail with.
+ *
+ * @see {@link VersionNotFoundError}
+ *
+ * @public
+ */
+export declare type DenoResolverError = VersionNotFoundError;
 
-export declare const DenoResolverLive: Layer.Layer<DenoResolver, never, GitHubClient | VersionCache>;
+/**
+ * Provides the {@link DenoResolver} service backed by a {@link DenoReleaseCache}.
+ *
+ * This layer composes with any of the three Deno cache strategy layers to form
+ * a complete resolver stack. It implements semver range filtering and increment
+ * grouping (latest per major, latest per minor, or all patch versions) using
+ * the releases already loaded into the cache.
+ *
+ * @example
+ * ```ts
+ * import { DenoResolverLive, AutoDenoCacheLive, DenoVersionFetcherLive, GitHubClientLive, GitHubAutoAuth } from "runtime-resolver";
+ * import { DenoResolver } from "runtime-resolver";
+ * import { Effect, Layer } from "effect";
+ *
+ * const GitHubLayer = GitHubClientLive.pipe(Layer.provide(GitHubAutoAuth));
+ * const CacheLayer = AutoDenoCacheLive.pipe(Layer.provide(DenoVersionFetcherLive.pipe(Layer.provide(GitHubLayer))));
+ * const ResolverLayer = DenoResolverLive.pipe(Layer.provide(CacheLayer));
+ *
+ * const program = Effect.gen(function* () {
+ *   const resolver = yield* DenoResolver;
+ *   const result = yield* resolver.resolve({ semverRange: "^2.0.0" });
+ *   console.log(result.latest);
+ * });
+ *
+ * Effect.runPromise(program.pipe(Effect.provide(ResolverLayer)));
+ * ```
+ *
+ * @see {@link DenoResolver}
+ * @see {@link DenoReleaseCache}
+ * @see {@link AutoDenoCacheLive}
+ * @see {@link FreshDenoCacheLive}
+ * @see {@link OfflineDenoCacheLive}
+ * @public
+ */
+export declare const DenoResolverLive: Layer.Layer<DenoResolver, never, DenoReleaseCache>;
 
+/**
+ * Options accepted by {@link DenoResolver.resolve}.
+ *
+ * All fields are optional; omitting them causes the resolver to fall back to
+ * its built-in defaults (latest stable release, `"latest"` increment
+ * granularity).
+ *
+ * @see {@link DenoResolver}
+ * @see {@link Increments}
+ * @see {@link ResolvedVersions}
+ *
+ * @public
+ */
 export declare interface DenoResolverOptions {
+    /**
+     * A semver range string used to constrain which Deno releases are
+     * considered (e.g. `"^2.0.0"` or `">=1.40.0 <2.0.0"`).
+     *
+     * When omitted all cached releases are eligible.
+     */
     readonly semverRange?: string;
+    /**
+     * A fallback version string returned when no release satisfies
+     * `semverRange`. Must be a valid semver version (e.g. `"2.0.0"`).
+     *
+     * When omitted and no match is found the effect fails with
+     * {@link VersionNotFoundError}.
+     */
     readonly defaultVersion?: string;
+    /**
+     * Controls the granularity of the version list included in
+     * {@link ResolvedVersions.versions}.
+     *
+     * - `"latest"` — only the single highest matching version.
+     * - `"minor"` — the latest patch for every minor line.
+     * - `"patch"` — every individual patch release.
+     *
+     * Defaults to `"latest"` when omitted.
+     *
+     * @see {@link Increments}
+     */
     readonly increments?: Increments;
-    readonly freshness?: Freshness;
 }
 
-export declare const Freshness: Schema.Literal<["auto", "api", "cache"]>;
+/**
+ * Service interface for fetching Deno release data from the GitHub API.
+ *
+ * Retrieves both the parsed semver version list and the raw release input
+ * records needed to populate a {@link DenoReleaseCache}. The live
+ * implementation queries the `denoland/deno` GitHub repository via
+ * {@link GitHubClient}.
+ *
+ * @see {@link DenoVersionFetcherLive}
+ * @see {@link DenoReleaseCache}
+ * @see {@link AuthenticationError}
+ * @see {@link NetworkError}
+ * @see {@link ParseError}
+ * @see {@link RateLimitError}
+ *
+ * @public
+ */
+export declare interface DenoVersionFetcher {
+    /**
+     * Fetches all available Deno releases from the GitHub API and returns both
+     * the parsed semver version objects and the raw release input records.
+     *
+     * Fails with:
+     * - {@link AuthenticationError} — missing or invalid GitHub credentials.
+     * - {@link NetworkError} — the upstream request could not be completed.
+     * - {@link ParseError} — the response payload could not be decoded.
+     * - {@link RateLimitError} — the GitHub API rate limit was exceeded.
+     */
+    readonly fetch: () => Effect.Effect<{
+        readonly versions: ReadonlyArray<SemVer.SemVer>;
+        readonly inputs: ReadonlyArray<RuntimeReleaseInput>;
+    }, AuthenticationError | NetworkError | ParseError | RateLimitError>;
+}
 
-export declare type Freshness = typeof Freshness.Type;
+/**
+ * Service tag and companion object for {@link DenoVersionFetcher}.
+ *
+ * Acts as both the TypeScript service interface and the Effect dependency tag
+ * used for dependency injection (companion object pattern). Yield this tag
+ * inside `Effect.gen` to access the fetcher implementation provided by
+ * {@link DenoVersionFetcherLive}.
+ *
+ * @example
+ * ```typescript
+ * import type { RuntimeReleaseInput } from "runtime-resolver";
+ * import { DenoVersionFetcher, DenoVersionFetcherLive, GitHubAutoAuth } from "runtime-resolver";
+ * import { Effect } from "effect";
+ *
+ * const program = Effect.gen(function* () {
+ * 	const fetcher = yield* DenoVersionFetcher;
+ * 	const { versions, inputs } = yield* fetcher.fetch();
+ * 	console.log(`Fetched ${versions.length} Deno releases`);
+ * });
+ *
+ * Effect.runPromise(
+ * 	program.pipe(Effect.provide(DenoVersionFetcherLive), Effect.provide(GitHubAutoAuth)),
+ * );
+ * ```
+ *
+ * @see {@link DenoVersionFetcherLive}
+ *
+ * @public
+ */
+export declare const DenoVersionFetcher: Context.Tag<DenoVersionFetcher, DenoVersionFetcher>;
+
+/**
+ * Provides the {@link DenoVersionFetcher} service using the live GitHub API.
+ *
+ * Fetches Deno releases from the `denoland/deno` GitHub repository using the
+ * provided {@link GitHubClient}. Draft releases and pre-releases are excluded.
+ * Tag names are normalized by stripping any leading `v` before parsing as
+ * semver.
+ *
+ * This layer is a required dependency of {@link AutoDenoCacheLive} and
+ * {@link FreshDenoCacheLive}. It is not needed by {@link OfflineDenoCacheLive}.
+ *
+ * @see {@link DenoVersionFetcher}
+ * @see {@link GitHubClient}
+ * @see {@link AutoDenoCacheLive}
+ * @see {@link FreshDenoCacheLive}
+ * @public
+ */
+export declare const DenoVersionFetcherLive: Layer.Layer<DenoVersionFetcher, never, GitHubClient>;
+
+/**
+ * Provides the {@link BunReleaseCache} service using the "Fresh" cache strategy.
+ *
+ * Requires live release data from the GitHub API via {@link BunVersionFetcher}.
+ * If the fetch fails for any reason — authentication errors, network errors,
+ * parse errors, or rate-limit errors — the layer fails with a `FreshnessError`
+ * rather than falling back to stale data.
+ *
+ * Use this strategy in contexts where working with outdated version data would
+ * be incorrect or misleading, such as CI pipelines or tooling that must reflect
+ * the true current state of Bun releases.
+ *
+ * The three Bun cache strategy layers are:
+ * - {@link AutoBunCacheLive} — tries API first, falls back to bundled defaults on any error
+ * - `FreshBunCacheLive` — requires live API data, fails with `FreshnessError` if unavailable
+ * - {@link OfflineBunCacheLive} — uses only bundled defaults, no network I/O
+ *
+ * @see {@link BunReleaseCache}
+ * @see {@link AutoBunCacheLive}
+ * @see {@link OfflineBunCacheLive}
+ * @public
+ */
+export declare const FreshBunCacheLive: Layer.Layer<BunReleaseCache, FreshnessError, BunVersionFetcher>;
 
+/**
+ * Provides the {@link DenoReleaseCache} service using the "Fresh" cache strategy.
+ *
+ * Requires live release data from the GitHub API via {@link DenoVersionFetcher}.
+ * If the fetch fails for any reason — authentication errors, network errors,
+ * parse errors, or rate-limit errors — the layer fails with a `FreshnessError`
+ * rather than falling back to stale data.
+ *
+ * Use this strategy in contexts where working with outdated version data would
+ * be incorrect or misleading, such as CI pipelines or tooling that must reflect
+ * the true current state of Deno releases.
+ *
+ * The three Deno cache strategy layers are:
+ * - {@link AutoDenoCacheLive} — tries API first, falls back to bundled defaults on any error
+ * - `FreshDenoCacheLive` — requires live API data, fails with `FreshnessError` if unavailable
+ * - {@link OfflineDenoCacheLive} — uses only bundled defaults, no network I/O
+ *
+ * @see {@link DenoReleaseCache}
+ * @see {@link AutoDenoCacheLive}
+ * @see {@link OfflineDenoCacheLive}
+ * @public
+ */
+export declare const FreshDenoCacheLive: Layer.Layer<DenoReleaseCache, FreshnessError, DenoVersionFetcher>;
+
+/**
+ * Raised when a cache freshness check cannot be completed.
+ *
+ * Each runtime cache layer ({@link FreshBunCacheLive}, {@link FreshDenoCacheLive},
+ * {@link FreshNodeCacheLive}) validates whether locally stored version data is
+ * still current before returning it. This error is produced when that
+ * validation fails — for example, when the upstream API is unreachable during
+ * an `"api"` freshness check, or when the cached timestamp is corrupt during
+ * an `"auto"` or `"cache"` check.
+ *
+ * @see {@link FreshBunCacheLive}
+ * @see {@link FreshDenoCacheLive}
+ * @see {@link FreshNodeCacheLive}
+ *
+ * @example
+ * ```typescript
+ * import { Effect } from "effect";
+ * import type { FreshnessError } from "./FreshnessError.js";
+ * import { resolveNode } from "../resolvers/node.js";
+ *
+ * const program = resolveNode(">=20").pipe(
+ *   Effect.catchTag("FreshnessError", (err: FreshnessError) =>
+ *     Effect.logWarning(
+ *       `Freshness check (${err.strategy}) failed: ${err.message}`
+ *     ).pipe(Effect.andThen(Effect.fail(err)))
+ *   )
+ * );
+ * ```
+ *
+ * @public
+ */
 export declare class FreshnessError extends FreshnessErrorBase<{
-    readonly strategy: Freshness;
+    readonly strategy: "auto" | "api" | "cache";
     readonly message: string;
 }> {
 }
@@ -144,39 +1031,250 @@ export declare class FreshnessError extends FreshnessErrorBase<{
 /**
  * @internal
  * Exported for declaration bundling — see AuthenticationError.ts for details.
+ *
+ * @privateRemarks
+ * This base constant must remain a named export so that api-extractor can
+ * resolve the extends clause of {@link FreshnessError} to a stable declaration.
+ * Without it the bundled `.d.ts` would contain an anonymous `_base` symbol
+ * that cannot be referenced by downstream consumers.
  */
 export declare const FreshnessErrorBase: new <A extends Record<string, any> = {}>(args: Equals<A, {}> extends true ? void : { readonly [P in keyof A as P extends "_tag" ? never : P]: A[P]; }) => YieldableError & {
     readonly _tag: "FreshnessError";
 } & Readonly<A>;
 
+/**
+ * Provides the {@link NodeReleaseCache} service using the "Fresh" cache strategy.
+ *
+ * Requires live release data from `nodejs.org/dist/index.json` via
+ * {@link NodeVersionFetcher} and the release schedule from the `nodejs/Release`
+ * repository via {@link NodeScheduleFetcher}. If either fetch fails — due to
+ * network errors or parse errors — the layer fails with a `FreshnessError`
+ * rather than falling back to stale data.
+ *
+ * Use this strategy in contexts where working with outdated version data would
+ * be incorrect or misleading, such as CI pipelines or tooling that must reflect
+ * the true current state of Node.js releases and LTS schedule.
+ *
+ * The three Node cache strategy layers are:
+ * - {@link AutoNodeCacheLive} — tries API first, falls back to bundled defaults on any error
+ * - `FreshNodeCacheLive` — requires live API data, fails with `FreshnessError` if unavailable
+ * - {@link OfflineNodeCacheLive} — uses only bundled defaults, no network I/O
+ *
+ * @see {@link NodeReleaseCache}
+ * @see {@link AutoNodeCacheLive}
+ * @see {@link OfflineNodeCacheLive}
+ * @public
+ */
+export declare const FreshNodeCacheLive: Layer.Layer<NodeReleaseCache, FreshnessError, NodeVersionFetcher | NodeScheduleFetcher>;
+
+/**
+ * Provides an {@link OctokitInstance} authenticated as a GitHub App installation.
+ *
+ * Accepts a {@link GitHubAppAuthConfig} and uses `@octokit/auth-app` to obtain
+ * an installation access token. If `installationId` is omitted, the first
+ * installation returned by the GitHub API is used automatically (suitable for
+ * apps with a single installation). If authentication fails for any reason the
+ * layer fails with an `AuthenticationError`.
+ *
+ * Use this auth method when your integration runs as a GitHub App rather than
+ * as an individual user or a CI token.
+ *
+ * @param config - App credentials and optional installation ID.
+ *
+ * @see {@link GitHubAppAuthConfig}
+ * @see {@link OctokitInstance}
+ * @see {@link GitHubAutoAuth}
+ * @see {@link GitHubTokenAuth}
+ * @public
+ */
 export declare const GitHubAppAuth: (config: GitHubAppAuthConfig) => Layer.Layer<OctokitInstance, AuthenticationError, never>;
 
+/**
+ * Configuration required to authenticate as a GitHub App installation.
+ *
+ * @see {@link GitHubAppAuth}
+ * @public
+ */
 export declare interface GitHubAppAuthConfig {
     readonly appId: string;
     readonly privateKey: string;
     readonly installationId?: number;
 }
 
+/**
+ * Provides an {@link OctokitInstance} by auto-detecting the available
+ * authentication credentials from environment variables at layer construction
+ * time.
+ *
+ * Credentials are evaluated in the following priority order:
+ * 1. **GitHub App** — when both `GITHUB_APP_ID` and `GITHUB_APP_PRIVATE_KEY`
+ *    are set, authenticates as a GitHub App installation via {@link GitHubAppAuth}.
+ *    `GITHUB_APP_INSTALLATION_ID` is optional; if absent the first installation
+ *    is used automatically.
+ * 2. **Personal Access Token** — when `GITHUB_PERSONAL_ACCESS_TOKEN` is set,
+ *    authenticates with that token.
+ * 3. **`GITHUB_TOKEN`** — when `GITHUB_TOKEN` is set (e.g., the default token
+ *    injected in GitHub Actions), authenticates with that token.
+ * 4. **Unauthenticated** — falls back to an unauthenticated Octokit instance
+ *    when no credentials are found (lower rate limits apply).
+ *
+ * If both App and token credentials are present, App auth takes precedence and
+ * a warning is logged. This layer fails with `AuthenticationError` only when
+ * App credentials are present but the App authentication itself fails.
+ *
+ * Use this layer as the default auth strategy in most applications. Switch to
+ * {@link GitHubTokenAuth} or {@link GitHubAppAuth} when you need explicit control
+ * over which credential source is used.
+ *
+ * @example
+ * ```ts
+ * import { GitHubClientLive, GitHubAutoAuth } from "runtime-resolver";
+ * import { Layer } from "effect";
+ *
+ * const GitHubLayer = GitHubClientLive.pipe(Layer.provide(GitHubAutoAuth));
+ * ```
+ *
+ * @see {@link OctokitInstance}
+ * @see {@link GitHubTokenAuth}
+ * @see {@link GitHubAppAuth}
+ * @public
+ */
 export declare const GitHubAutoAuth: Layer.Layer<OctokitInstance, AuthenticationError>;
 
 /**
- * Service interface for GitHub API operations.
+ * Service interface for GitHub REST API operations used by the version
+ * fetcher services.
+ *
+ * Abstracts over pagination and authentication so that higher-level services
+ * such as {@link BunVersionFetcher}, {@link DenoVersionFetcher}, and
+ * {@link NodeScheduleFetcher} remain independent of the underlying HTTP
+ * transport. The live implementation is provided by {@link GitHubClientLive}
+ * and requires an {@link OctokitInstance} in its dependency graph.
+ *
+ * @see {@link GitHubClientLive}
+ * @see {@link OctokitInstance}
+ * @see {@link ListOptions}
+ *
+ * @public
  */
 export declare interface GitHubClient {
+    /**
+     * Lists all git tags for the given repository, automatically paginating
+     * through results according to `options`.
+     *
+     * Fails with:
+     * - {@link AuthenticationError} — missing or invalid GitHub credentials.
+     * - {@link NetworkError} — the upstream request could not be completed.
+     * - {@link RateLimitError} — the GitHub API rate limit was exceeded.
+     * - {@link ParseError} — a response page could not be decoded.
+     *
+     * @param owner - GitHub organisation or user name (e.g. `"oven-sh"`).
+     * @param repo - Repository name (e.g. `"bun"`).
+     * @param options - Optional pagination controls.
+     */
     readonly listTags: (owner: string, repo: string, options?: ListOptions) => Effect.Effect<ReadonlyArray<GitHubTag>, AuthenticationError | NetworkError | RateLimitError | ParseError>;
+    /**
+     * Lists all GitHub Releases for the given repository, automatically
+     * paginating through results according to `options`.
+     *
+     * Fails with:
+     * - {@link AuthenticationError} — missing or invalid GitHub credentials.
+     * - {@link NetworkError} — the upstream request could not be completed.
+     * - {@link RateLimitError} — the GitHub API rate limit was exceeded.
+     * - {@link ParseError} — a response page could not be decoded.
+     *
+     * @param owner - GitHub organisation or user name (e.g. `"denoland"`).
+     * @param repo - Repository name (e.g. `"deno"`).
+     * @param options - Optional pagination controls.
+     */
     readonly listReleases: (owner: string, repo: string, options?: ListOptions) => Effect.Effect<ReadonlyArray<GitHubRelease>, AuthenticationError | NetworkError | RateLimitError | ParseError>;
+    /**
+     * Fetches arbitrary JSON from `url` and decodes it with the provided
+     * schema, returning the typed result.
+     *
+     * Useful for endpoints outside the standard Octokit REST methods (e.g.
+     * raw GitHub content URLs).
+     *
+     * Fails with:
+     * - {@link NetworkError} — the upstream request could not be completed.
+     * - {@link ParseError} — the response body could not be decoded by `schema`.
+     *
+     * @typeParam A - The decoded output type produced by `schema`.
+     * @param url - Fully qualified URL to fetch.
+     * @param schema - An object with a `decode` method compatible with
+     * Effect Schema's `decodeUnknown`.
+     */
     readonly getJson: <A>(url: string, schema: {
         readonly decode: (input: unknown) => Effect.Effect<A, ParseError>;
     }) => Effect.Effect<A, NetworkError | ParseError>;
 }
 
 /**
- * @internal Uses GenericTag — see BunResolver.ts for rationale.
+ * Service tag and companion object for {@link GitHubClient}.
+ *
+ * Acts as both the TypeScript service interface and the Effect dependency tag
+ * used for dependency injection (companion object pattern). Yield this tag
+ * inside `Effect.gen` to access the client implementation provided by
+ * {@link GitHubClientLive}.
+ *
+ * @example
+ * ```typescript
+ * import type { GitHubTag } from "runtime-resolver";
+ * import { GitHubClient, GitHubClientLive, GitHubAutoAuth } from "runtime-resolver";
+ * import { Effect } from "effect";
+ *
+ * const program = Effect.gen(function* () {
+ * 	const client = yield* GitHubClient;
+ * 	const tags = yield* client.listTags("oven-sh", "bun", { perPage: 100 });
+ * 	console.log(`Found ${tags.length} tags`);
+ * });
+ *
+ * Effect.runPromise(
+ * 	program.pipe(Effect.provide(GitHubClientLive), Effect.provide(GitHubAutoAuth)),
+ * );
+ * ```
+ *
+ * @see {@link GitHubClientLive}
+ * @see {@link OctokitInstance}
+ *
+ * @public
  */
 export declare const GitHubClient: Context.Tag<GitHubClient, GitHubClient>;
 
+/**
+ * Provides the {@link GitHubClient} service backed by an {@link OctokitInstance}.
+ *
+ * This layer wraps an Octokit instance and exposes a typed, Effect-native API
+ * for listing GitHub releases, listing tags, and fetching arbitrary JSON from
+ * URLs. HTTP errors are mapped to typed domain errors (`NetworkError`,
+ * `RateLimitError`, `AuthenticationError`) so they can be handled precisely in
+ * calling code.
+ *
+ * Pair this layer with one of the auth layers to form a complete GitHub
+ * integration stack:
+ * - {@link GitHubAutoAuth} — auto-detects auth from environment variables
+ * - {@link GitHubTokenAuth} — authenticates using a personal access token
+ * - {@link GitHubAppAuth} — authenticates as a GitHub App installation
+ *
+ * @see {@link GitHubClient}
+ * @see {@link OctokitInstance}
+ * @see {@link GitHubAutoAuth}
+ * @public
+ */
 export declare const GitHubClientLive: Layer.Layer<GitHubClient, never, OctokitInstance>;
 
+/**
+ * A single release entry as returned by the GitHub REST API
+ * (`GET /repos/{owner}/{repo}/releases`).
+ *
+ * Consumed by {@link GitHubClient} when fetching Deno releases that carry
+ * publication timestamps.
+ *
+ * @see {@link GitHubClient}
+ * @see {@link GitHubReleaseList}
+ *
+ * @public
+ */
 export declare const GitHubRelease: Schema.Struct<{
     tag_name: typeof Schema.String;
     name: Schema.NullOr<typeof Schema.String>;
@@ -185,8 +1283,26 @@ export declare const GitHubRelease: Schema.Struct<{
     published_at: Schema.NullOr<typeof Schema.String>;
 }>;
 
+/**
+ * A single release entry as returned by the GitHub REST API.
+ *
+ * @see {@link GitHubClient}
+ *
+ * @public
+ */
 export declare type GitHubRelease = typeof GitHubRelease.Type;
 
+/**
+ * A single tag entry as returned by the GitHub REST API
+ * (`GET /repos/{owner}/{repo}/tags`).
+ *
+ * Consumed by {@link GitHubClient} when fetching Bun and Deno release tags.
+ *
+ * @see {@link GitHubClient}
+ * @see {@link GitHubTagList}
+ *
+ * @public
+ */
 export declare const GitHubTag: Schema.Struct<{
     name: typeof Schema.String;
     zipball_url: typeof Schema.String;
@@ -198,87 +1314,972 @@ export declare const GitHubTag: Schema.Struct<{
     node_id: typeof Schema.String;
 }>;
 
+/**
+ * A single tag entry as returned by the GitHub REST API.
+ *
+ * @see {@link GitHubClient}
+ *
+ * @public
+ */
 export declare type GitHubTag = typeof GitHubTag.Type;
 
-export declare const GitHubTokenAuth: Layer.Layer<OctokitInstance>;
+/**
+ * Provides an {@link OctokitInstance} authenticated with a GitHub personal
+ * access token read from the environment at layer construction time.
+ *
+ * The token is resolved by checking, in order:
+ * 1. `GITHUB_PERSONAL_ACCESS_TOKEN` environment variable
+ * 2. `GITHUB_TOKEN` environment variable
+ *
+ * If neither variable is set the layer constructs an unauthenticated Octokit
+ * instance (lower rate limits apply). This layer never fails.
+ *
+ * Use {@link GitHubTokenAuthFromToken} when you have the token value available
+ * programmatically at construction time.
+ *
+ * @see {@link OctokitInstance}
+ * @see {@link GitHubTokenAuthFromToken}
+ * @see {@link GitHubAutoAuth}
+ * @see {@link GitHubAppAuth}
+ * @public
+ */
+export declare const GitHubTokenAuth: Layer.Layer<OctokitInstance>;
+
+/**
+ * Provides an {@link OctokitInstance} authenticated with the given personal
+ * access token string.
+ *
+ * Use this variant when the token is available as a value in your program
+ * rather than read from an environment variable. The resulting layer never
+ * fails.
+ *
+ * @param token - A GitHub personal access token string.
+ *
+ * @see {@link OctokitInstance}
+ * @see {@link GitHubTokenAuth}
+ * @see {@link GitHubAutoAuth}
+ * @see {@link GitHubAppAuth}
+ * @public
+ */
+export declare const GitHubTokenAuthFromToken: (token: string) => Layer.Layer<OctokitInstance, never, never>;
+
+/**
+ * Controls the granularity at which matching versions are grouped when a
+ * resolver returns multiple results.
+ *
+ * - `"latest"` — return only the single highest matching version.
+ * - `"minor"` — return the latest patch for every minor line.
+ * - `"patch"` — return every individual patch release.
+ *
+ * @public
+ */
+export declare const Increments: Schema.Literal<["latest", "minor", "patch"]>;
+
+/**
+ * Controls the granularity at which matching versions are grouped.
+ *
+ * @public
+ */
+export declare type Increments = typeof Increments.Type;
+
+/**
+ * Raised when a caller-supplied value fails validation.
+ *
+ * This error is produced at the boundary where user-provided inputs (such as
+ * version constraint strings or runtime identifiers) are decoded against their
+ * expected schemas. The `field` identifies which input was invalid, `value`
+ * carries the raw string that was rejected, and `message` explains the
+ * specific violation.
+ *
+ * @example
+ * ```typescript
+ * import { Effect } from "effect";
+ * import type { InvalidInputError } from "./InvalidInputError.js";
+ * import { resolveNode } from "../resolvers/node.js";
+ *
+ * const program = resolveNode("not-a-semver-range").pipe(
+ *   Effect.catchTag("InvalidInputError", (err: InvalidInputError) =>
+ *     Effect.logError(
+ *       `Invalid value for "${err.field}": ${err.value} — ${err.message}`
+ *     ).pipe(Effect.andThen(Effect.fail(err)))
+ *   )
+ * );
+ * ```
+ *
+ * @public
+ */
+export declare class InvalidInputError extends InvalidInputErrorBase<{
+    readonly field: string;
+    readonly value: string;
+    readonly message: string;
+}> {
+}
+
+/**
+ * @internal
+ * Exported for declaration bundling — see AuthenticationError.ts for details.
+ *
+ * @privateRemarks
+ * This base constant must remain a named export so that api-extractor can
+ * resolve the extends clause of {@link InvalidInputError} to a stable
+ * declaration. Without it the bundled `.d.ts` would contain an anonymous
+ * `_base` symbol that cannot be referenced by downstream consumers.
+ */
+export declare const InvalidInputErrorBase: new <A extends Record<string, any> = {}>(args: Equals<A, {}> extends true ? void : { readonly [P in keyof A as P extends "_tag" ? never : P]: A[P]; }) => YieldableError & {
+    readonly _tag: "InvalidInputError";
+} & Readonly<A>;
+
+/**
+ * Pagination options shared by all list operations on {@link GitHubClient}.
+ *
+ * @see {@link GitHubClient}
+ *
+ * @public
+ */
+export declare interface ListOptions {
+    /**
+     * Number of items to request per page. Defaults to the GitHub API maximum
+     * of `100` when omitted.
+     */
+    readonly perPage?: number;
+    /**
+     * Maximum number of pages to fetch. When omitted all pages are fetched
+     * until the API returns an empty result set.
+     */
+    readonly pages?: number;
+}
+
+/**
+ * Raised when an HTTP request to an upstream API fails.
+ *
+ * This error is produced when a fetch to a runtime release API (e.g. the
+ * Node.js release index, the Deno release feed, or the Bun GitHub releases
+ * endpoint) either does not receive a response or receives a non-successful
+ * HTTP status code. When a status code is available it is included in the
+ * `status` field; for connection-level failures (timeouts, DNS errors) that
+ * field is absent.
+ *
+ * @example
+ * ```typescript
+ * import { Effect } from "effect";
+ * import type { NetworkError } from "./NetworkError.js";
+ * import { resolveNode } from "../resolvers/node.js";
+ *
+ * const program = resolveNode(">=20").pipe(
+ *   Effect.catchTag("NetworkError", (err: NetworkError) =>
+ *     Effect.logError(
+ *       `Request to ${err.url} failed${err.status != null ? ` with status ${err.status}` : ""}: ${err.message}`
+ *     ).pipe(Effect.andThen(Effect.fail(err)))
+ *   )
+ * );
+ * ```
+ *
+ * @public
+ */
+export declare class NetworkError extends NetworkErrorBase<{
+    readonly url: string;
+    readonly status?: number;
+    readonly message: string;
+}> {
+}
+
+/**
+ * @internal
+ * Exported for declaration bundling — see AuthenticationError.ts for details.
+ *
+ * @privateRemarks
+ * This base constant must remain a named export so that api-extractor can
+ * resolve the extends clause of {@link NetworkError} to a stable declaration.
+ * Without it the bundled `.d.ts` would contain an anonymous `_base` symbol
+ * that cannot be referenced by downstream consumers.
+ */
+export declare const NetworkErrorBase: new <A extends Record<string, any> = {}>(args: Equals<A, {}> extends true ? void : { readonly [P in keyof A as P extends "_tag" ? never : P]: A[P]; }) => YieldableError & {
+    readonly _tag: "NetworkError";
+} & Readonly<A>;
+
+/**
+ * Lifecycle phase of a Node.js major release line, derived from the official
+ * Node.js release schedule.
+ *
+ * - `"current"` — actively receiving features and bug fixes.
+ * - `"active-lts"` — Long-Term Support; stable, receiving only bug and
+ *   security fixes.
+ * - `"maintenance-lts"` — critical security fixes only.
+ * - `"end-of-life"` — no longer maintained.
+ *
+ * @see {@link NodeRelease.phase}
+ *
+ * @public
+ */
+export declare const NodePhase: Schema.Literal<["current", "active-lts", "maintenance-lts", "end-of-life"]>;
+
+/**
+ * Lifecycle phase of a Node.js major release line.
+ *
+ * @see {@link NodeRelease.phase}
+ *
+ * @public
+ */
+export declare type NodePhase = typeof NodePhase.Type;
+
+/**
+ * A Node.js release entry with parsed version, bundled npm version,
+ * publication date, and a shared reference to the Node.js release schedule.
+ *
+ * `NodeRelease` is a plain class rather than a `Data.TaggedClass` because it
+ * holds a `Ref<NodeSchedule>` — mutable Effect references break structural
+ * equality semantics, making `Data.TaggedClass` unsuitable here. The
+ * `_tag` field is set manually to preserve tagged-union compatibility.
+ *
+ * Use {@link NodeRelease.fromInput} to construct instances; call
+ * {@link NodeRelease.phase} or {@link NodeRelease.lts} to query the lifecycle
+ * state of the release at a given point in time.
+ *
+ * @see {@link NodeReleaseCache}
+ * @see {@link NodeResolver}
+ * @see {@link NodeSchedule}
+ *
+ * @example
+ * ```typescript
+ * import { Effect, Ref } from "effect";
+ * import type { NodePhase } from "./common.js";
+ * import type { NodeRelease } from "./node-release.js";
+ * import { NodeRelease as NodeReleaseClass } from "./node-release.js";
+ * import { NodeSchedule } from "./node-schedule.js";
+ *
+ * const program = Effect.gen(function* () {
+ *   const schedule = NodeSchedule.fromData({
+ *     v20: { start: "2023-04-18", lts: "2023-10-24", end: "2026-04-30" },
+ *   });
+ *   const scheduleRef = yield* Ref.make(schedule);
+ *
+ *   const release: NodeRelease = yield* NodeReleaseClass.fromInput(
+ *     { version: "v20.0.0", npm: "9.6.4", date: "2023-04-18" },
+ *     scheduleRef,
+ *   );
+ *
+ *   const phase: NodePhase | null = yield* release.phase();
+ *   const isLts: boolean = yield* release.lts();
+ *   console.log(phase);  // e.g. "active-lts"
+ *   console.log(isLts);  // true
+ * });
+ *
+ * Effect.runPromise(program);
+ * ```
+ *
+ * @public
+ */
+export declare class NodeRelease {
+    readonly version: SemVer.SemVer;
+    readonly npm: SemVer.SemVer;
+    readonly date: DateTime.DateTime;
+    readonly scheduleRef: Ref.Ref<NodeSchedule>;
+    readonly _tag: "NodeRelease";
+    constructor(version: SemVer.SemVer, npm: SemVer.SemVer, date: DateTime.DateTime, scheduleRef: Ref.Ref<NodeSchedule>);
+    /**
+     * Determine this release's lifecycle phase at the given point in time.
+     *
+     * Reads the current value of the shared `scheduleRef` and delegates to
+     * {@link NodeSchedule.phaseFor}. Defaults to the current wall-clock time
+     * when `now` is omitted.
+     *
+     * @param now - Optional reference time; defaults to `new Date()`.
+     * @returns An `Effect` that resolves to a {@link NodePhase} string, or
+     *   `null` when the major version is not present in the schedule or has
+     *   not yet been released.
+     */
+    phase(now?: DateTime.DateTime): Effect.Effect<NodePhase | null>;
+    /**
+     * Whether this release is currently in Long-Term Support.
+     *
+     * Returns `true` for both `"active-lts"` and `"maintenance-lts"` phases.
+     * Defaults to the current wall-clock time when `now` is omitted.
+     *
+     * @param now - Optional reference time; defaults to `new Date()`.
+     */
+    lts(now?: DateTime.DateTime): Effect.Effect<boolean>;
+    /**
+     * Create a {@link NodeRelease} from lean string inputs.
+     *
+     * Parses `input.version` and `input.npm` via `SemVer.fromString` and
+     * constructs the publication date with `DateTime.unsafeMake`.
+     *
+     * @param input - A {@link NodeReleaseInput} object with raw string fields.
+     * @param scheduleRef - A shared `Ref<NodeSchedule>` injected by the cache layer.
+     * @returns An `Effect` that succeeds with a `NodeRelease` or fails with an
+     *   `InvalidVersionError` when either version string cannot be parsed.
+     */
+    static fromInput(input: NodeReleaseInput, scheduleRef: Ref.Ref<NodeSchedule>): Effect.Effect<NodeRelease, InvalidVersionError>;
+}
+
+/**
+ * Node.js-specific cache service that extends {@link RuntimeCache} with
+ * additional operations for lifecycle schedule data and LTS / current
+ * release filtering.
+ *
+ * Unlike the Bun and Deno equivalents this interface is not a plain type alias
+ * — it adds four Node-specific methods on top of the generic cache contract.
+ *
+ * @see {@link NodeRelease}
+ * @see {@link NodeScheduleData}
+ * @see {@link RuntimeCache}
+ * @see {@link AutoNodeCacheLive}
+ * @see {@link FreshNodeCacheLive}
+ * @see {@link OfflineNodeCacheLive}
+ *
+ * @example
+ * ```typescript
+ * import type { NodeRelease } from "runtime-resolver";
+ * import { NodeReleaseCache, OfflineNodeCacheLive } from "runtime-resolver";
+ * import { Effect } from "effect";
+ *
+ * const program = Effect.gen(function* () {
+ * 	const cache = yield* NodeReleaseCache;
+ * 	const lts = yield* cache.ltsReleases();
+ * 	for (const release of lts) {
+ * 		console.log(release.version.toString(), release.phase);
+ * 	}
+ * });
+ *
+ * Effect.runPromise(program.pipe(Effect.provide(OfflineNodeCacheLive)));
+ * ```
+ *
+ * @public
+ */
+export declare interface NodeReleaseCache extends RuntimeCache<NodeRelease> {
+    /**
+     * Merges Node.js release-schedule data into the cache, updating lifecycle
+     * phase information (LTS dates, end-of-life dates, etc.) for every major
+     * release line.
+     *
+     * @param data - Parsed schedule payload, typically fetched via
+     * {@link NodeScheduleFetcher}.
+     *
+     * @see {@link NodeScheduleData}
+     */
+    readonly updateSchedule: (data: NodeScheduleData) => Effect.Effect<void>;
+    /**
+     * Populates the cache from raw {@link NodeReleaseInput} records (as
+     * returned by the Node.js release index JSON) rather than from already-
+     * decoded {@link NodeRelease} objects.
+     *
+     * Prefer this over `load` when consuming data directly from the Node.js
+     * distribution server.
+     *
+     * @param inputs - An array of un-decoded release index entries.
+     *
+     * @see {@link NodeReleaseInput}
+     */
+    readonly loadFromInputs: (inputs: ReadonlyArray<NodeReleaseInput>) => Effect.Effect<void>;
+    /**
+     * Returns all cached releases whose lifecycle phase is `"active-lts"` or
+     * `"maintenance-lts"` as of the given point in time.
+     *
+     * When `now` is omitted the current wall-clock time is used.
+     *
+     * @param now - Optional reference timestamp for phase evaluation.
+     *
+     * @see {@link NodeRelease}
+     */
+    readonly ltsReleases: (now?: DateTime.DateTime) => Effect.Effect<ReadonlyArray<NodeRelease>>;
+    /**
+     * Returns all cached releases whose lifecycle phase is `"current"` as of
+     * the given point in time.
+     *
+     * When `now` is omitted the current wall-clock time is used.
+     *
+     * @param now - Optional reference timestamp for phase evaluation.
+     *
+     * @see {@link NodeRelease}
+     */
+    readonly currentReleases: (now?: DateTime.DateTime) => Effect.Effect<ReadonlyArray<NodeRelease>>;
+}
+
+/**
+ * Service tag and companion object for {@link NodeReleaseCache}.
+ *
+ * Acts as both the TypeScript service interface and the Effect dependency tag
+ * used for dependency injection (companion object pattern). Yield this tag
+ * inside `Effect.gen` to access the cache implementation supplied by one of
+ * the Node cache layers.
+ *
+ * @see {@link AutoNodeCacheLive}
+ * @see {@link FreshNodeCacheLive}
+ * @see {@link OfflineNodeCacheLive}
+ *
+ * @public
+ */
+export declare const NodeReleaseCache: Context.Tag<NodeReleaseCache, NodeReleaseCache>;
+
+/**
+ * Low-level layer that constructs the {@link NodeReleaseCache} service backed by
+ * a `SemVerVersionCache` instance from `semver-effect`.
+ *
+ * This layer is more complex than the Bun and Deno equivalents because it manages
+ * additional LTS schedule state via an internal `Ref`. The schedule is stored
+ * separately from the version list so that calling `updateSchedule` can
+ * transparently rebuild all release objects with the latest phase information
+ * without reloading data from the network.
+ *
+ * This layer wires up the cache storage but does not populate it with any
+ * release data. Callers are responsible for calling `updateSchedule` and
+ * `loadFromInputs` after construction. In normal usage you should prefer the
+ * higher-level cache strategy layers instead of using this layer directly:
+ * - {@link AutoNodeCacheLive} — API with fallback to bundled defaults
+ * - {@link FreshNodeCacheLive} — API only, fails if unavailable
+ * - {@link OfflineNodeCacheLive} — bundled defaults only
+ *
+ * @see {@link NodeReleaseCache}
+ * @see {@link createRuntimeCache}
+ * @internal
+ */
+export declare const NodeReleaseCacheLive: Layer.Layer<NodeReleaseCache, never, VersionCache>;
+
+/**
+ * Lean input schema used to construct {@link NodeRelease} instances from
+ * bundled default data files and the Node.js dist API response.
+ *
+ * The `version` and `npm` fields are raw version strings validated by
+ * `SemVer.fromString`; `date` is a date string accepted by
+ * `DateTime.unsafeMake`.
+ *
+ * @see {@link NodeRelease.fromInput}
+ * @see {@link NodeVersionFetcher}
+ *
+ * @public
+ */
+export declare const NodeReleaseInput: Schema.Struct<{
+    version: typeof Schema.String;
+    npm: typeof Schema.String;
+    date: typeof Schema.String;
+}>;
+
+/**
+ * Lean input type used to construct {@link NodeRelease} instances.
+ *
+ * @see {@link NodeRelease.fromInput}
+ *
+ * @public
+ */
+export declare type NodeReleaseInput = typeof NodeReleaseInput.Type;
+
+/**
+ * Service interface for resolving Node.js runtime versions against the cached
+ * release index.
+ *
+ * Unlike {@link BunResolver} and {@link DenoResolver}, this service is
+ * lifecycle-aware: results can be filtered by {@link NodePhase} and evaluated
+ * against a specific reference date.
+ *
+ * @see {@link NodeResolverLive}
+ * @see {@link resolveNode}
+ * @see {@link NodeResolverOptions}
+ * @see {@link ResolvedVersions}
+ *
+ * @public
+ */
+export declare interface NodeResolver {
+    /**
+     * Resolves Node.js versions according to `options` and returns a
+     * {@link ResolvedVersions} object containing the matching version list,
+     * the latest version string, optional LTS version string, and the data
+     * source indicator.
+     *
+     * Fails with {@link NodeResolverError} when no version can be resolved and
+     * no `defaultVersion` was provided.
+     *
+     * @param options - Optional resolution constraints.
+     *
+     * @see {@link NodeResolverOptions}
+     */
+    readonly resolve: (options?: NodeResolverOptions) => Effect.Effect<ResolvedVersions, NodeResolverError>;
+}
+
+/**
+ * Service tag and companion object for {@link NodeResolver}.
+ *
+ * Acts as both the TypeScript service interface and the Effect dependency tag
+ * used for dependency injection (companion object pattern). Yield this tag
+ * inside `Effect.gen` to obtain the resolver implementation provided by
+ * {@link NodeResolverLive}.
+ *
+ * For a one-shot Promise-based API see {@link resolveNode}.
+ *
+ * @example
+ * ```typescript
+ * import type { ResolvedVersions } from "runtime-resolver";
+ * import { NodeResolver, NodeResolverLive } from "runtime-resolver";
+ * import { Effect } from "effect";
+ *
+ * const program = Effect.gen(function* () {
+ * 	const resolver = yield* NodeResolver;
+ * 	const result = yield* resolver.resolve({
+ * 		semverRange: "^20.0.0",
+ * 		phases: ["active-lts"],
+ * 		increments: "minor",
+ * 	});
+ * 	console.log(result.latest);
+ * 	console.log(result.lts);
+ * });
+ *
+ * Effect.runPromise(program.pipe(Effect.provide(NodeResolverLive)));
+ * ```
+ *
+ * @see {@link NodeResolverLive}
+ * @see {@link resolveNode}
+ *
+ * @public
+ */
+export declare const NodeResolver: Context.Tag<NodeResolver, NodeResolver>;
 
-export declare const GitHubTokenAuthFromToken: (token: string) => Layer.Layer<OctokitInstance, never, never>;
+/**
+ * Union of all typed errors that {@link NodeResolver.resolve} can fail with.
+ *
+ * @see {@link VersionNotFoundError}
+ *
+ * @public
+ */
+export declare type NodeResolverError = VersionNotFoundError;
 
-export declare const Increments: Schema.Literal<["latest", "minor", "patch"]>;
+/**
+ * Provides the {@link NodeResolver} service backed by a {@link NodeReleaseCache}.
+ *
+ * This layer composes with any of the three Node cache strategy layers to form
+ * a complete resolver stack. In addition to semver range filtering and increment
+ * grouping, it supports filtering by Node.js release phase (e.g., `"current"`,
+ * `"active-lts"`, `"maintenance-lts"`, `"end-of-life"`) and automatically
+ * determines the current LTS version from the loaded schedule data.
+ *
+ * @example
+ * ```ts
+ * import {
+ *   NodeResolverLive, AutoNodeCacheLive,
+ *   NodeVersionFetcherLive, NodeScheduleFetcherLive,
+ *   GitHubClientLive, GitHubAutoAuth,
+ * } from "runtime-resolver";
+ * import { NodeResolver } from "runtime-resolver";
+ * import { Effect, Layer } from "effect";
+ *
+ * const GitHubLayer = GitHubClientLive.pipe(Layer.provide(GitHubAutoAuth));
+ * const FetchersLayer = Layer.merge(
+ *   NodeVersionFetcherLive.pipe(Layer.provide(GitHubLayer)),
+ *   NodeScheduleFetcherLive.pipe(Layer.provide(GitHubLayer)),
+ * );
+ * const CacheLayer = AutoNodeCacheLive.pipe(Layer.provide(FetchersLayer));
+ * const ResolverLayer = NodeResolverLive.pipe(Layer.provide(CacheLayer));
+ *
+ * const program = Effect.gen(function* () {
+ *   const resolver = yield* NodeResolver;
+ *   // Resolve only active-LTS and maintenance-LTS releases in the ^20 range
+ *   const result = yield* resolver.resolve({
+ *     semverRange: "^20.0.0",
+ *     phases: ["active-lts", "maintenance-lts"],
+ *   });
+ *   console.log(result.lts);
+ * });
+ *
+ * Effect.runPromise(program.pipe(Effect.provide(ResolverLayer)));
+ * ```
+ *
+ * @see {@link NodeResolver}
+ * @see {@link NodeReleaseCache}
+ * @see {@link AutoNodeCacheLive}
+ * @see {@link FreshNodeCacheLive}
+ * @see {@link OfflineNodeCacheLive}
+ * @public
+ */
+export declare const NodeResolverLive: Layer.Layer<NodeResolver, never, NodeReleaseCache>;
 
-export declare type Increments = typeof Increments.Type;
+/**
+ * Options accepted by {@link NodeResolver.resolve}.
+ *
+ * All fields are optional; omitting them causes the resolver to fall back to
+ * its built-in defaults (all lifecycle phases, latest stable release,
+ * `"latest"` increment granularity, current wall-clock date).
+ *
+ * @see {@link NodeResolver}
+ * @see {@link NodePhase}
+ * @see {@link Increments}
+ * @see {@link ResolvedVersions}
+ *
+ * @public
+ */
+export declare interface NodeResolverOptions {
+    /**
+     * A semver range string used to constrain which Node.js releases are
+     * considered (e.g. `"^20.0.0"` or `">=18.0.0 <22.0.0"`).
+     *
+     * When omitted all cached releases are eligible.
+     */
+    readonly semverRange?: string;
+    /**
+     * A fallback version string returned when no release satisfies
+     * `semverRange`. Must be a valid semver version (e.g. `"20.0.0"`).
+     *
+     * When omitted and no match is found the effect fails with
+     * {@link VersionNotFoundError}.
+     */
+    readonly defaultVersion?: string;
+    /**
+     * Restricts resolution to releases whose lifecycle phase is included in
+     * this list. For example, passing `["active-lts"]` excludes `"current"`
+     * and `"maintenance-lts"` releases from consideration.
+     *
+     * When omitted all phases are eligible.
+     *
+     * @see {@link NodePhase}
+     */
+    readonly phases?: ReadonlyArray<NodePhase>;
+    /**
+     * Controls the granularity of the version list included in
+     * {@link ResolvedVersions.versions}.
+     *
+     * - `"latest"` — only the single highest matching version.
+     * - `"minor"` — the latest patch for every minor line.
+     * - `"patch"` — every individual patch release.
+     *
+     * Defaults to `"latest"` when omitted.
+     *
+     * @see {@link Increments}
+     */
+    readonly increments?: Increments;
+    /**
+     * Reference date used when evaluating Node.js lifecycle phases. Releases
+     * whose LTS or end-of-life boundaries fall relative to this date are
+     * classified accordingly.
+     *
+     * When omitted the current wall-clock date is used.
+     */
+    readonly date?: Date;
+}
 
-export declare class InvalidInputError extends InvalidInputErrorBase<{
-    readonly field: string;
-    readonly value: string;
-    readonly message: string;
+/**
+ * Immutable snapshot of the Node.js release schedule.
+ *
+ * Holds a `ReadonlyArray<NodeScheduleEntry>` parsed from the raw
+ * {@link NodeScheduleData} fetched by {@link NodeScheduleFetcher}. A single
+ * `NodeSchedule` instance lives inside a `Ref<NodeSchedule>` that is shared
+ * across all {@link NodeRelease} instances so that schedule updates propagate
+ * without rebuilding the release cache.
+ *
+ * `NodeSchedule` extends `Data.TaggedClass` and therefore supports structural
+ * equality — two schedules built from identical data compare as equal.
+ *
+ * @see {@link NodeRelease}
+ * @see {@link NodeScheduleFetcher}
+ *
+ * @example
+ * ```typescript
+ * import { Effect } from "effect";
+ * import type { NodePhase } from "./common.js";
+ * import type { NodeScheduleData } from "./node-schedule.js";
+ * import { NodeSchedule } from "./node-schedule.js";
+ *
+ * const data: NodeScheduleData = {
+ *   v20: {
+ *     start: "2023-04-18",
+ *     lts: "2023-10-24",
+ *     maintenance: "2024-10-22",
+ *     end: "2026-04-30",
+ *     codename: "Iron",
+ *   },
+ * };
+ *
+ * const schedule = NodeSchedule.fromData(data);
+ *
+ * const program = schedule.phaseFor(20, new Date("2024-01-01") as any).pipe(
+ *   Effect.map((phase: NodePhase | null) => {
+ *     console.log(phase); // "active-lts"
+ *   }),
+ * );
+ *
+ * Effect.runPromise(program);
+ * ```
+ *
+ * @public
+ */
+export declare class NodeSchedule extends NodeScheduleBase<{
+    readonly entries: ReadonlyArray<NodeScheduleEntry>;
 }> {
+    /**
+     * Parse raw {@link NodeScheduleData} into a `NodeSchedule` instance.
+     *
+     * Iterates over every key of the form `"vNN"`, converts ISO date strings
+     * to `DateTime.DateTime`, and normalises missing codenames to `""`.
+     *
+     * @param data - The raw JSON object fetched from the Node.js release repo.
+     * @returns A fully constructed, immutable `NodeSchedule`.
+     */
+    static fromData(data: NodeScheduleData): NodeSchedule;
+    /**
+     * Determine the current {@link NodePhase} for a given major version number
+     * at the specified point in time.
+     *
+     * Returns `null` when the major is not present in the schedule or when
+     * `now` is before the release's start date.
+     *
+     * @param major - The Node.js major version number (e.g. `20`).
+     * @param now - The reference `DateTime` against which phases are evaluated.
+     */
+    phaseFor(major: number, now: DateTime.DateTime): Effect.Effect<NodePhase | null>;
+    /**
+     * Look up the {@link NodeScheduleEntry} for a given major version number.
+     *
+     * Returns `Option.none()` when the major is not present in the schedule.
+     *
+     * @param major - The Node.js major version number (e.g. `20`).
+     */
+    entryFor(major: number): Option.Option<NodeScheduleEntry>;
 }
 
 /**
  * @internal
- * Exported for declaration bundling — see AuthenticationError.ts for details.
+ *
+ * Exported for declaration bundling (api-extractor). When `export *`
+ * re-exports a class whose `extends` expression is an inline call like
+ * `Data.TaggedClass(...)`, TypeScript emits an un-nameable `_base` symbol in
+ * the declaration file. Splitting the base into a named export gives the
+ * bundler a stable reference.
+ *
+ * @privateRemarks
+ * This base constant must remain a named export so that api-extractor can
+ * resolve the extends clause of {@link NodeSchedule} to a stable declaration.
+ * Without it the bundled `.d.ts` would contain an anonymous `_base` symbol
+ * that cannot be referenced by downstream consumers.
  */
-export declare const InvalidInputErrorBase: new <A extends Record<string, any> = {}>(args: Equals<A, {}> extends true ? void : { readonly [P in keyof A as P extends "_tag" ? never : P]: A[P]; }) => YieldableError & {
-    readonly _tag: "InvalidInputError";
-} & Readonly<A>;
+export declare const NodeScheduleBase: new <A extends Record<string, any> = {}>(args: Equals<A, {}> extends true ? void : { readonly [P in keyof A as P extends "_tag" ? never : P]: A[P]; }) => Readonly<A> & {
+    readonly _tag: "NodeSchedule";
+};
 
-export declare interface ListOptions {
-    readonly perPage?: number;
-    readonly pages?: number;
-}
+/**
+ * Raw schedule format as fetched from the Node.js Release GitHub repository
+ * (`nodejs/Release`).
+ *
+ * This is the intermediate type between the {@link NodeScheduleFetcher} layer
+ * and the {@link NodeSchedule} class. Date values are plain ISO strings; the
+ * `NodeSchedule.fromData` factory converts them to `DateTime`.
+ *
+ * @see {@link NodeSchedule.fromData}
+ * @see {@link NodeScheduleFetcher}
+ *
+ * @public
+ */
+export declare type NodeScheduleData = Record<string, {
+    readonly start: string;
+    readonly lts?: string;
+    readonly maintenance?: string;
+    readonly end: string;
+    readonly codename?: string;
+}>;
 
-export declare class NetworkError extends NetworkErrorBase<{
-    readonly url: string;
-    readonly status?: number;
-    readonly message: string;
-}> {
+/**
+ * A single entry in the Node.js release schedule, representing one major
+ * release line's lifecycle dates and optional LTS codename.
+ *
+ * All date fields have already been converted from ISO strings to Effect
+ * `DateTime.DateTime` values by {@link NodeSchedule.fromData}.
+ *
+ * @see {@link NodeSchedule}
+ * @see {@link NodeSchedule.phaseFor}
+ *
+ * @public
+ */
+export declare interface NodeScheduleEntry {
+    readonly major: number;
+    readonly start: DateTime.DateTime;
+    readonly lts: DateTime.DateTime | null;
+    readonly maintenance: DateTime.DateTime | null;
+    readonly end: DateTime.DateTime;
+    readonly codename: string;
 }
 
 /**
- * @internal
- * Exported for declaration bundling — see AuthenticationError.ts for details.
+ * Service interface for fetching the official Node.js release schedule.
+ *
+ * The schedule maps each major release line to its LTS start date and
+ * end-of-life date, and is used by {@link NodeReleaseCache} to assign
+ * lifecycle phases to individual releases. The live implementation fetches
+ * from the `nodejs/Release` GitHub repository via a plain HTTP request.
+ *
+ * @see {@link NodeScheduleFetcherLive}
+ * @see {@link NodeReleaseCache}
+ * @see {@link NodeScheduleData}
+ * @see {@link NetworkError}
+ * @see {@link ParseError}
+ *
+ * @public
  */
-export declare const NetworkErrorBase: new <A extends Record<string, any> = {}>(args: Equals<A, {}> extends true ? void : { readonly [P in keyof A as P extends "_tag" ? never : P]: A[P]; }) => YieldableError & {
-    readonly _tag: "NetworkError";
-} & Readonly<A>;
+export declare interface NodeScheduleFetcher {
+    /**
+     * Fetches and decodes the Node.js release schedule JSON, returning a
+     * typed {@link NodeScheduleData} map keyed by major release line.
+     *
+     * Fails with:
+     * - {@link NetworkError} — the upstream request could not be completed.
+     * - {@link ParseError} — the response payload could not be decoded.
+     */
+    readonly fetch: () => Effect.Effect<NodeScheduleData, NetworkError | ParseError>;
+}
 
-export declare const NodePhase: Schema.Literal<["current", "active-lts", "maintenance-lts", "end-of-life"]>;
+/**
+ * Service tag and companion object for {@link NodeScheduleFetcher}.
+ *
+ * Acts as both the TypeScript service interface and the Effect dependency tag
+ * used for dependency injection (companion object pattern). Yield this tag
+ * inside `Effect.gen` to access the fetcher implementation provided by
+ * {@link NodeScheduleFetcherLive}.
+ *
+ * @example
+ * ```typescript
+ * import type { NodeScheduleData } from "runtime-resolver";
+ * import { NodeScheduleFetcher, NodeScheduleFetcherLive } from "runtime-resolver";
+ * import { Effect } from "effect";
+ *
+ * const program = Effect.gen(function* () {
+ * 	const fetcher = yield* NodeScheduleFetcher;
+ * 	const schedule = yield* fetcher.fetch();
+ * 	console.log(Object.keys(schedule).length, "major release lines");
+ * });
+ *
+ * Effect.runPromise(program.pipe(Effect.provide(NodeScheduleFetcherLive)));
+ * ```
+ *
+ * @see {@link NodeScheduleFetcherLive}
+ *
+ * @public
+ */
+export declare const NodeScheduleFetcher: Context.Tag<NodeScheduleFetcher, NodeScheduleFetcher>;
 
-export declare type NodePhase = typeof NodePhase.Type;
+/**
+ * Provides the {@link NodeScheduleFetcher} service using the live Node.js release schedule.
+ *
+ * Fetches the Node.js release schedule from the raw GitHub content URL for
+ * `nodejs/Release` (`schedule.json` on the `main` branch) using the HTTP client
+ * on the provided {@link GitHubClient} service. The schedule data maps major
+ * version codenames to their start, LTS, and end-of-life dates and is used by
+ * {@link NodeReleaseCache} to compute per-release lifecycle phases.
+ *
+ * This layer is a required dependency of {@link AutoNodeCacheLive} and
+ * {@link FreshNodeCacheLive}. It is not needed by {@link OfflineNodeCacheLive}.
+ *
+ * @see {@link NodeScheduleFetcher}
+ * @see {@link GitHubClient}
+ * @see {@link AutoNodeCacheLive}
+ * @see {@link FreshNodeCacheLive}
+ * @public
+ */
+export declare const NodeScheduleFetcherLive: Layer.Layer<NodeScheduleFetcher, never, GitHubClient>;
 
 /**
- * Service interface for resolving Node.js runtime versions.
+ * Service interface for fetching Node.js release data from the official
+ * Node.js distribution index.
+ *
+ * Retrieves both the parsed semver version list and the raw
+ * {@link NodeReleaseInput} records needed to populate a
+ * {@link NodeReleaseCache}. The live implementation fetches from
+ * `https://nodejs.org/dist/index.json` via a plain HTTP request — no GitHub
+ * credentials are required.
+ *
+ * @see {@link NodeVersionFetcherLive}
+ * @see {@link NodeReleaseCache}
+ * @see {@link NetworkError}
+ * @see {@link ParseError}
+ *
+ * @public
  */
-export declare interface NodeResolver {
-    readonly resolve: (options?: NodeResolverOptions) => Effect.Effect<ResolvedVersions, NodeResolverError>;
-    readonly resolveVersion: (versionOrRange: string) => Effect.Effect<string, NodeResolverError>;
+export declare interface NodeVersionFetcher {
+    /**
+     * Fetches all available Node.js releases from the distribution index and
+     * returns both the parsed semver version objects and the raw release input
+     * records.
+     *
+     * Fails with:
+     * - {@link NetworkError} — the upstream request could not be completed.
+     * - {@link ParseError} — the response payload could not be decoded.
+     */
+    readonly fetch: () => Effect.Effect<{
+        readonly versions: ReadonlyArray<SemVer.SemVer>;
+        readonly inputs: ReadonlyArray<NodeReleaseInput>;
+    }, NetworkError | ParseError>;
 }
 
 /**
- * @internal Uses GenericTag — see BunResolver.ts for rationale.
+ * Service tag and companion object for {@link NodeVersionFetcher}.
+ *
+ * Acts as both the TypeScript service interface and the Effect dependency tag
+ * used for dependency injection (companion object pattern). Yield this tag
+ * inside `Effect.gen` to access the fetcher implementation provided by
+ * {@link NodeVersionFetcherLive}.
+ *
+ * @example
+ * ```typescript
+ * import type { NodeReleaseInput } from "runtime-resolver";
+ * import { NodeVersionFetcher, NodeVersionFetcherLive } from "runtime-resolver";
+ * import { Effect } from "effect";
+ *
+ * const program = Effect.gen(function* () {
+ * 	const fetcher = yield* NodeVersionFetcher;
+ * 	const { versions, inputs } = yield* fetcher.fetch();
+ * 	console.log(`Fetched ${versions.length} Node.js releases`);
+ * });
+ *
+ * Effect.runPromise(program.pipe(Effect.provide(NodeVersionFetcherLive)));
+ * ```
+ *
+ * @see {@link NodeVersionFetcherLive}
+ *
+ * @public
  */
-export declare const NodeResolver: Context.Tag<NodeResolver, NodeResolver>;
-
-export declare type NodeResolverError = AuthenticationError | NetworkError | ParseError | RateLimitError | VersionNotFoundError | InvalidInputError | FreshnessError | CacheError;
+export declare const NodeVersionFetcher: Context.Tag<NodeVersionFetcher, NodeVersionFetcher>;
 
-export declare const NodeResolverLive: Layer.Layer<NodeResolver, never, GitHubClient | VersionCache>;
-
-export declare interface NodeResolverOptions {
-    readonly semverRange?: string;
-    readonly defaultVersion?: string;
-    readonly phases?: ReadonlyArray<NodePhase>;
-    readonly increments?: Increments;
-    readonly date?: Date;
-    readonly freshness?: Freshness;
-}
+/**
+ * Provides the {@link NodeVersionFetcher} service using the live Node.js dist index.
+ *
+ * Fetches the full Node.js version list from `https://nodejs.org/dist/index.json`
+ * using the HTTP client on the provided {@link GitHubClient} service. Version
+ * strings are normalized by stripping the leading `v` before parsing as semver.
+ * Entries with non-string `npm` fields (present in very old releases prior to
+ * v0.6.3) are substituted with the sentinel version `"0.0.0"`.
+ *
+ * This layer is a required dependency of {@link AutoNodeCacheLive} and
+ * {@link FreshNodeCacheLive}. It is not needed by {@link OfflineNodeCacheLive}.
+ *
+ * @see {@link NodeVersionFetcher}
+ * @see {@link GitHubClient}
+ * @see {@link AutoNodeCacheLive}
+ * @see {@link FreshNodeCacheLive}
+ * @public
+ */
+export declare const NodeVersionFetcherLive: Layer.Layer<NodeVersionFetcher, never, GitHubClient>;
 
 /**
- * Service interface for Octokit REST API client.
+ * Thin wrapper around the subset of Octokit's REST client used by
+ * {@link GitHubClient}.
+ *
+ * Exposing only the repository methods actually consumed by this library
+ * keeps the surface area narrow and makes the interface straightforward to
+ * stub in tests without pulling in the full Octokit type.
+ *
+ * An `OctokitInstance` is provided to the dependency graph by one of the
+ * three authentication layers: {@link GitHubTokenAuth}, {@link GitHubAppAuth},
+ * or {@link GitHubAutoAuth}.
+ *
+ * @see {@link GitHubClientLive}
+ * @see {@link GitHubTokenAuth}
+ * @see {@link GitHubAppAuth}
+ * @see {@link GitHubAutoAuth}
+ *
+ * @public
  */
 export declare interface OctokitInstance {
     readonly rest: {
         readonly repos: {
+            /**
+             * Lists git tags for a repository, corresponding to
+             * `GET /repos/{owner}/{repo}/tags`.
+             *
+             * @param params - Owner, repo, and optional pagination parameters.
+             */
             readonly listTags: (params: {
                 owner: string;
                 repo: string;
@@ -287,6 +2288,12 @@ export declare interface OctokitInstance {
             }) => Promise<{
                 data: Array<unknown>;
             }>;
+            /**
+             * Lists GitHub Releases for a repository, corresponding to
+             * `GET /repos/{owner}/{repo}/releases`.
+             *
+             * @param params - Owner, repo, and optional pagination parameters.
+             */
             readonly listReleases: (params: {
                 owner: string;
                 repo: string;
@@ -300,10 +2307,139 @@ export declare interface OctokitInstance {
 }
 
 /**
- * @internal Uses GenericTag — see BunResolver.ts for rationale.
+ * Service tag and companion object for {@link OctokitInstance}.
+ *
+ * Acts as both the TypeScript service interface and the Effect dependency tag
+ * used for dependency injection (companion object pattern). This tag is
+ * consumed internally by {@link GitHubClientLive} and is satisfied by
+ * whichever authentication layer is provided — {@link GitHubTokenAuth},
+ * {@link GitHubAppAuth}, or {@link GitHubAutoAuth}.
+ *
+ * Most application code should depend on {@link GitHubClient} rather than
+ * this tag directly.
+ *
+ * @example
+ * ```typescript
+ * import { OctokitInstance, GitHubClientLive, GitHubAutoAuth } from "runtime-resolver";
+ * import { Effect } from "effect";
+ *
+ * const program = Effect.gen(function* () {
+ * 	const octokit = yield* OctokitInstance;
+ * 	const response = await octokit.rest.repos.listTags({
+ * 		owner: "oven-sh",
+ * 		repo: "bun",
+ * 		per_page: 10,
+ * 	});
+ * 	console.log(response.data.length);
+ * });
+ *
+ * Effect.runPromise(program.pipe(Effect.provide(GitHubAutoAuth)));
+ * ```
+ *
+ * @see {@link GitHubClientLive}
+ * @see {@link GitHubTokenAuth}
+ * @see {@link GitHubAppAuth}
+ * @see {@link GitHubAutoAuth}
+ *
+ * @public
  */
 export declare const OctokitInstance: Context.Tag<OctokitInstance, OctokitInstance>;
 
+/**
+ * Provides the {@link BunReleaseCache} service using the "Offline" cache strategy.
+ *
+ * Uses only the bundled default Bun release data that was baked in at build time.
+ * Makes no network requests and has no runtime dependencies. This layer always
+ * succeeds immediately.
+ *
+ * Use this strategy in environments where network access is unavailable or
+ * undesirable (e.g., air-gapped systems, hermetic test environments, or any
+ * context where version data from the bundle is sufficient).
+ *
+ * The three Bun cache strategy layers are:
+ * - {@link AutoBunCacheLive} — tries API first, falls back to bundled defaults on any error
+ * - {@link FreshBunCacheLive} — requires live API data, fails with `FreshnessError` if unavailable
+ * - `OfflineBunCacheLive` — uses only bundled defaults, no network I/O
+ *
+ * @see {@link BunReleaseCache}
+ * @see {@link AutoBunCacheLive}
+ * @see {@link FreshBunCacheLive}
+ * @public
+ */
+export declare const OfflineBunCacheLive: Layer.Layer<BunReleaseCache>;
+
+/**
+ * Provides the {@link DenoReleaseCache} service using the "Offline" cache strategy.
+ *
+ * Uses only the bundled default Deno release data that was baked in at build time.
+ * Makes no network requests and has no runtime dependencies. This layer always
+ * succeeds immediately.
+ *
+ * Use this strategy in environments where network access is unavailable or
+ * undesirable (e.g., air-gapped systems, hermetic test environments, or any
+ * context where version data from the bundle is sufficient).
+ *
+ * The three Deno cache strategy layers are:
+ * - {@link AutoDenoCacheLive} — tries API first, falls back to bundled defaults on any error
+ * - {@link FreshDenoCacheLive} — requires live API data, fails with `FreshnessError` if unavailable
+ * - `OfflineDenoCacheLive` — uses only bundled defaults, no network I/O
+ *
+ * @see {@link DenoReleaseCache}
+ * @see {@link AutoDenoCacheLive}
+ * @see {@link FreshDenoCacheLive}
+ * @public
+ */
+export declare const OfflineDenoCacheLive: Layer.Layer<DenoReleaseCache>;
+
+/**
+ * Provides the {@link NodeReleaseCache} service using the "Offline" cache strategy.
+ *
+ * Uses only the bundled default Node.js release data and schedule data that were
+ * baked in at build time. Makes no network requests and has no runtime
+ * dependencies. This layer always succeeds immediately.
+ *
+ * Use this strategy in environments where network access is unavailable or
+ * undesirable (e.g., air-gapped systems, hermetic test environments, or any
+ * context where version data from the bundle is sufficient).
+ *
+ * The three Node cache strategy layers are:
+ * - {@link AutoNodeCacheLive} — tries API first, falls back to bundled defaults on any error
+ * - {@link FreshNodeCacheLive} — requires live API data, fails with `FreshnessError` if unavailable
+ * - `OfflineNodeCacheLive` — uses only bundled defaults, no network I/O
+ *
+ * @see {@link NodeReleaseCache}
+ * @see {@link AutoNodeCacheLive}
+ * @see {@link FreshNodeCacheLive}
+ * @public
+ */
+export declare const OfflineNodeCacheLive: Layer.Layer<NodeReleaseCache>;
+
+/**
+ * Raised when the body of an upstream API response cannot be decoded.
+ *
+ * This error is produced after a successful HTTP response is received but
+ * its payload does not match the expected shape — for example, when a release
+ * index returns malformed JSON or when a required field is missing from the
+ * response structure. The `source` field identifies the URL or data source
+ * that produced the unparseable content.
+ *
+ * @example
+ * ```typescript
+ * import { Effect } from "effect";
+ * import type { ParseError } from "./ParseError.js";
+ * import { resolveNode } from "../resolvers/node.js";
+ *
+ * const program = resolveNode(">=20").pipe(
+ *   Effect.catchTag("ParseError", (err: ParseError) =>
+ *     Effect.logError(
+ *       `Failed to parse response from ${err.source}: ${err.message}`
+ *     ).pipe(Effect.andThen(Effect.fail(err)))
+ *   )
+ * );
+ * ```
+ *
+ * @public
+ */
 export declare class ParseError extends ParseErrorBase<{
     readonly source: string;
     readonly message: string;
@@ -313,11 +2449,49 @@ export declare class ParseError extends ParseErrorBase<{
 /**
  * @internal
  * Exported for declaration bundling — see AuthenticationError.ts for details.
+ *
+ * @privateRemarks
+ * This base constant must remain a named export so that api-extractor can
+ * resolve the extends clause of {@link ParseError} to a stable declaration.
+ * Without it the bundled `.d.ts` would contain an anonymous `_base` symbol
+ * that cannot be referenced by downstream consumers.
  */
 export declare const ParseErrorBase: new <A extends Record<string, any> = {}>(args: Equals<A, {}> extends true ? void : { readonly [P in keyof A as P extends "_tag" ? never : P]: A[P]; }) => YieldableError & {
     readonly _tag: "ParseError";
 } & Readonly<A>;
 
+/**
+ * Raised when a GitHub API rate limit is exceeded.
+ *
+ * The `limit` and `remaining` fields reflect the values returned in the
+ * `X-RateLimit-Limit` and `X-RateLimit-Remaining` response headers. When the
+ * API indicates how long to wait before the quota resets, that duration (in
+ * seconds) is available via `retryAfter`.
+ *
+ * Use {@link retryOnRateLimit} to automatically retry an effect with
+ * exponential backoff whenever this error is encountered.
+ *
+ * @see {@link retryOnRateLimit}
+ *
+ * @example
+ * ```typescript
+ * import { Effect } from "effect";
+ * import type { RateLimitError } from "./RateLimitError.js";
+ * import { resolveNode } from "../resolvers/node.js";
+ *
+ * const program = resolveNode(">=20").pipe(
+ *   Effect.catchTag("RateLimitError", (err: RateLimitError) =>
+ *     Effect.logWarning(
+ *       `Rate limit hit (${err.remaining}/${err.limit} remaining)` +
+ *       (err.retryAfter != null ? `, retry after ${err.retryAfter}s` : "") +
+ *       `: ${err.message}`
+ *     ).pipe(Effect.andThen(Effect.fail(err)))
+ *   )
+ * );
+ * ```
+ *
+ * @public
+ */
 export declare class RateLimitError extends RateLimitErrorBase<{
     readonly retryAfter?: number;
     readonly limit: number;
@@ -329,6 +2503,12 @@ export declare class RateLimitError extends RateLimitErrorBase<{
 /**
  * @internal
  * Exported for declaration bundling — see AuthenticationError.ts for details.
+ *
+ * @privateRemarks
+ * This base constant must remain a named export so that api-extractor can
+ * resolve the extends clause of {@link RateLimitError} to a stable declaration.
+ * Without it the bundled `.d.ts` would contain an anonymous `_base` symbol
+ * that cannot be referenced by downstream consumers.
  */
 export declare const RateLimitErrorBase: new <A extends Record<string, any> = {}>(args: Equals<A, {}> extends true ? void : { readonly [P in keyof A as P extends "_tag" ? never : P]: A[P]; }) => YieldableError & {
     readonly _tag: "RateLimitError";
@@ -337,8 +2517,29 @@ export declare const RateLimitErrorBase: new <A extends Record<string, any> = {}
 /**
  * Resolve Bun versions matching the given options.
  *
- * Uses GITHUB_PERSONAL_ACCESS_TOKEN or GITHUB_TOKEN for authentication.
- * Falls back to build-time cache when the network is unavailable.
+ * Fetches release data from the Bun GitHub repository, then filters and ranks
+ * versions according to `options`. Authentication is read from
+ * `GITHUB_PERSONAL_ACCESS_TOKEN` or `GITHUB_TOKEN` environment variables.
+ * Falls back to a build-time offline cache when the network is unavailable.
+ *
+ * @param options - Filtering and ranking options. See {@link BunResolverOptions}.
+ * @returns A promise that resolves to a {@link ResolvedVersions} object
+ *   containing the matched version list and the highest matching version as
+ *   `latest`.
+ *
+ * @example
+ * ```ts
+ * import type { ResolvedVersions } from "runtime-resolver";
+ * import { resolveBun } from "runtime-resolver";
+ *
+ * const result: ResolvedVersions = await resolveBun({ semverRange: "^1.0.0" });
+ * console.log(result.latest);
+ * ```
+ *
+ * @see {@link BunResolver} for the Effect-based API
+ * @see {@link BunResolverOptions} for available options
+ *
+ * @public
  */
 export declare const resolveBun: (options?: BunResolverOptions | undefined) => Promise<{
     readonly source: "api" | "cache";
@@ -351,8 +2552,29 @@ export declare const resolveBun: (options?: BunResolverOptions | undefined) => P
 /**
  * Resolve Deno versions matching the given options.
  *
- * Uses GITHUB_PERSONAL_ACCESS_TOKEN or GITHUB_TOKEN for authentication.
- * Falls back to build-time cache when the network is unavailable.
+ * Fetches release data from the Deno GitHub repository, then filters and ranks
+ * versions according to `options`. Authentication is read from
+ * `GITHUB_PERSONAL_ACCESS_TOKEN` or `GITHUB_TOKEN` environment variables.
+ * Falls back to a build-time offline cache when the network is unavailable.
+ *
+ * @param options - Filtering and ranking options. See {@link DenoResolverOptions}.
+ * @returns A promise that resolves to a {@link ResolvedVersions} object
+ *   containing the matched version list and the highest matching version as
+ *   `latest`.
+ *
+ * @example
+ * ```ts
+ * import type { ResolvedVersions } from "runtime-resolver";
+ * import { resolveDeno } from "runtime-resolver";
+ *
+ * const result: ResolvedVersions = await resolveDeno({ semverRange: "^2.0.0" });
+ * console.log(result.latest);
+ * ```
+ *
+ * @see {@link DenoResolver} for the Effect-based API
+ * @see {@link DenoResolverOptions} for available options
+ *
+ * @public
  */
 export declare const resolveDeno: (options?: DenoResolverOptions | undefined) => Promise<{
     readonly source: "api" | "cache";
@@ -362,6 +2584,35 @@ export declare const resolveDeno: (options?: DenoResolverOptions | undefined) =>
     readonly default?: string | undefined;
 }>;
 
+/**
+ * The primary return type produced by every runtime resolver.
+ *
+ * Contains the full list of matching versions, the latest version string, and
+ * optional `lts` / `default` version strings depending on the runtime.
+ * The `source` field indicates whether the data came from a live API call or
+ * a cached snapshot.
+ *
+ * @see {@link resolveNode}
+ * @see {@link resolveBun}
+ * @see {@link resolveDeno}
+ *
+ * @example
+ * ```typescript
+ * import { Effect } from "effect";
+ * import type { ResolvedVersions } from "./common.js";
+ * import { resolveNode } from "../resolvers/node.js";
+ *
+ * const program: Effect.Effect<ResolvedVersions> = resolveNode(">=20");
+ *
+ * Effect.runPromise(program).then((result: ResolvedVersions) => {
+ *   console.log(result.latest);   // e.g. "22.3.0"
+ *   console.log(result.source);   // "api" | "cache"
+ *   console.log(result.versions); // ["22.3.0", "22.2.0", ...]
+ * });
+ * ```
+ *
+ * @public
+ */
 export declare const ResolvedVersions: Schema.Struct<{
     source: Schema.Literal<["api", "cache"]>;
     versions: Schema.Array$<typeof Schema.String>;
@@ -370,13 +2621,48 @@ export declare const ResolvedVersions: Schema.Struct<{
     default: Schema.optional<typeof Schema.String>;
 }>;
 
+/**
+ * The primary return type produced by every runtime resolver.
+ *
+ * @see {@link resolveNode}
+ * @see {@link resolveBun}
+ * @see {@link resolveDeno}
+ *
+ * @public
+ */
 export declare type ResolvedVersions = typeof ResolvedVersions.Type;
 
 /**
  * Resolve Node.js versions matching the given options.
  *
- * Uses GITHUB_PERSONAL_ACCESS_TOKEN or GITHUB_TOKEN for authentication.
- * Falls back to build-time cache when the network is unavailable.
+ * Fetches release data from the Node.js GitHub repository and the official
+ * release schedule API, then filters and ranks versions according to
+ * `options`. Authentication is read from `GITHUB_PERSONAL_ACCESS_TOKEN` or
+ * `GITHUB_TOKEN` environment variables. Falls back to a build-time offline
+ * cache when the network is unavailable.
+ *
+ * @param options - Filtering and ranking options. See {@link NodeResolverOptions}.
+ * @returns A promise that resolves to a {@link ResolvedVersions} object
+ *   containing the matched version list, the highest matching version as
+ *   `latest`, and optional `lts` / `default` strings.
+ *
+ * @example
+ * ```ts
+ * import type { ResolvedVersions } from "runtime-resolver";
+ * import { resolveNode } from "runtime-resolver";
+ *
+ * const result: ResolvedVersions = await resolveNode({
+ * 	semverRange: ">=20.0.0",
+ * 	phases: ["active-lts"],
+ * });
+ * console.log(result.latest); // e.g. "22.11.0"
+ * console.log(result.versions); // all matching versions
+ * ```
+ *
+ * @see {@link NodeResolver} for the Effect-based API
+ * @see {@link NodeResolverOptions} for available options
+ *
+ * @public
  */
 export declare const resolveNode: (options?: NodeResolverOptions | undefined) => Promise<{
     readonly source: "api" | "cache";
@@ -386,32 +2672,214 @@ export declare const resolveNode: (options?: NodeResolverOptions | undefined) =>
     readonly default?: string | undefined;
 }>;
 
+/**
+ * Discriminates which JavaScript runtime a resolver targets.
+ *
+ * @see {@link resolveNode}
+ * @see {@link resolveBun}
+ * @see {@link resolveDeno}
+ *
+ * @public
+ */
 export declare const Runtime: Schema.Literal<["node", "bun", "deno"]>;
 
+/**
+ * Discriminates which JavaScript runtime a resolver targets.
+ *
+ * @see {@link resolveNode}
+ * @see {@link resolveBun}
+ * @see {@link resolveDeno}
+ *
+ * @public
+ */
 export declare type Runtime = typeof Runtime.Type;
 
-export declare const Source: Schema.Literal<["api", "cache"]>;
-
-export declare type Source = typeof Source.Type;
+/**
+ * Generic in-memory cache service for a typed runtime release collection,
+ * built on top of semver-effect's version cache primitives.
+ *
+ * Concrete instantiations are {@link BunReleaseCache}, {@link DenoReleaseCache},
+ * and {@link NodeReleaseCache}. The canonical factory function for obtaining a
+ * `RuntimeCache` implementation is {@link createRuntimeCache}.
+ *
+ * @typeParam R - A {@link RuntimeRelease} subtype specific to the runtime
+ * (e.g. `BunRelease`, `DenoRelease`, `NodeRelease`).
+ *
+ * @example
+ * ```typescript
+ * import type { BunRelease } from "runtime-resolver";
+ * import { BunReleaseCache, OfflineBunCacheLive } from "runtime-resolver";
+ * import { Effect } from "effect";
+ *
+ * const program = Effect.gen(function* () {
+ * 	const cache = yield* BunReleaseCache;
+ * 	const latest = yield* cache.latest();
+ * 	console.log(latest.version.toString());
+ * });
+ *
+ * Effect.runPromise(program.pipe(Effect.provide(OfflineBunCacheLive)));
+ * ```
+ *
+ * @see {@link BunReleaseCache}
+ * @see {@link DenoReleaseCache}
+ * @see {@link NodeReleaseCache}
+ * @see {@link createRuntimeCache}
+ *
+ * @public
+ */
+export declare interface RuntimeCache<R extends RuntimeRelease> {
+    /**
+     * Populates the cache with the given array of typed release objects,
+     * replacing any previously loaded entries.
+     *
+     * @param releases - The full set of releases to store.
+     */
+    readonly load: (releases: ReadonlyArray<R>) => Effect.Effect<void>;
+    /**
+     * Finds the single best-matching release for the given semver range string,
+     * preferring the highest satisfying version.
+     *
+     * Fails with {@link InvalidRangeError} when `range` is not a valid semver
+     * range expression, or with {@link UnsatisfiedRangeError} when no cached
+     * release satisfies the range.
+     *
+     * @param range - A semver range string (e.g. `">=1.0.0 <2.0.0"`).
+     */
+    readonly resolve: (range: string) => Effect.Effect<R, InvalidRangeError | UnsatisfiedRangeError>;
+    /**
+     * Returns the complete list of all releases currently held in the cache,
+     * in the order they were loaded.
+     */
+    readonly releases: () => Effect.Effect<ReadonlyArray<R>>;
+    /**
+     * Returns all cached releases whose version satisfies the given semver
+     * range string.
+     *
+     * Fails with {@link InvalidRangeError} when `range` is not a valid semver
+     * range expression.
+     *
+     * @param range - A semver range string (e.g. `"^20.0.0"`).
+     */
+    readonly filter: (range: string) => Effect.Effect<ReadonlyArray<R>, InvalidRangeError>;
+    /**
+     * Returns the release with the highest version among all entries in the
+     * cache.
+     *
+     * Fails with {@link EmptyCacheError} when the cache contains no releases.
+     */
+    readonly latest: () => Effect.Effect<R, EmptyCacheError>;
+    /**
+     * Returns one release per major version line, each being the highest
+     * available version within that major line.
+     *
+     * Returns an empty array when the cache is empty.
+     */
+    readonly latestByMajor: () => Effect.Effect<ReadonlyArray<R>>;
+    /**
+     * Returns one release per minor version line, each being the highest
+     * available patch version within that minor line.
+     *
+     * Returns an empty array when the cache is empty.
+     */
+    readonly latestByMinor: () => Effect.Effect<ReadonlyArray<R>>;
+}
 
 /**
- * Service interface for version data caching.
+ * Structural base constraint shared by {@link BunRelease}, {@link DenoRelease},
+ * and {@link NodeRelease}.
+ *
+ * Enables the generic `RuntimeCache<R extends RuntimeRelease>` service to
+ * operate over any runtime release type without coupling to a concrete class.
+ *
+ * @see {@link RuntimeCache}
+ * @see {@link BunRelease}
+ * @see {@link DenoRelease}
+ * @see {@link NodeRelease}
+ *
+ * @public
  */
-export declare interface VersionCache {
-    readonly get: (runtime: Runtime) => Effect.Effect<{
-        data: CachedData;
-        source: Source;
-    }, CacheError>;
-    readonly set: (runtime: Runtime, data: CachedData) => Effect.Effect<void, CacheError>;
+export declare interface RuntimeRelease {
+    readonly _tag: string;
+    readonly version: SemVer.SemVer;
+    readonly date: DateTime.DateTime;
 }
 
 /**
- * @internal Uses GenericTag — see BunResolver.ts for rationale.
+ * Lean input schema used to construct {@link BunRelease} and
+ * {@link DenoRelease} instances from bundled default data files.
+ *
+ * Both Bun and Deno source their offline snapshots from JSON/TS data files
+ * whose entries conform to this shape. The `version` and `date` fields are
+ * plain strings that are subsequently parsed by `SemVer.fromString` and
+ * `DateTime.unsafeMake` respectively.
+ *
+ * @see {@link BunRelease.fromInput}
+ * @see {@link DenoRelease.fromInput}
+ *
+ * @public
+ */
+export declare const RuntimeReleaseInput: Schema.Struct<{
+    version: typeof Schema.String;
+    date: typeof Schema.String;
+}>;
+
+/**
+ * Lean input type used to construct {@link BunRelease} and {@link DenoRelease}
+ * instances from bundled default data files.
+ *
+ * @see {@link BunRelease.fromInput}
+ * @see {@link DenoRelease.fromInput}
+ *
+ * @public
+ */
+export declare type RuntimeReleaseInput = typeof RuntimeReleaseInput.Type;
+
+/**
+ * Indicates whether a {@link ResolvedVersions} result was served from
+ * a live API call or a local cache.
+ *
+ * @public
  */
-export declare const VersionCache: Context.Tag<VersionCache, VersionCache>;
+export declare const Source: Schema.Literal<["api", "cache"]>;
 
-export declare const VersionCacheLive: Layer.Layer<VersionCache>;
+/**
+ * Indicates whether a {@link ResolvedVersions} result was served from
+ * a live API call or a local cache.
+ *
+ * @public
+ */
+export declare type Source = typeof Source.Type;
 
+/**
+ * Raised when no published version satisfies the requested constraint.
+ *
+ * This error is produced by {@link NodeResolver}, {@link BunResolver}, and
+ * {@link DenoResolver} after the full list of available versions has been
+ * fetched and filtered but no entry matches the caller-supplied semver
+ * constraint. The `runtime` field identifies which runtime was queried and
+ * `constraint` echoes the range string that was provided.
+ *
+ * @see {@link NodeResolver}
+ * @see {@link BunResolver}
+ * @see {@link DenoResolver}
+ *
+ * @example
+ * ```typescript
+ * import { Effect } from "effect";
+ * import type { VersionNotFoundError } from "./VersionNotFoundError.js";
+ * import { resolveNode } from "../resolvers/node.js";
+ *
+ * const program = resolveNode(">=999").pipe(
+ *   Effect.catchTag("VersionNotFoundError", (err: VersionNotFoundError) =>
+ *     Effect.logError(
+ *       `No ${err.runtime} version matched "${err.constraint}": ${err.message}`
+ *     ).pipe(Effect.andThen(Effect.fail(err)))
+ *   )
+ * );
+ * ```
+ *
+ * @public
+ */
 export declare class VersionNotFoundError extends VersionNotFoundErrorBase<{
     readonly runtime: Runtime;
     readonly constraint: string;
@@ -422,6 +2890,12 @@ export declare class VersionNotFoundError extends VersionNotFoundErrorBase<{
 /**
  * @internal
  * Exported for declaration bundling — see AuthenticationError.ts for details.
+ *
+ * @privateRemarks
+ * This base constant must remain a named export so that api-extractor can
+ * resolve the extends clause of {@link VersionNotFoundError} to a stable
+ * declaration. Without it the bundled `.d.ts` would contain an anonymous
+ * `_base` symbol that cannot be referenced by downstream consumers.
  */
 export declare const VersionNotFoundErrorBase: new <A extends Record<string, any> = {}>(args: Equals<A, {}> extends true ? void : { readonly [P in keyof A as P extends "_tag" ? never : P]: A[P]; }) => YieldableError & {
     readonly _tag: "VersionNotFoundError";