Module shard 

The shard: one render, one journal, one task.

   business state changes
        |  wake()
        v
  +------------------------------------------------------+
  | the shard's task (woken, one per shard)               |
  |                                                       |
  |  1. logic.render(&mut builder)                        |
  |       -> the SHARED view + the PRIVATE overlays        |
  |          + the AUDIO relation                          |
  |  2. ops = plan(current view -> new view)               |
  |  3. version += 1, ops -> journal                       |
  |  4. publish the audio routing table                    |
  |  5. for each connection:                               |
  |       its observation changed? -> replan for it        |
  |       otherwise -> filter, splice, collapse, encode,   |
  |                    push, advance its committed state   |
  +------------------------------------------------------+

The rules this module must never break

1. A shard task never awaits IO.
2. The audio routing table is published before the views are pushed. A revoked route disappears immediately, which is always safe: cutting too early means hearing less than your due, never more. A granted route is inert until the receiver’s cursor catches up.
3. The committed state of a connection is a quadruplet - cursor, observation, overlay, offered actions - and the four only advance together, once the queue has accepted everything. This is what lets a lagging connection catch up naturally: the shared part replays from the journal, the private parts are recomputed from what was last accepted, so neither an overlay nor an action ever needs journalling.
4. An invalid render never replaces the current view: log it, keep the old one, and do not close anything.

REF: docs/design/guide-implementation.md 9

Structs

AttachedConnection

One connection attached to a shard, and its committed state.

Handover

Where a migrating connection’s held view is sent.

ReconcileReport

What one Shard::reconcile did. Everything an operator or a test needs.

Shard

A shard: unit of ownership, scheduling, rendering, id allocation and audio routing.

ShardHandle

The handle a flavor uses to say “my state changed”.

Enums

ActionTarget

What a context action was invoked on.

ShardCommand

A command for a shard’s task.

VoiceEvent

A voice-plane fact reported to the flavor.

Constants

MIN_INTERVAL

The floor between two publications.

Traits

ShardLogic

What a flavor writes.

Functions

run

Drive a shard until every handle to it is dropped.

spawn_parts

The handle and the driver halves for one shard.