Eve library

Chapter 3 · A command is not a sound · brief · 11 September 2026

Guide

Revision 1

On this page

The third chapter of the Tara · practise track, rewritten in the Eve edition on 11 September 2026. It follows the plan in EVE-V1-REDESIGN-TODOS.md and the track brief in tara-practise-track.md. The receipt is under verification/.

The job#

Chapter two ended on an audio floor of eighty per cent that no template lowers. This chapter is where that percentage — and the position, the progress and the listening time beside it — actually comes from.

The shared audio model keeps two phases, not one. A session phase says where the practice stands in eight steps; a playback phase says what the transport is reported to be doing in eight more. They move independently: loading tracks leaves a session ready while playback is still idle, and an interruption leaves the session paused while playback reads interrupted.

Two paths write to that record and they do not share rules. Commands go through a transition table of eighty phase-and-event combinations and refuse anything not in it. Engine updates bypass that table entirely: they can revise a completed session, emit a completion and an error from one update, and copy a raw position the seek path would have clamped.

And the one number that sounds like a measurement is the narrowest of all. TaraPlaybackEngineUpdate has eleven fields and none of them is a clock, so activeListenSeconds adds the host's own wall-clock time between two calls — Date.now() at this call minus the reading the previous call stored — and only when the previous playback phase was playing and the incoming report says playing. It never reads the media position, never multiplies by the rate, and never inspects whether anything was audible. Because the interval is the calling cadence, an executed run with reports two seconds apart accumulates four seconds of listening while the track advances two.

Running example. One 600-second practice. A call half a second after the last one jumps the position to 250 and adds half a second of listening; a buffering call a second later that still says playing adds one more; the recovery call after it adds nothing. The practice is interrupted, the caller decides whether ending the interruption resumes it, and the session finishes at 120 seconds with progress 0.2 and 1.5 seconds listened. Every value here is executed against the pinned source under a controlled host clock.

Three learning promises (the cover)#

  1. Two phases, moving independently, and a screen that reads only one of them will be wrong about the other.
  2. Commands and engine updates are separate paths, and only one of them respects the transition table.
  3. Listening time is wall clock between qualifying calls — not position, not rate, not attention.

Three things to remember (the close)#

  1. An accepted command is not an observed sound. The manager assigns state and emits an event before any adapter has called a player.
  2. Terminal is a command boundary, not a guarantee. An engine update can move a completed session to error.
  3. Nothing here saves anything. A snapshot is a value for a consumer that has to exist and does not yet.

Bridge. Chapter four — Tara ritual assembly and tone review: the moments a practice is assembled from before any of this runs.

Sections#

Four sections of six, five, six and six.

Section Slides
Two records, and what each says the case, the two phases, the handoff, identity, the media, the lifecycle
What a command may do the live phases, the ending phases, seek, the interruption branch, the feedback loop
What a report does to the record the priority order, position, listening time, the two completions, a late update, the markers
Sampling, listeners and the end marker sampling, subscriptions, snapshots, a throwing listener, replacement, the closing case

Treatment decisions#

  • Three recovery maps, one state machine. The plan turned all three into state machines. tara-audio-start became the whole command lifecycle in one diagram — preparing, ready, active, paused and a grouped terminal box — which leaves nothing for a second machine to draw. tara-audio-interrupt is the shouldResume branch, so it is a decision tree; tara-audio-replace-destroy is two operations against the same terminal outcome, so it is a card grid.
  • tara-audio-snapshots became a compare panel. Its rows already asked one question twice, of a shallow session copy against a scalar snapshot.
  • tara-audio-status-priority became a layer stack of five bands. It was planned as a card grid grown from three cards to five, one per playback label, because the order is the content and three cards had to group two of the five together. Five cards wrap to two rows and ran 97px past the 1280×720 budget; more to the point, a cascade is a precedence stack, and each band's boundary states exactly the condition that sends a report to the band below. The library already uses layer-stack for precedence in eve-policy-order.
  • Every case study carries three beats. Four fit at 1440 and run 6px past the narration chrome at 1280 — the Eve-edition .case-evidence list stacks rather than wrapping, so the fourth beat costs a full 88px row. The three chapter case studies that wanted a fourth (tara-audio-listening, tara-audio-marker-sampling, tara-audio-recovery) keep the fourth sample in their notes instead, where it reads as the extension it is.
  • No table. The eighty-combination command matrix is split across two card grids of four phases, as the plan asks. Chapter two's transition table already carries the library's one state-table-as-table, and a second adjacent one would teach the form rather than the content.

What this chapter does not establish#

No capture, and this is the one chapter in the track that has none. The shared audio model's only consumer is native, no pinned capture of that surface exists, and the web player from chapter one does not use this manager at all — so a capture here would have to show a screen the chapter is not about. The plan item that asks for one is left unchecked rather than satisfied by a picture that would mislead.

Nothing else, either: no persistence, no device, no audibility. The manager writes no store; a snapshot is eleven scalars handed to a consumer that has to exist. No native acceptance — the adapter is read in source and the linked native guide follows the actual mobile caller. And activeListenSeconds is a source measurement of qualifying wall-clock intervals, not a claim about attention, benefit or completion quality.