[Feature] Sharded daemon process partition placement

[pathosDev]

Size / Priority

• Size: S
• Reference: Akka ShardedDaemonProcess. actor-ts already has the file src/cluster/sharding/ShardedDaemonProcess.ts — likely partial implementation.

Caveat — likely partially-implemented

src/cluster/sharding/ShardedDaemonProcess.ts exists. Need to verify what's there before scope is set. This issue tracks any gaps; if fully implemented, it's a documentation pass.

Rationale

Common pattern: a background worker that should run as N replicas, evenly distributed across the cluster, with auto-rebalance on node failure. Examples:

• N projection consumers (each handles a partition of pids).
• N polling workers (each handles a topic-partition or a queue-shard).
• N scheduled-job runners.

Cluster sharding provides distribution + rebalance. ShardedDaemonProcess wraps it: declare "I want N instances of this Behavior"; cluster does the placement.

Design sketch

// src/cluster/sharding/ShardedDaemonProcess.ts (verify what's there)

export interface ShardedDaemonOptions {
  readonly name: string;
  readonly numInstances: number;
  /** Factory called with the instance index (0..numInstances-1). */
  readonly factory: (instanceId: number) => Props<unknown>;
  readonly allocationStrategy?: AllocationStrategy;
}

export function startShardedDaemon(cluster: Cluster, options: ShardedDaemonOptions): Promise<DaemonHandle>;

Behaviour:

• Spawns N entity-actors in a cluster-sharding type named daemon-<name>.
• Each entity's id is <index>.
• AllocationStrategy distributes; default LeastShardAllocationStrategy.
• Node failure → entity rebalanced to surviving nodes.

Verify-and-fix tasks

• Read src/cluster/sharding/ShardedDaemonProcess.ts; document what's present.
• Fill any gaps against the design sketch above.
• Documentation: usage examples + comparison with ClusterSingleton.
• Test suite if not already present.
• CHANGELOG entry if missing.

Out of scope / non-goals

• Single-instance daemon: that's ClusterSingleton.
• Per-message ephemeral spawn: that's standard sharding.

Acceptance criteria

• Verify implementation completeness.
• If gaps: implement to sketch.
• Documentation.
• Test suite covers rebalance on node failure.
• CHANGELOG entry.