virello 0.0.0-stage → 0.1.0

package/docs/engine.md

@@ -0,0 +1,144 @@
+# Original Discord engine milestone
+
+`rilo/engine` is an experimental, independent Bun client implemented inside Rilo. It owns its gateway session, REST transport and synchronous cache. The existing RiloClient, module system, commands, extensions and root exports retain their current behavior. Importing the engine does not migrate framework features.
+
+## Run it
+
+Use Bun canary (`bun upgrade --canary`) and `bun install --frozen-lockfile`.
+
+```sh
+bun run engine:test
+bun check
+bun lint
+bun fmt --check
+bun examples/engine/offline.ts
+```
+
+The offline example creates a loopback HTTP/WebSocket server, receives a message, replies using the engine's REST layer, then reconnects and resumes. It uses a literal fake token.
+
+`bun examples/engine/live.ts` only logs instructions. To opt into Discord yourself, set `DISCORD_TOKEN` and add `--live`. The example requires Guilds, GuildMessages and MessageContent intents, plus permission to read and send in the channel. It replies to `!engine-ping`. Its interaction branch handles an already registered `engine-ping` command; it does not register commands. No live Discord validation was performed.
+
+```ts
+import { createConsoleLogger, EngineClient, logEvent } from "rilo/engine";
+import {
+	GatewayIntentBits,
+	InteractionResponseType,
+} from "discord-api-types/v10";
+
+const logger = createConsoleLogger("MyBot");
+const client = new EngineClient({
+	token: suppliedToken,
+	intents: GatewayIntentBits.Guilds | GatewayIntentBits.GuildMessages,
+	cache: { membersPerGuild: 1000, messagesPerChannel: 0 },
+	onError: ({ source, error, fatal }) =>
+		logEvent(logger, fatal ? "error" : "alert", {
+			component: `engine.${source}`,
+			event: "diagnostic",
+			message: fatal
+				? "Engine cannot continue; inspect the diagnostic cause before restarting."
+				: "Engine reported a recoverable failure; inspect the diagnostic cause.",
+			context: { fatal },
+			error,
+		}),
+});
+client.on("messageCreate", async (message) => {
+	if (message.data.author.bot) return;
+	await message.reply({ content: "Hello", allowed_mentions: { parse: [] } });
+});
+client.on("interactionCreate", async (interaction) => {
+	if (interaction.data.type === 2)
+		await interaction.respond({
+			type: InteractionResponseType.ChannelMessageWithSource,
+			data: { content: "Hello", allowed_mentions: { parse: [] } },
+		});
+});
+await client.connect();
+// client.close() aborts transport work and clears the session and caches.
+```
+
+Construction and imports open no connections. The engine never reads a token from the environment. Request bodies preserve snake_case fields and native discord-api-types/v10 types. `message.data` is an APIMessage; `interaction.data` is an APIInteraction. `message.reply` supplies a message_reference while preserving native reference options. `interaction.respond` accepts a complete native callback body.
+
+The logging helpers share the framework's level, JSON/text, redaction and stack
+settings; see [console logging](console-logging.md). The supplied `onError`
+callback still receives the original error. Add fixed operation wording to the
+record rather than printing arbitrary provider messages.
+
+## Cache contract
+
+| Cache                | Default | Lookup                               | Retention              |
+| -------------------- | ------- | ------------------------------------ | ---------------------- |
+| Guild metadata       | On      | `cache.guilds.get(id)`               | Until removal/reset    |
+| Channels and threads | On      | `cache.channels.get(id)`             | Until removal/reset    |
+| Roles                | On      | `cache.roles.get(guildId, id)`       | Until removal/reset    |
+| Members              | On      | `cache.members.get(guildId, userId)` | LRU, 1,000 per guild   |
+| Messages             | Off     | `cache.messages.get(channelId, id)`  | Opt-in LRU per channel |
+
+Members have **no combined client limit**. `membersPerGuild` accepts a nonnegative integer or a function of guild ID. Zero disables storage. `guilds`, `channels` and `roles` accept false. `messagesPerChannel` opts into a finite per-channel limit. A synchronous `policy({ kind, id, scope, data })` can reject admission; false also removes an existing entry. A thrown policy error stops the client and clears state instead of continuing after a partly applied transaction. Custom backends are deferred.
+
+Results are undefined or a `$CacheEntry<T>` with complete and data. Patches create `complete: false`; accumulated partial fields never promote it. A full typed put, full gateway creation/chunk, or explicit REST fetch can promote it in place. Guild entries intentionally remain partial metadata: bulk members, channels, roles, presences and voice states live separately. This avoids retaining a second unbounded member snapshot inside the guild.
+
+Resident entry and data identities remain stable during updates. Nested objects merge; omitted/undefined fields remain; explicit null replaces; arrays replace old contents, so `roles: []` removes membership. Identity ends at eviction, deletion, fresh identification or close. Treat cached objects as engine-owned mutable views; use structuredClone when you need a snapshot.
+
+Targeted get, writes and gateway activity update LRU recency. Peek, has, values, entries and iteration do not. Activity discovery follows nested member payloads, guild-scoped user/author IDs, resolved member maps, mentioned users and member/user ID lists. Messages, commands, buttons, reactions, typing and voice payloads participate without an event-name whitelist. Future shapes without recognizable guild/member identity require an explicit cache call or adapter.
+
+Deletion removes data before handlers. `cacheDelete` supplies the original dispatch in payload and previous when resident. Missing entries yield undefined; partial previous entries remain partial. Bulk message deletion finishes all removals before any deletion handler. Guild removal clears resident children. An unavailable guild remains marked unavailable and invalidates its member scope. Role deletion removes its ID from resident member role arrays without touching recency.
+
+`fetchMember`, `fetchChannel` and `fetchMessage` are explicit HTTP operations; cache lookup never fetches. A fetch writes back only if no gateway dispatch or session reset occurred while pending. Otherwise it returns the HTTP snapshot without overwriting newer gateway state. This conservative rule avoids resurrecting deleted entries, but may skip insertion during unrelated activity.
+
+## Ordering and failures
+
+Each EngineClient owns one shard. Decoding, cache mutation and event invocation run synchronously in arrival order. Promise-returning handlers overlap; later cache processing does not await them. A live object's fields can change across await. Synchronous CPU-heavy user code still blocks Bun's event loop.
+
+Events are ready, resumed, messageCreate, messageUpdate, interactionCreate, cacheDelete, dispatch and gatewayState. Raw dispatch follows specialized callbacks and sees updated cache. On returns an unsubscribe function. Handler exceptions/rejections go to onError without stopping later handlers. The default ceiling is 1,024 outstanding handler promises. Overflow reports a fatal error and closes the client instead of retaining unbounded work. Closing does not await or cancel developer promises; idle is available when they are known to settle.
+
+Gateway ownership includes HELLO/session timeouts, jittered heartbeats, requested beats, ACK debt, reconnect backoff, session ID/sequence/resume URL, stale-generation rejection and cleanup. Fresh identification clears state; resume preserves it. Fatal close codes stop retries. Defaults: 10 reconnect attempts, 15-second handshake deadline, 8 MiB input frames, and capped exponential reconnect delays with jitter. Uncompressed v10 JSON needs no async decoding queue. Runtime validation covers the envelope/session fields, not every entity schema.
+
+REST admits up to 8 concurrent attempts. Identical normalized routes and learned bucket hashes serialize within each channel/guild/webhook major partition; independent routes progress concurrently. Cooldowns apply before admitting more attempts. The bound is 1,024 logical requests, including retry delays. Each attempt has a 15-second timeout and an 8 MiB response limit. Rate-limit metadata is bounded independently; exhausting it while cooldowns remain active fails explicitly.
+
+429 handling uses retry_after or Retry-After with a separate retry ceiling of 5. Transport and 5xx failures retry GET/PUT/DELETE at most twice. POST/PATCH are not replayed after ambiguous failure. Interaction initial responses cannot race; ambiguity leaves replyState unknown. JSON bodies are snapshotted on submission. Redirects are rejected and endpoints require TLS except loopback tests. Client/transport token fields are private and absent from ordinary JSON serialization.
+
+## Validation results
+
+Historical validation on 2026-10-11 used Bun 1.4.2 on Windows x64 and a disposable Redis 7.4.11 container:
+
+- `bun install --frozen-lockfile --ignore-scripts`: succeeded without lock changes.
+- `bun run engine:test`: 76 passing tests across four files, 279 assertions.
+- `bun scripts/ci.ts` with `RILO_TEST_REDIS_URL`: 2,361 passing tests across 226 files, 4,943 assertions, zero failures and zero skipped tests.
+- The same CI run passed type checking, the lint and formatting checks configured at the time, the existing offline framework example, the engine offline example and `bun run smoke`.
+- The smoke test packed and installed the package in a temporary consumer, audited public exports/notices, loaded a framework command and ran the native engine connect/reply/resume example.
+
+Engine coverage comprises 14 cache tests, 11 client/event/helper tests, 28 gateway/protocol/identify tests and 23 REST tests. They exercise partial/null updates, resident identity, LRU boundaries and recency, deletion ordering, concurrent handlers, fetch/delete races, heartbeat debt, disconnect/resume/session invalidation, malformed/premature frames, stale sockets, cleanup, rate limits, bounded retries, cancellation and request limits.
+
+The live example was checked without `--live`. No real Discord token was retrieved and no live bot connection or Discord message was sent.
+
+## Protocol and architectural references
+
+Reviewed on 2026-10-11:
+
+- [Gateway lifecycle](https://docs.discord.com/developers/events/gateway): discovery, HELLO, heartbeat/ACK, identify, resume URLs, sequences and session budgets.
+- [Gateway events](https://docs.discord.com/developers/events/gateway-events) and [close codes](https://docs.discord.com/developers/topics/opcodes-and-status-codes): payloads and recoverable/fatal closures.
+- [Rate limits](https://docs.discord.com/developers/topics/rate-limits): bucket hashes, major resources, fractional resets and global 429 handling.
+- [Message resource](https://docs.discord.com/developers/resources/message) and [interaction responses](https://docs.discord.com/developers/interactions/receiving-and-responding): native body fields and callback endpoints.
+- [discord-api-types 0.38.56](https://github.com/discordjs/discord-api-types/releases/tag/0.38.56): checked against public npm latest and pinned exactly in package.json and bun.lock.
+
+`$MessageUpdateData` conservatively permits omitted native update fields with Partial plus required id/channel_id. Version 0.38.56 declares the create fields required for updates. This engine retains the agreed partial-update contract without renaming or reinterpreting fields.
+
+The Ovencord checkout was read only. Package boundaries, WebSocketShard/identify strategies, REST SequentialHandler's bucket/major/global separation, and CachedManager's resident patching boundary informed the review. Its source, Collection abstraction, compatibility API and benchmark claims were not copied. Rilo uses its own Map/Set stores, scheduler, lifecycle and helpers.
+
+## Production gaps
+
+- A real bot session needs explicit approval. Extended reconnect soak tests and large real guild payloads remain untested; this milestone uses deterministic mocks and local servers.
+- One shard per client is supported. The local identify budget cannot account for other processes or persist session starts across restarts. Supply waitForIdentify when sharing a token and integrate the existing Rilo coordinator.
+- Add full payload validation and broader cache projections. Reaction counts, user updates across every guild, thread membership and ancillary guild collections still need reconciliation. This is not complete Discord cache coverage.
+- Add compression, multipart uploads, additional typed endpoints, proactive global pacing, route-specific sublimits, retry telemetry and deadline-aware prioritization. Different routes can be coalesced only after headers reveal their shared bucket.
+- Interaction callbacks share the bounded REST scheduler. Respond or defer promptly to meet Discord's initial-response deadline; automatic deferral, follow-up helpers and deadline reservation remain future work.
+- Profile real traces before changing policy. Activity traversal, cache misses and JSON parsing need realistic workload evaluation.
+
+## Future Rilo integration
+
+1. Introduce engine-facing command/listener contexts using native payloads and thin helpers, then test adapters for current framework contracts.
+2. Replace discord.js-specific permission, resolver, collector, pagination and registration dependencies at explicit boundaries without building a compatibility clone.
+3. Wire ShardLink.waitForIdentify, shard readiness and cleanup into EngineClient's injected permits and state hooks.
+4. Port extensions and example bots with contract tests before changing RiloClient's runtime and retiring discord.js dependencies.
+
+The independent subpath is deliberate. The root API baseline stays intact, and a test verifies that this engine and the existing offline RiloClient coexist without changing the framework container.

package/docs/sharding-recovery.md

@@ -0,0 +1,163 @@
+# Shard maintenance, leases and recovery
+
+Each shard runs in its own Bun OS process. A `ShardManager` supervises its local
+children and proxies their authenticated coordinator traffic. A child receives
+only its own assignment and total count: no peer list, peer connections or
+dependency on another shard's arrival. Coordination is entirely in memory.
+There are no ownership files, state directories or persistent locks.
+
+Fixed shard totals remain the default. Opt-in [automatic scaling](sharding-scaling.md)
+retains its five-minute polling, three matching decisions and thirty-minute
+cooldown defaults.
+
+## Maintenance and bounded calls
+
+A managed client starts with `client.maintenance === true`. A detected coordinator
+connection loss immediately sets it back to `true` and keeps the existing Discord
+session open. Socket closure is detected directly; a silent partition uses the
+existing fifteen-second heartbeat deadline. Parent/child IPC heartbeats continue
+through coordinator outages. Unmanaged clients default to `maintenance = false`.
+
+Only authenticated control, an accepted lease, local assignment application and
+coordinator registration clear maintenance. Opening a socket or receiving a
+welcome is insufficient. Rilo does not install a command policy or send outage
+replies: developers choose the response appropriate to each operation.
+
+```ts
+if (client.maintenance) {
+	return interaction.reply(
+		"Coordination is temporarily unavailable. Try again shortly.",
+	);
+}
+```
+
+Ordinary requests fail with `DISCONNECTED` while the local assignment is
+unreconciled. Each request or broadcast can opt into bounded waiting:
+
+```ts
+const result = await client.sharding.request(0, "exampleStats", null, {
+	waitForCoordinator: true,
+	timeoutMs: 5000,
+	signal: controller.signal,
+});
+```
+
+The timeout includes waiting and execution; broadcasts share one overall deadline
+across all targets. The default is `limits.timeoutMs` (15 seconds). Waits are
+bounded by `limits.maxPending`, respect cancellation and return `TIMEOUT` or
+`CAPACITY` instead of building an unlimited queue. Already dispatched calls fail
+on disconnect and are never replayed. Waiting does not guarantee a destination
+is available: routing can still return `UNAVAILABLE`, or `RESHARDING` during an
+automatic scaling drain. Host manager calls support the same options.
+
+Discord IDENTIFY still requires a coordinator permit. Control loss during a
+permit wait waits for reconciliation within the shard's outage lifetime;
+permit queue deadlines and exhausted allowance remain explicit failures.
+An existing Discord session does not authorize new IDENTIFY calls offline.
+
+## Leases and dormant processes
+
+The coordinator maintains slots `0..shardCount - 1`. `workers[].shards` provide
+initial placement preferences; leases determine actual ownership. `maxShards`
+bounds new allocations per host, defaulting to its initial preference count
+in fixed mode. Valid returning IDs are retained even if the host's configured
+capacity was reduced during the outage. Allocation and lease installation are atomic, authenticated by
+host credentials, supervisor instance and child generation. Duplicate sockets
+for the same supervisor instance are refused. Different authenticated instances
+can connect independently to reconcile their children or wait dormant.
+
+A new/restarted process must obtain a valid assignment before opening Discord.
+A returning process reports its previous ID. If valid and free, or already
+reserved for that exact process, it keeps that ID. An invalid or taken ID is
+refused: the child closes any old Discord session, forgets its ID
+(`client.sharding.id === null`), warns clearly and becomes dormant. New processes
+without capacity behave the same way.
+
+Dormant children stay alive indefinitely with no Discord connection. They request
+an assignment every `assignmentPollIntervalMs` (default 30,000), and open Discord
+only after acceptance. Repeated full-capacity polls do not repeat the warning.
+`client.login()` and transport-only `client.sharding.connect()` intentionally wait
+for the first assignment. Ordinary coordinator RPC calls retain deadlines.
+
+The host normally starts one child per initial placement. Optional `processCount`
+sets a minimum local pool, including standby processes, within host capacity.
+Scaling may require more children up to that capacity. Surviving processes are
+reconciled independently, including IDs removed by a restarted coordinator.
+
+`manager.processes` exposes a stable local `slot`, nullable leased `shard`, PID,
+restart count and state. States include `maintenance` and `dormant`, alongside
+`starting`, `running`, `backoff`, `failed` and `stopped`. Local slots are not
+Discord shard IDs. Dormant clients remain in maintenance.
+
+## Gateway changes and process lifetime
+
+Recovery with the same ID and total preserves the Discord session. If the total
+changed, the child closes its old gateway and reconnects with the accepted ID
+and current total, even when the numerical ID is unchanged. RiloClient, modules
+and application listeners stay alive. Assignment changes reset gateway resume
+data and guild/channel/user caches. Extension login hooks run once per client;
+Discord ready events may repeat. The gateway adapter targets discord.js 14.
+
+A lost connection never releases a lease during the current coordinator lifetime.
+Network loss is not proof of death. The owning supervisor must confirm the child
+exited, including after reconnect, or release it after graceful shutdown/scaling.
+Only then can an idle process acquire the slot. Another instance or generation
+cannot release it. Lost first-lease replies and confirmed-exit acknowledgements
+can be retried without stealing or releasing a replacement's assignment.
+
+An assigned child has `maxDisconnectedLifetimeMs` (default 900,000: fifteen
+minutes) to reconnect and reconcile. Failed connections, welcomes and failed
+reconciliations never reset that timer. Success resets it for a future outage.
+Expiry closes down and terminates the **entire shard process**; the existing host
+restart/backoff policy applies. The host also bounds a stalled child's shutdown.
+Dormant processes are exempt once their old Discord session is closed.
+
+```ts
+new ShardManager({
+	id: "local",
+	url,
+	token,
+	script,
+	assignmentPollIntervalMs: 30_000,
+	maxDisconnectedLifetimeMs: 15 * 60_000,
+});
+```
+
+Polling accepts 50..300,000 ms; the outage lifetime accepts 1..2,147,483,647 ms.
+`startupTimeoutMs` separately bounds boot, lease and local gateway application.
+A gateway that cannot close/reconfigure is a process failure. `shutdownTimeoutMs`
+bounds graceful exit. `reconnect: false` explicitly opts out of recovery and
+stops children on loss. Hosts may start before the coordinator and retry with
+capped backoff; closing the manager cancels the wait.
+
+Parent IPC loss still terminates a responsive child, since it cannot reconnect
+to a dead parent. Supervise each host's whole process tree. A new supervisor
+instance cannot prove the old children died merely by presenting the same host
+credentials. Their leases remain reserved for that coordinator lifetime; a
+coordinator restart rebuilds the pool. No PID discovery or disk cleanup occurs.
+
+## Coordinator restart tradeoff
+
+Restart rebuilds zero-based slots from the currently required count (configured,
+or the automatic scaling startup recommendation). Arrivals are admitted
+independently, with **no global reconciliation grace period**.
+
+An old partitioned Discord session may overlap a newly assigned replacement
+until the old process reconnects or reaches its configured outage cutoff. If its
+ID is taken on return, it closes Discord and becomes dormant. This policy cannot
+promise zero duplicate processing or exactly-once delivery. A wedged process
+needs host/service supervision to enforce termination. Run one coordinator per
+bot; independent coordinators are not fenced from each other.
+
+Use `botToken` in production. Each coordinator start waits 5.5 seconds before
+fetching fresh `GET /gateway/bot` limits. This is an IDENTIFY cooldown, not a
+reconciliation grace period. Permits are charged before sending and never refunded
+on loss. An unexpired allowance cannot increase. `sessionStartLimit` is the
+manual/offline alternative and needs a fresh snapshot on every start and expiry.
+Restarting Rilo does not reset Discord's allowance.
+
+Upgrade coordinator, hosts and children together: the internal protocol changed.
+Restart running processes deliberately to load the new version. `statePath`,
+`stateDirectory`, `releaseWorker`, `SHARD_STATE_PATH` and `SHARD_HOST_STATE_DIR`
+remain removed. Legacy state files stay ignored and unused. See
+[breaking changes](../BREAKING_CHANGES.md) and [examples](../examples/README.md).

package/docs/sharding-scaling.md

@@ -0,0 +1,197 @@
+# Automatic shard deployment
+
+Automatic scaling is **off by default**. Without `scaling`, `shardCount` and
+`workers[].shards` remain fixed and metadata is fetched only at startup or when
+the identify allowance expires. Enable scaling on the coordinator; hosts run
+the same `ShardManager` and bot entrypoint.
+
+## Coordinator configuration
+
+```ts
+import { ShardCoordinator } from "rilo/sharding";
+
+const coordinator = new ShardCoordinator({
+	shardCount: 2,
+	workers: [
+		{
+			id: "a",
+			token: process.env.HOST_A_SECRET!,
+			shards: [0],
+			maxShards: 4,
+			weight: 2,
+		},
+		{
+			id: "b",
+			token: process.env.HOST_B_SECRET!,
+			shards: [1],
+			maxShards: 2,
+			weight: 1,
+		},
+	],
+	botToken: process.env.DISCORD_TOKEN!,
+	scaling: {
+		minShards: 2,
+		maxShards: 6,
+		targetGuildsPerShard: 1000,
+		pollIntervalMs: 300000,
+		cooldownMs: 1800000,
+		confirmations: 3,
+		allowDownscale: true,
+		rebalanceThreshold: 0.25,
+		sessionReserve: 10,
+		drainTimeoutMs: 30000,
+		readyTimeoutMs: 300000,
+	},
+});
+await coordinator.start();
+```
+
+Keep credentials in your environment. Remote hosts need the normal TLS
+configuration. This policy uses only configured hosts that are already running;
+it never provisions machines, changes server settings or purchases capacity.
+Every automatic host needs `maxShards`, including standby hosts with `shards: []`.
+Initial assignments must cover `0..shardCount-1` exactly once and fit host capacity.
+
+On startup, fresh Discord metadata, bounds and capacities determine the initial
+assignment before hosts connect. `shardCount` is an initial configuration seed,
+not a fixed count in automatic mode. No previous topology, guild counts,
+confirmation history, cooldown or allowance is restored from disk. Set
+`minShards` to retain an operational floor across coordinator restarts.
+
+| Setting                | Default        | Meaning                                                                |
+| ---------------------- | -------------- | ---------------------------------------------------------------------- |
+| `maxShards`            | Required       | Global ceiling, 1–4096, also bounded by summed host capacity           |
+| `minShards`            | `1`            | Minimum total, at most `maxShards`                                     |
+| `targetGuildsPerShard` | Disabled (`0`) | Optional average target, 1–2500; requires accurate guild caches        |
+| `pollIntervalMs`       | `300000`       | Metadata polling interval, 60000–86400000 ms                           |
+| `cooldownMs`           | `1800000`      | Minimum interval between transition attempts, 60000–604800000 ms       |
+| `confirmations`        | `3`            | Consecutive matching plans before a running deployment changes, 1–100  |
+| `allowDownscale`       | `true`         | Allow fewer shards after confirmation and cooldown                     |
+| `rebalanceThreshold`   | `0.25`         | Required improvement in peak weighted host guild load, 0.05–1          |
+| `sessionReserve`       | `0`            | Unspent identify allowance to retain beyond the transition requirement |
+| `drainTimeoutMs`       | `30000`        | Time for every host to confirm old process exits, 100–300000 ms        |
+| `readyTimeoutMs`       | `300000`       | Time for the new deployment to become gateway-ready, 100–3600000 ms    |
+| Host `maxShards`       | Required       | Maximum shard processes on this host, 1–4096                           |
+| Host `weight`          | `1`            | Relative resource capacity, 0.01–1000; set it from your host sizing    |
+
+## What Discord controls
+
+Discord does not send a push event requesting a particular scale-up or
+scale-down. The coordinator polls `GET /gateway/bot` for the recommended shard
+count and fresh session-start metadata. Discord assigns guilds by
+`(guild_id >> 22) % num_shards`; the framework cannot choose individual guilds or
+move one guild to another shard independently. See the official
+[Gateway sharding and session-start documentation](https://docs.discord.com/developers/events/gateway#sharding).
+
+The desired count is the maximum of the recommendation, configured minimum and
+`ceil(totalCachedGuilds / targetGuildsPerShard)` when that target is enabled.
+Counts round up to multiples of the current recommendation, a conservative
+choice compatible with Discord's large-bot shard-count multiple requirement.
+This can overprovision compared with using arbitrary shard totals. The largest
+legal count within configured capacity is used if the guild target cannot fit;
+a recommendation or minimum that cannot fit blocks the change with
+`SCALING_CAPACITY`. The recommendation is a floor, not an automatic instruction
+to remove a particular existing shard.
+
+Guild targets are averages, not a guarantee that every shard has that many
+guilds. Discord's per-shard limit still applies. Uneven guild sizes, unavailable
+guilds and custom caches affect the usefulness of guild counts. Keep the Guilds
+intent and a complete guild cache if using guild targets. This is not CPU,
+memory, member-count or event-volume monitoring.
+
+For an unchanged total, allocation greedily places entire shards using observed
+guild counts and host weights, while respecting per-host process limits.
+Existing owners win equal-load ties. An allocation-only change requires the
+configured improvement in peak weighted load. For a new total, individual shard
+guild counts are unknown until login, so allocation uses equal estimated loads.
+A later poll can rebalance hosts if the measured distribution warrants it.
+
+## Transition and recovery
+
+1. Fetch fresh metadata and apply the existing conservative identify accounting.
+   All configured hosts must be connected, including standby hosts. Shrinking,
+   guild-target changes and allocation-only balancing require every shard to
+   report gateway readiness and metrics no older than 15 seconds. A larger
+   Discord recommendation may grow an unready topology to repair insufficient
+   sharding. A degraded committed deployment must recover before another change.
+2. Require repeated matching plans and the cooldown. Before disrupting children,
+   require unexpired remaining session starts of at least
+   `max(currentCount, proposedCount) + sessionReserve`. The larger count covers
+   either deployment or a pre-commit rollback. Insufficient budget defers the
+   change without stopping healthy children.
+3. Reject pending/new shard RPC and identify work with `RESHARDING`. Ask all hosts
+   to drain. Each host cancels scheduled restarts, requests graceful shutdown,
+   escalates only its own children if necessary, and confirms actual process
+   exits. This interrupts bot availability and cancels in-flight work; application
+   jobs must tolerate restarts. Even allocation-only changes restart all shards.
+4. If a host disconnects or draining times out before commit, retain the old
+   total and assignment. Still-connected hosts receive that assignment after
+   their drains finish; reconnecting hosts receive it in their welcome. An
+   unconfirmed child exit cannot authorize a replacement.
+5. Once every old process is confirmed stopped, commit the new count and
+   assignment in memory and start fresh children. After this point recovery
+   moves forward: reconnecting hosts receive the committed topology. There is
+   no rollback to a different total while new children are running.
+6. Wait for gateway readiness. Failed startup/readiness leaves status
+   `degraded`; ordinary configured process retries and host reconnection continue.
+   Once all shards recover, status becomes `idle` automatically. Exhausted
+   restart attempts, disabled restart, or application errors require correction
+   and replacement/restart of the affected supervisor. No state-file cleanup is
+   required.
+
+Every IDENTIFY still uses the central `shardId % max_concurrency` bucket and
+5.5-second cooldown. Permits are charged before delivery and never refunded.
+Fresh metadata cannot increase an unexpired in-memory allowance. RESUME remains
+discord.js behavior; this feature does not bypass Discord rate limits or alter
+retry policy. Crashes during startup can consume additional session starts and
+leave the deployment waiting for a fresh allowance. Choose host
+`identifyTimeoutMs` and coordinator `readyTimeoutMs` for your total, concurrency,
+startup time and possible retries; a large serial deployment can exceed defaults.
+
+Automatic totals must also fit `limits.maxPending` (default 256) so the control
+plane has room for startup identifies. Welcome and assignment frames must fit
+`limits.maxBytes`; these checks happen before draining. Increase these bounded
+limits deliberately when sizing a larger deployment. Host `identifyTimeoutMs`
+is capped at 300000 ms. If the serial login queue cannot fit that deadline with
+the bot's Discord concurrency, this deployment model cannot start the whole
+topology reliably; more machines do not increase Discord concurrency.
+
+Closing the coordinator aborts metadata requests and transition waits, closes
+connections, and cancels polling. Surviving children keep Discord open in
+maintenance while their hosts reconnect and reconcile individual leases. A
+changed total closes the old gateway before a new session opens, even for the
+same ID. Rejected IDs become dormant. Explicit scaling transitions still confirm
+child exits and release leases before committing the new topology; reservations
+belonging to disconnected instances block that transition.
+
+The [process lifetime limitations](sharding-recovery.md) still apply: run one
+coordinator per bot and supervise host process trees. There is no global grace
+period on coordinator restart. A partitioned old Discord session can overlap a
+replacement until it reconnects or reaches the configured outage cutoff.
+
+## Observability and compatibility
+
+`coordinator.shardCount` exposes the current committed total.
+`coordinator.scalingStatus` is a copied snapshot with `phase`
+(`disabled`, `idle`, `draining`, `starting` or `degraded`), `shardCount`, and optional
+`reason`/`targetShards`. `await coordinator.checkScaling()` requests one immediate
+evaluation; simultaneous calls share one promise and still respect confirmation,
+cooldown, readiness and allowance checks. Periodic checks continue automatically.
+
+Structured logs emit `scaling_status`, `scaling_failed` and host `reassigned`
+events. Ordinary waiting/stable reasons are logged only when status changes.
+Use `RILO_LOG_FORMAT=json` for full context. Logs contain counts and host IDs,
+not guild IDs, tokens or application payloads.
+
+Upgrade coordinator, hosts and children together. The internal transport adds
+drain, assignment and bounded metrics frames; mixed framework versions are not
+supported. Metrics distinguish IPC boot from actual gateway readiness.
+Public logger customization, fixed totals and existing message APIs remain
+available. Initial host placements are preferences; per-process leases control
+ownership. In automatic mode, callers must tolerate `RESHARDING` and total-count
+changes during requests/broadcasts. No ownership database, directory or lock is
+introduced.
+
+See [the runnable example configuration](../examples/README.md#automatic-scaling).
+Regression tests use synthetic gateway metadata and real local Bun processes;
+they never log in to Discord.

package/docs/sharding-stats.md

@@ -0,0 +1,121 @@
+# Live shard statistics
+
+Use `this.container.sharding.stats()` inside a command, listener or service to ask
+every configured shard for its current stats. `client.sharding.stats()` and
+`manager.stats()` provide the same API. No application handler registration is needed.
+
+```ts
+const results = await this.container.sharding.stats();
+for (const [shard, result] of results) {
+	if (result.ok) {
+		this.container.logger.notif(
+			`Shard ${shard}: ${result.value.guilds} cached guilds`,
+		);
+	} else {
+		this.container.logger.alert(`Shard ${shard}: ${result.error.code}`);
+	}
+}
+
+// A specific shard still returns a map, with exactly one entry.
+const one = await this.container.sharding.stats(0, { timeoutMs: 5000 });
+const shardZero = one.get(0);
+```
+
+The return type is `Promise<ReadonlyMap<number, ShardStatsResult>>`. Import
+`ShardStats`, `ShardStatsResult` and `ShardCallOptions` from `rilo` or
+`rilo/sharding`. Entries follow the existing request result shape: `{ shard,
+ok: true, value }` or `{ shard, ok: false, error }`. Errors are frozen `ShardError`
+copies with a `code` and `message`; a failed entry has no `value` property.
+
+## Freshness and scope
+
+Every call makes new requests through the coordinator, including a request to
+the caller's own shard. The destination reads its client and process state only
+when that request arrives. Stats never use the coordinator's periodic scaling
+metrics, an earlier successful result, or a local shortcut as a fallback.
+The private request name `rilo:stats` is reserved and cannot be registered with
+`handle()`.
+
+Without an ID, the target set is `0..shardCount - 1` from the caller's reconciled
+assignment when collection begins. It includes unavailable IDs. Passing an ID
+selects only that shard; an invalid or out-of-range ID rejects with `TARGET`.
+Dormant process slots are not shard IDs. A topology change during collection can
+produce failures; call again after reconciliation to sample the new topology.
+
+Samples are fresh observations, not a simultaneous cross-process snapshot. State
+can change after a shard replies. `sampledAt` is Unix milliseconds on that shard's
+clock, so differences between hosts can include clock skew. Successful entries
+remain useful even when other shards fail; totals computed from them are partial.
+
+The returned map has the read methods and iteration behavior of `ReadonlyMap`,
+with no `set`, `delete` or `clear` methods. The map, entries, samples, nested memory
+objects and errors are frozen. They are detached from live internals and will
+not change after you receive them. The read-only map is a view over private
+storage, not a mutable JavaScript `Map` instance. It is iterable; use
+`[...results]` when you need an array. JSON serialization of errors should copy
+their `code` and `message` explicitly.
+
+## Deadlines and failures
+
+The optional second argument accepts the usual `ShardCallOptions`:
+
+```ts
+const results = await client.sharding.stats(undefined, {
+	timeoutMs: 5000,
+	waitForCoordinator: true,
+	signal: controller.signal,
+});
+```
+
+One deadline covers coordinator waiting and the whole collection, including
+queued targets. It defaults to the coordinator's `limits.timeoutMs` (15 seconds),
+and accepts 1..300000 milliseconds. At most eight requests are in flight for one
+collection, also subject to the existing client, host and coordinator pending
+limits. A target still queued when the budget runs out receives `TIMEOUT`
+without being dispatched. Late replies are ignored and never update a completed
+map. A reply received after the budget expires is a timeout, even if it has metrics.
+
+Before collection starts, invalid options or a locally unavailable coordinator
+reject the promise. By default, maintenance and unmanaged clients reject with
+`DISCONNECTED`; a closed client or host rejects with `CLOSED`. Opting into
+`waitForCoordinator` waits within the same deadline and can reject with `TIMEOUT`,
+`CAPACITY` or the supplied abort signal's reason. No local or cached stats are
+returned while waiting. A connected host can still have children reconciling;
+those destinations remain unavailable until their registration completes.
+
+Once collection starts, failures become individual map entries:
+
+| Code           | What happened                                                            |
+| -------------- | ------------------------------------------------------------------------ |
+| `UNAVAILABLE`  | The shard has no ready route, has exited, or has no stats provider.      |
+| `TIMEOUT`      | The overall budget ran out before a usable reply arrived.                |
+| `DISCONNECTED` | A required coordinator or host connection was lost.                      |
+| `CAPACITY`     | A client, host, coordinator or destination handler limit was reached.    |
+| `RESHARDING`   | The deployment is draining for a topology change.                        |
+| `ABORTED`      | The caller cancelled collection. Already completed entries are retained. |
+| `PROTOCOL`     | A responding shard returned a malformed stats sample.                    |
+| `HANDLER`      | The destination's sampler threw an error.                                |
+
+Other transport error codes can also appear. Failed entries contain no metrics:
+an unavailable shard does not mean zero guilds, zero memory or a disconnected
+Discord session. Calls already sent are never replayed after reconnection.
+Collection does not change leases, maintenance, gateway sessions or dormant
+process behavior. See [maintenance and recovery](sharding-recovery.md).
+
+## Sample fields
+
+| Field                         | Meaning                                                                                                          |
+| ----------------------------- | ---------------------------------------------------------------------------------------------------------------- |
+| `sampledAt`                   | Shard wall-clock sampling time, in Unix milliseconds.                                                            |
+| `ready`                       | Whether the shard's Discord client is ready right now.                                                           |
+| `guilds`, `users`, `channels` | Current local cache sizes. Users may appear on multiple shards.                                                  |
+| `pingMs`                      | Most recent gateway heartbeat latency, or `null` before a measurement exists. This doesn't send a new heartbeat. |
+| `uptimeMs`                    | Milliseconds since the client last became ready, or `null` while it isn't ready.                                 |
+| `pid`                         | Process ID on that shard's host.                                                                                 |
+| `processUptimeMs`             | Milliseconds since the Bun process started.                                                                      |
+| `memory`                      | Process memory usage in bytes: `rss`, `heapTotal`, `heapUsed`, `external`, `arrayBuffers`. These values overlap. |
+
+Cache counts depend on intents, cache configuration and received events; they
+aren't a fresh Discord REST census. A process can answer stats while its Discord
+client is not ready. That is a successful sample with `ready: false`, distinct
+from a shard that cannot answer at all.