Inspect an Instance

An instance can be observed through its chart-typed client or through committed storage. Choose the authority that owns the question. A convenient API is not a reason to blur current state, retained history, operational status, and commands into one ambiguous “inspect” operation.

Choose by authority, not convenience

The first three rows begin with an authored chart and one instance ID. The fourth begins with storage identity and can cross instances or chart versions. The last row changes the world and belongs on the other side of the boundary.

A typed client begins with chart meaning

TicketChart.client constructs a chart-typed address for one root instance. Construction does not start the instance. snapshot, changes, read, observe, awaitPresent, awaitTerminal, and timeline observe through the selected engine; they do not birth an instance that has no committed head. Until the command path establishes birth, current observation fails with InstanceNotStarted.

Use the client when the chart itself should shape the answer:

• snapshot acquires one decoded current Snapshot.
• changes publishes that current Snapshot first, then each later committed Snapshot.
• read(selection) and observe(selection) preserve state-owned projection and honest Option absence.
• awaitPresent(perspective) and awaitTerminal wait for chart-typed lifecycle facts.
• timeline({ fromSeq, limit }) pages one instance's retained macrosteps in ascending sequence.

The client is still more than a read surface. start, send, and interrupt are explicit commands. Keeping those names visible is safer than handing an operator UI a generic client and pretending the whole object is read-only.

For the exact current-first and paging contracts, see Client Reads & Timeline. For state-owned projection, see Selections & Perspectives.

Committed inspection begins with storage identity

StatechartInspect reads committed storage without chart registration, engine admission, mailbox entry, folding, or mutation. Its seven projections remain separate because they answer separate operational questions:

• headCheckpoint — current committed head for one instance, as Option;
• historyCheckpoints — retained historical checkpoints;
• steps — retained immutable macrosteps and their provenance;
• outboxPending — planned external intents not yet terminally settled;
• parkJournal — the append-only operational incident record;
• instancesByStatus — fleet-wide stored heads filtered by operational status; and
• getVersion — hash-qualified registered chart geometry.

Use inspection when the caller is an operator, indexer, incident tool, or fleet view whose authority is storage rather than one imported chart type. No inspection read starts an instance, settles an outbox row, redrives work, changes Park disposition, or sends an event.

The full projection and provenance contracts live in Committed Inspection & Provenance.

Coordinate reads with sequence

Every operation is committed-as-of its own read. Effect.all may issue several reads together, but it does not turn them into one storage transaction. Another macrostep can commit between any two answers.

Compare chart name, instance ID, and sequence before combining facts. Resolve chartHash before rendering geometry. If the head advances while a timeline page remains older, present that difference or retry under an owning consistency policy; do not silently merge the rows into a state that never existed.

Absence also has several meanings:

• Option.none() from headCheckpoint means no committed head row was found;
• an empty page means no retained rows matched that query;
• a sequence gap is evidence of retention, not evidence that nothing happened; and
• a typed storage, format, or owner-generation error means the read failed.

Do not collapse those outcomes into one empty object or “not found” banner.

Make derived views show their work

A diagram, incident panel, or timeline is a projection—not a new authority. Carry enough coordinates for the reader to challenge every claim:

• chart name, instance ID, and current sequence;
• chart hash for the geometry being rendered;
• retained lower and upper bounds when making a historical claim;
• operational status separately from domain configuration; and
• step provenance when explaining causation.

The view may organize those facts beautifully. It may not invent missing rows, infer causation from log timing, reinterpret parked as a domain State, or present current source code as the geometry of an older chart hash.

Stop reading when you mean rehearse

Inspection answers what committed. It does not answer what would happen if an event arrived, a Timer fired, or an Activity completed. That question belongs to the pure Simulator, where the starting Snapshot and injected stimulus are explicit values and no production instance can change.

Next, Provenance, Causation & Tracing follows exact durable causes across instance, child, Resource, and effect boundaries. For deterministic rehearsal instead, continue to Simulation & Trace.