@typed/fx 2.0.0-beta.0 → 2.0.0-beta.10

package/dist/RefSubject/RefHashRing.d.ts

@@ -10,29 +10,73 @@ import type * as Fx from "../Fx/index.js";
 import * as RefSubject from "./RefSubject.js";
 /**
  * A RefHashRing is a RefSubject specialized over a HashRing.
+ * @remarks
+ * ## Why
+ *
+ * Defines hash ring state with the same current-read, pushed-update, and synchronized-write
+ * contract as RefSubject.
+ *
+ * ## Ownership and lifetime
+ *
+ * RefHashRing is a contract and performs no acquisition. Implementations retain the errors,
+ * services, interruption, and Scope requirements expressed by its members.
+ *
  * @since 1.18.0
- * @category models
+ * @category State models
  */
 export interface RefHashRing<in out A extends PrimaryKey.PrimaryKey, in out E = never, out R = never> extends RefSubject.RefSubject<HashRing.HashRing<A>, E, R> {
 }
 /**
  * Creates a new `RefHashRing` from a HashRing, `Effect`, or `Fx`.
+ * @remarks
+ * ## Why
+ *
+ * Creates hash ring state with equality suited to that Effect data type, so unchanged values do
+ * not produce redundant pushed updates.
+ *
+ * ## Ownership and lifetime
+ *
+ * The creation Effect requires Scope. It owns initializer acquisition, live source subscriptions,
+ * and cleanup; source failures and services stay on reads and pushes.
+ *
  * @since 1.18.0
- * @category constructors
+ * @category Constructors
  */
-export declare function make<A extends PrimaryKey.PrimaryKey, E, R>(initial: HashRing.HashRing<A> | Effect.Effect<HashRing.HashRing<A>, E, R> | Fx.Fx<HashRing.HashRing<A>, E, R>): Effect.Effect<RefHashRing<A, E>, never, R | Scope.Scope>;
+export declare function make<A extends PrimaryKey.PrimaryKey, E = never, R = never>(initial: HashRing.HashRing<A> | Effect.Effect<HashRing.HashRing<A>, E, R> | Fx.Fx<HashRing.HashRing<A>, E, R>): Effect.Effect<RefHashRing<A, E>, never, R | Scope.Scope>;
 /**
  * Creates a new empty RefHashRing.
+ * @remarks
+ * ## Why
+ *
+ * Creates a new empty RefHashRing. The operation remains attached to the RefSubject's versioned
+ * state boundary.
+ *
+ * ## Ownership and lifetime
+ *
+ * Running empty performs one serialized hash ring transition and resolves with its committed
+ * value. It acquires no resource; failures and services remain those of the source ref.
+ *
  * @since 1.18.0
- * @category constructors
+ * @category Constructors
  */
-export declare function empty<A extends PrimaryKey.PrimaryKey, E, R>(options?: {
+export declare function empty<A extends PrimaryKey.PrimaryKey, E = never, R = never>(options?: {
     readonly baseWeight?: number;
 }): Effect.Effect<RefHashRing<A, E>, never, R | Scope.Scope>;
 /**
  * Add a node to the HashRing.
+ * @remarks
+ * ## Why
+ *
+ * Add a node to the HashRing. The operation remains attached to the RefSubject's versioned state
+ * boundary.
+ *
+ * ## Ownership and lifetime
+ *
+ * Running add performs one serialized hash ring transition and resolves with its committed value.
+ * It acquires no resource; failures and services remain those of the source ref.
+ *
  * @since 1.18.0
- * @category combinators
+ * @category State updates
  */
 export declare const add: {
     <A extends PrimaryKey.PrimaryKey>(node: A, options?: {
@@ -44,8 +88,19 @@ export declare const add: {
 };
 /**
  * Add multiple nodes to the HashRing.
+ * @remarks
+ * ## Why
+ *
+ * Add multiple nodes to the HashRing. The operation remains attached to the RefSubject's versioned
+ * state boundary.
+ *
+ * ## Ownership and lifetime
+ *
+ * Running add many performs one serialized hash ring transition and resolves with its committed
+ * value. It acquires no resource; failures and services remain those of the source ref.
+ *
  * @since 1.18.0
- * @category combinators
+ * @category State updates
  */
 export declare const addMany: {
     <A extends PrimaryKey.PrimaryKey>(nodes: Iterable<A>, options?: {
@@ -57,8 +112,19 @@ export declare const addMany: {
 };
 /**
  * Remove a node from the HashRing.
+ * @remarks
+ * ## Why
+ *
+ * Applies remove to the committed hash ring value and publishes only the result, preserving its
+ * element order and equality rules.
+ *
+ * ## Ownership and lifetime
+ *
+ * Running remove performs one serialized hash ring transition and resolves with its committed
+ * value. It acquires no resource; failures and services remain those of the source ref.
+ *
  * @since 1.18.0
- * @category combinators
+ * @category State updates
  */
 export declare const remove: {
     <A extends PrimaryKey.PrimaryKey>(node: A): <E, R>(ref: RefHashRing<A, E, R>) => Effect.Effect<HashRing.HashRing<A>, E, R>;
@@ -66,8 +132,19 @@ export declare const remove: {
 };
 /**
  * Check if a node exists in the HashRing.
+ * @remarks
+ * ## Why
+ *
+ * Makes has a live projection of the hash ring; consumers can sample it now or observe it without
+ * copying the source state.
+ *
+ * ## Ownership and lifetime
+ *
+ * The has view retains no independent state. An Effect read samples the source once; Fx
+ * observation follows later pushes and its observing Scope owns subscription cleanup.
+ *
  * @since 1.18.0
- * @category computed
+ * @category State predicates
  */
 export declare const has: {
     <A extends PrimaryKey.PrimaryKey>(node: A): <E, R>(ref: RefHashRing<A, E, R>) => RefSubject.Computed<boolean, E, R>;
@@ -75,21 +152,54 @@ export declare const has: {
 };
 /**
  * Get the number of nodes in the HashRing.
+ * @remarks
+ * ## Why
+ *
+ * Makes size a live projection of the hash ring; consumers can sample it now or observe it without
+ * copying the source state.
+ *
+ * ## Ownership and lifetime
+ *
+ * The size view retains no independent state. An Effect read samples the source once; Fx
+ * observation follows later pushes and its observing Scope owns subscription cleanup.
+ *
  * @since 1.18.0
- * @category computed
+ * @category Derived queries
  */
 export declare const size: <A extends PrimaryKey.PrimaryKey, E, R>(ref: RefHashRing<A, E, R>) => RefSubject.Computed<number, E, R>;
 /**
  * Check if the HashRing is empty.
+ * @remarks
+ * ## Why
+ *
+ * Makes is empty a live projection of the hash ring; consumers can sample it now or observe it
+ * without copying the source state.
+ *
+ * ## Ownership and lifetime
+ *
+ * The is empty view retains no independent state. An Effect read samples the source once; Fx
+ * observation follows later pushes and its observing Scope owns subscription cleanup.
+ *
  * @since 1.18.0
- * @category computed
+ * @category State predicates
  */
 export declare const isEmpty: <A extends PrimaryKey.PrimaryKey, E, R>(ref: RefHashRing<A, E, R>) => RefSubject.Computed<boolean, E, R>;
 /**
  * Get the node which should handle a given input string as a Computed.
  * Returns undefined if the ring is empty.
+ * @remarks
+ * ## Why
+ *
+ * Projects the selected node for current reads and later pushes. An empty ring is represented by
+ * `undefined` inside the Computed value; it does not become Filtered or add `NoSuchElementError`.
+ *
+ * ## Ownership and lifetime
+ *
+ * The get node view retains no independent state. An Effect read samples the source once; Fx
+ * observation follows later pushes and its observing Scope owns subscription cleanup.
+ *
  * @since 1.18.0
- * @category computed
+ * @category Derived queries
  */
 export declare const getNode: {
     (input: string): <A extends PrimaryKey.PrimaryKey, E, R>(ref: RefHashRing<A, E, R>) => RefSubject.Computed<A | undefined, E, R>;
@@ -97,8 +207,20 @@ export declare const getNode: {
 };
 /**
  * Get shard distribution across nodes.
+ * @remarks
+ * ## Why
+ *
+ * Projects the shard distribution for current reads and later pushes. An empty ring is represented
+ * by `undefined` inside the Computed value; it does not become Filtered or add
+ * `NoSuchElementError`.
+ *
+ * ## Ownership and lifetime
+ *
+ * The get shards view retains no independent state. An Effect read samples the source once; Fx
+ * observation follows later pushes and its observing Scope owns subscription cleanup.
+ *
  * @since 1.18.0
- * @category computed
+ * @category Derived queries
  */
 export declare const getShards: {
     (count: number): <A extends PrimaryKey.PrimaryKey, E, R>(ref: RefHashRing<A, E, R>) => RefSubject.Computed<Array<A> | undefined, E, R>;
@@ -106,15 +228,37 @@ export declare const getShards: {
 };
 /**
  * Get all nodes as an array.
+ * @remarks
+ * ## Why
+ *
+ * Projects hash ring state with values for both current reads and future pushes, avoiding a second
+ * mutable cache of the derived value.
+ *
+ * ## Ownership and lifetime
+ *
+ * The values view retains no independent state. An Effect read samples the source once; Fx
+ * observation follows later pushes and its observing Scope owns subscription cleanup.
+ *
  * @since 1.18.0
- * @category computed
+ * @category Derived queries
  */
 export declare const values: <A extends PrimaryKey.PrimaryKey, E, R>(ref: RefHashRing<A, E, R>) => RefSubject.Computed<Array<A>, E, R>;
 /**
  * Get the node which should handle a given input string as a Filtered.
  * Fails if the ring is empty.
+ * @remarks
+ * ## Why
+ *
+ * Models the possibly absent result of get as Filtered state, so absence stays explicit while
+ * later source versions can make a value available.
+ *
+ * ## Ownership and lifetime
+ *
+ * The get view retains no independent value. Its Effect read fails with NoSuchElement
+ * while absent; the observing Scope owns and finalizes its Fx subscription.
+ *
  * @since 1.18.0
- * @category filtered
+ * @category Optional queries
  */
 export declare const get: {
     (input: string): <A extends PrimaryKey.PrimaryKey, E, R>(ref: RefHashRing<A, E, R>) => RefSubject.Filtered<A, E, R>;

package/dist/RefSubject/RefHashRing.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"RefHashRing.d.ts","sourceRoot":"","sources":["../../src/RefSubject/RefHashRing.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"RefHashRing.d.ts","sourceRoot":"","sources":["../../src/RefSubject/RefHashRing.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,KAAK,KAAK,MAAM,MAAM,eAAe,CAAC;AAG7C,OAAO,KAAK,QAAQ,MAAM,iBAAiB,CAAC;AAE5C,OAAO,KAAK,KAAK,UAAU,MAAM,mBAAmB,CAAC;AACrD,OAAO,KAAK,KAAK,KAAK,MAAM,cAAc,CAAC;AAC3C,OAAO,KAAK,KAAK,EAAE,MAAM,gBAAgB,CAAC;AAC1C,OAAO,KAAK,UAAU,MAAM,iBAAiB,CAAC;AAE9C;;;;;;;;;;;;;;;GAeG;AACH,MAAM,WAAW,WAAW,CAC1B,EAAE,CAAC,GAAG,CAAC,CAAC,SAAS,UAAU,CAAC,UAAU,EACtC,EAAE,CAAC,GAAG,CAAC,CAAC,GAAG,KAAK,EAChB,GAAG,CAAC,CAAC,GAAG,KAAK,CACb,SAAQ,UAAU,CAAC,UAAU,CAAC,QAAQ,CAAC,QAAQ,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC;CAAG;AAE9D;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,IAAI,CAAC,CAAC,SAAS,UAAU,CAAC,UAAU,EAAE,CAAC,GAAG,KAAK,EAAE,CAAC,GAAG,KAAK,EACxE,OAAO,EACH,QAAQ,CAAC,QAAQ,CAAC,CAAC,CAAC,GACpB,MAAM,CAAC,MAAM,CAAC,QAAQ,CAAC,QAAQ,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,GACzC,EAAE,CAAC,EAAE,CAAC,QAAQ,CAAC,QAAQ,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,GACpC,MAAM,CAAC,MAAM,CAAC,WAAW,CAAC,CAAC,EAAE,CAAC,CAAC,EAAE,KAAK,EAAE,CAAC,GAAG,KAAK,CAAC,KAAK,CAAC,CAE1D;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,KAAK,CAAC,CAAC,SAAS,UAAU,CAAC,UAAU,EAAE,CAAC,GAAG,KAAK,EAAE,CAAC,GAAG,KAAK,EAAE,OAAO,CAAC,EAAE;IACrF,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;CAC9B,GAAG,MAAM,CAAC,MAAM,CAAC,WAAW,CAAC,CAAC,EAAE,CAAC,CAAC,EAAE,KAAK,EAAE,CAAC,GAAG,KAAK,CAAC,KAAK,CAAC,CAE3D;AAcD;;;;;;;;;;;;;;;GAeG;AACH,eAAO,MAAM,GAAG,EAAE;IAChB,CAAC,CAAC,SAAS,UAAU,CAAC,UAAU,EAC9B,IAAI,EAAE,CAAC,EACP,OAAO,CAAC,EAAE;QAAE,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAA;KAAE,GACrC,CAAC,CAAC,EAAE,CAAC,EAAE,GAAG,EAAE,WAAW,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,KAAK,MAAM,CAAC,MAAM,CAAC,QAAQ,CAAC,QAAQ,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,CAAC;IAClF,CAAC,CAAC,SAAS,UAAU,CAAC,UAAU,EAAE,CAAC,EAAE,CAAC,EACpC,GAAG,EAAE,WAAW,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,EACzB,IAAI,EAAE,CAAC,EACP,OAAO,CAAC,EAAE;QAAE,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAA;KAAE,GACrC,MAAM,CAAC,MAAM,CAAC,QAAQ,CAAC,QAAQ,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,CAAC;CAU9C,CAAC;AAEF;;;;;;;;;;;;;;;GAeG;AACH,eAAO,MAAM,OAAO,EAAE;IACpB,CAAC,CAAC,SAAS,UAAU,CAAC,UAAU,EAC9B,KAAK,EAAE,QAAQ,CAAC,CAAC,CAAC,EAClB,OAAO,CAAC,EAAE;QAAE,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAA;KAAE,GACrC,CAAC,CAAC,EAAE,CAAC,EAAE,GAAG,EAAE,WAAW,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,KAAK,MAAM,CAAC,MAAM,CAAC,QAAQ,CAAC,QAAQ,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,CAAC;IAClF,CAAC,CAAC,SAAS,UAAU,CAAC,UAAU,EAAE,CAAC,EAAE,CAAC,EACpC,GAAG,EAAE,WAAW,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,EACzB,KAAK,EAAE,QAAQ,CAAC,CAAC,CAAC,EAClB,OAAO,CAAC,EAAE;QAAE,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAA;KAAE,GACrC,MAAM,CAAC,MAAM,CAAC,QAAQ,CAAC,QAAQ,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,CAAC;CAU9C,CAAC;AAEF;;;;;;;;;;;;;;;GAeG;AACH,eAAO,MAAM,MAAM,EAAE;IACnB,CAAC,CAAC,SAAS,UAAU,CAAC,UAAU,EAC9B,IAAI,EAAE,CAAC,GACN,CAAC,CAAC,EAAE,CAAC,EAAE,GAAG,EAAE,WAAW,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,KAAK,MAAM,CAAC,MAAM,CAAC,QAAQ,CAAC,QAAQ,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,CAAC;IAClF,CAAC,CAAC,SAAS,UAAU,CAAC,UAAU,EAAE,CAAC,EAAE,CAAC,EACpC,GAAG,EAAE,WAAW,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,EACzB,IAAI,EAAE,CAAC,GACN,MAAM,CAAC,MAAM,CAAC,QAAQ,CAAC,QAAQ,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,CAAC;CAO7C,CAAC;AAMH;;;;;;;;;;;;;;;GAeG;AACH,eAAO,MAAM,GAAG,EAAE;IAChB,CAAC,CAAC,SAAS,UAAU,CAAC,UAAU,EAC9B,IAAI,EAAE,CAAC,GACN,CAAC,CAAC,EAAE,CAAC,EAAE,GAAG,EAAE,WAAW,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,KAAK,UAAU,CAAC,QAAQ,CAAC,OAAO,EAAE,CAAC,EAAE,CAAC,CAAC,CAAC;IAC3E,CAAC,CAAC,SAAS,UAAU,CAAC,UAAU,EAAE,CAAC,EAAE,CAAC,EACpC,GAAG,EAAE,WAAW,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,EACzB,IAAI,EAAE,CAAC,GACN,UAAU,CAAC,QAAQ,CAAC,OAAO,EAAE,CAAC,EAAE,CAAC,CAAC,CAAC;CAOtC,CAAC;AAEH;;;;;;;;;;;;;;;GAeG;AACH,eAAO,MAAM,IAAI,GAAI,CAAC,SAAS,UAAU,CAAC,UAAU,EAAE,CAAC,EAAE,CAAC,OACnD,WAAW,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,KACxB,UAAU,CAAC,QAAQ,CAAC,MAAM,EAAE,CAAC,EAAE,CAAC,CAAmD,CAAC;AAEvF;;;;;;;;;;;;;;;GAeG;AACH,eAAO,MAAM,OAAO,GAAI,CAAC,SAAS,UAAU,CAAC,UAAU,EAAE,CAAC,EAAE,CAAC,OACtD,WAAW,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,KACxB,UAAU,CAAC,QAAQ,CAAC,OAAO,EAAE,CAAC,EAAE,CAAC,CAAyD,CAAC;AAE9F;;;;;;;;;;;;;;;;GAgBG;AACH,eAAO,MAAM,OAAO,EAAE;IACpB,CACE,KAAK,EAAE,MAAM,GACZ,CAAC,CAAC,SAAS,UAAU,CAAC,UAAU,EAAE,CAAC,EAAE,CAAC,EACvC,GAAG,EAAE,WAAW,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,KACtB,UAAU,CAAC,QAAQ,CAAC,CAAC,GAAG,SAAS,EAAE,CAAC,EAAE,CAAC,CAAC,CAAC;IAC9C,CAAC,CAAC,SAAS,UAAU,CAAC,UAAU,EAAE,CAAC,EAAE,CAAC,EACpC,GAAG,EAAE,WAAW,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,EACzB,KAAK,EAAE,MAAM,GACZ,UAAU,CAAC,QAAQ,CAAC,CAAC,GAAG,SAAS,EAAE,CAAC,EAAE,CAAC,CAAC,CAAC;CAO5C,CAAC;AAEH;;;;;;;;;;;;;;;;GAgBG;AACH,eAAO,MAAM,SAAS,EAAE;IACtB,CACE,KAAK,EAAE,MAAM,GACZ,CAAC,CAAC,SAAS,UAAU,CAAC,UAAU,EAAE,CAAC,EAAE,CAAC,EACvC,GAAG,EAAE,WAAW,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,KACtB,UAAU,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAC,CAAC,GAAG,SAAS,EAAE,CAAC,EAAE,CAAC,CAAC,CAAC;IACrD,CAAC,CAAC,SAAS,UAAU,CAAC,UAAU,EAAE,CAAC,EAAE,CAAC,EACpC,GAAG,EAAE,WAAW,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,EACzB,KAAK,EAAE,MAAM,GACZ,UAAU,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAC,CAAC,GAAG,SAAS,EAAE,CAAC,EAAE,CAAC,CAAC,CAAC;CAOnD,CAAC;AAEH;;;;;;;;;;;;;;;GAeG;AACH,eAAO,MAAM,MAAM,GAAI,CAAC,SAAS,UAAU,CAAC,UAAU,EAAE,CAAC,EAAE,CAAC,OACrD,WAAW,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,KACxB,UAAU,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAoD,CAAC;AAM1F;;;;;;;;;;;;;;;;GAgBG;AACH,eAAO,MAAM,GAAG,EAAE;IAChB,CACE,KAAK,EAAE,MAAM,GACZ,CAAC,CAAC,SAAS,UAAU,CAAC,UAAU,EAAE,CAAC,EAAE,CAAC,EACvC,GAAG,EAAE,WAAW,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,KACtB,UAAU,CAAC,QAAQ,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,CAAC;IAClC,CAAC,CAAC,SAAS,UAAU,CAAC,UAAU,EAAE,CAAC,EAAE,CAAC,EACpC,GAAG,EAAE,WAAW,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,EACzB,KAAK,EAAE,MAAM,GACZ,UAAU,CAAC,QAAQ,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,CAAC;CAOhC,CAAC"}

package/dist/RefSubject/RefHashRing.js

@@ -9,16 +9,38 @@ import * as Option from "effect/Option";
 import * as RefSubject from "./RefSubject.js";
 /**
  * Creates a new `RefHashRing` from a HashRing, `Effect`, or `Fx`.
+ * @remarks
+ * ## Why
+ *
+ * Creates hash ring state with equality suited to that Effect data type, so unchanged values do
+ * not produce redundant pushed updates.
+ *
+ * ## Ownership and lifetime
+ *
+ * The creation Effect requires Scope. It owns initializer acquisition, live source subscriptions,
+ * and cleanup; source failures and services stay on reads and pushes.
+ *
  * @since 1.18.0
- * @category constructors
+ * @category Constructors
  */
 export function make(initial) {
     return RefSubject.make(initial, { eq: equals });
 }
 /**
  * Creates a new empty RefHashRing.
+ * @remarks
+ * ## Why
+ *
+ * Creates a new empty RefHashRing. The operation remains attached to the RefSubject's versioned
+ * state boundary.
+ *
+ * ## Ownership and lifetime
+ *
+ * Running empty performs one serialized hash ring transition and resolves with its committed
+ * value. It acquires no resource; failures and services remain those of the source ref.
+ *
  * @since 1.18.0
- * @category constructors
+ * @category Constructors
  */
 export function empty(options) {
     return RefSubject.make(HashRing.make(options), { eq: equals });
@@ -33,24 +55,57 @@ function copyRing(ring) {
 // ========================================
 /**
  * Add a node to the HashRing.
+ * @remarks
+ * ## Why
+ *
+ * Add a node to the HashRing. The operation remains attached to the RefSubject's versioned state
+ * boundary.
+ *
+ * ## Ownership and lifetime
+ *
+ * Running add performs one serialized hash ring transition and resolves with its committed value.
+ * It acquires no resource; failures and services remain those of the source ref.
+ *
  * @since 1.18.0
- * @category combinators
+ * @category State updates
  */
 export const add = dual((args) => RefSubject.isRefSubject(args[0]), function add(ref, node, options) {
     return RefSubject.update(ref, (ring) => HashRing.add(copyRing(ring), node, options));
 });
 /**
  * Add multiple nodes to the HashRing.
+ * @remarks
+ * ## Why
+ *
+ * Add multiple nodes to the HashRing. The operation remains attached to the RefSubject's versioned
+ * state boundary.
+ *
+ * ## Ownership and lifetime
+ *
+ * Running add many performs one serialized hash ring transition and resolves with its committed
+ * value. It acquires no resource; failures and services remain those of the source ref.
+ *
  * @since 1.18.0
- * @category combinators
+ * @category State updates
  */
 export const addMany = dual((args) => RefSubject.isRefSubject(args[0]), function addMany(ref, nodes, options) {
     return RefSubject.update(ref, (ring) => HashRing.addMany(copyRing(ring), nodes, options));
 });
 /**
  * Remove a node from the HashRing.
+ * @remarks
+ * ## Why
+ *
+ * Applies remove to the committed hash ring value and publishes only the result, preserving its
+ * element order and equality rules.
+ *
+ * ## Ownership and lifetime
+ *
+ * Running remove performs one serialized hash ring transition and resolves with its committed
+ * value. It acquires no resource; failures and services remain those of the source ref.
+ *
  * @since 1.18.0
- * @category combinators
+ * @category State updates
  */
 export const remove = dual(2, function remove(ref, node) {
     return RefSubject.update(ref, (ring) => HashRing.remove(copyRing(ring), node));
@@ -60,45 +115,112 @@ export const remove = dual(2, function remove(ref, node) {
 // ========================================
 /**
  * Check if a node exists in the HashRing.
+ * @remarks
+ * ## Why
+ *
+ * Makes has a live projection of the hash ring; consumers can sample it now or observe it without
+ * copying the source state.
+ *
+ * ## Ownership and lifetime
+ *
+ * The has view retains no independent state. An Effect read samples the source once; Fx
+ * observation follows later pushes and its observing Scope owns subscription cleanup.
+ *
  * @since 1.18.0
- * @category computed
+ * @category State predicates
  */
 export const has = dual(2, function has(ref, node) {
     return RefSubject.map(ref, HashRing.has(node));
 });
 /**
  * Get the number of nodes in the HashRing.
+ * @remarks
+ * ## Why
+ *
+ * Makes size a live projection of the hash ring; consumers can sample it now or observe it without
+ * copying the source state.
+ *
+ * ## Ownership and lifetime
+ *
+ * The size view retains no independent state. An Effect read samples the source once; Fx
+ * observation follows later pushes and its observing Scope owns subscription cleanup.
+ *
  * @since 1.18.0
- * @category computed
+ * @category Derived queries
  */
 export const size = (ref) => RefSubject.map(ref, (ring) => ring.nodes.size);
 /**
  * Check if the HashRing is empty.
+ * @remarks
+ * ## Why
+ *
+ * Makes is empty a live projection of the hash ring; consumers can sample it now or observe it
+ * without copying the source state.
+ *
+ * ## Ownership and lifetime
+ *
+ * The is empty view retains no independent state. An Effect read samples the source once; Fx
+ * observation follows later pushes and its observing Scope owns subscription cleanup.
+ *
  * @since 1.18.0
- * @category computed
+ * @category State predicates
  */
 export const isEmpty = (ref) => RefSubject.map(ref, (ring) => ring.nodes.size === 0);
 /**
  * Get the node which should handle a given input string as a Computed.
  * Returns undefined if the ring is empty.
+ * @remarks
+ * ## Why
+ *
+ * Projects the selected node for current reads and later pushes. An empty ring is represented by
+ * `undefined` inside the Computed value; it does not become Filtered or add `NoSuchElementError`.
+ *
+ * ## Ownership and lifetime
+ *
+ * The get node view retains no independent state. An Effect read samples the source once; Fx
+ * observation follows later pushes and its observing Scope owns subscription cleanup.
+ *
  * @since 1.18.0
- * @category computed
+ * @category Derived queries
  */
 export const getNode = dual(2, function getNode(ref, input) {
     return RefSubject.map(ref, (ring) => HashRing.get(ring, input));
 });
 /**
  * Get shard distribution across nodes.
+ * @remarks
+ * ## Why
+ *
+ * Projects the shard distribution for current reads and later pushes. An empty ring is represented
+ * by `undefined` inside the Computed value; it does not become Filtered or add
+ * `NoSuchElementError`.
+ *
+ * ## Ownership and lifetime
+ *
+ * The get shards view retains no independent state. An Effect read samples the source once; Fx
+ * observation follows later pushes and its observing Scope owns subscription cleanup.
+ *
  * @since 1.18.0
- * @category computed
+ * @category Derived queries
  */
 export const getShards = dual(2, function getShards(ref, count) {
     return RefSubject.map(ref, (ring) => HashRing.getShards(ring, count));
 });
 /**
  * Get all nodes as an array.
+ * @remarks
+ * ## Why
+ *
+ * Projects hash ring state with values for both current reads and future pushes, avoiding a second
+ * mutable cache of the derived value.
+ *
+ * ## Ownership and lifetime
+ *
+ * The values view retains no independent state. An Effect read samples the source once; Fx
+ * observation follows later pushes and its observing Scope owns subscription cleanup.
+ *
  * @since 1.18.0
- * @category computed
+ * @category Derived queries
  */
 export const values = (ref) => RefSubject.map(ref, (ring) => Array.from(ring));
 // ========================================
@@ -107,8 +229,19 @@ export const values = (ref) => RefSubject.map(ref, (ring) => Array.from(ring));
 /**
  * Get the node which should handle a given input string as a Filtered.
  * Fails if the ring is empty.
+ * @remarks
+ * ## Why
+ *
+ * Models the possibly absent result of get as Filtered state, so absence stays explicit while
+ * later source versions can make a value available.
+ *
+ * ## Ownership and lifetime
+ *
+ * The get view retains no independent value. Its Effect read fails with NoSuchElement
+ * while absent; the observing Scope owns and finalizes its Fx subscription.
+ *
  * @since 1.18.0
- * @category filtered
+ * @category Optional queries
  */
 export const get = dual(2, function get(ref, input) {
     return RefSubject.filterMap(ref, (ring) => Option.fromUndefinedOr(HashRing.get(ring, input)));