# Changelog All notable changes to this project will be documented in this file. The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html). Entries for unreleased work are not written here directly. Each issue drops a fragment in [`changelog.d/`](changelog.d/README.md); the fragments are assembled into a version section at release. See that README for the format and for when a change warrants an entry at all. ## [0.3.0] 2026-09-02 The ops surface arrives. `StatifierUI.Live` ships read-only LiveView components a host mounts over one trace stream, live or persisted; the Livebook inspector gains a scrubber that moves the diagram to any macrostep in the run; and `StatifierUI.Live.ExpressionInput` offers predicator's own grammar as completion, dropping into statifier_blocks' editor seam - which makes this the first release to ship JavaScript. Around them the trace wire format reserves `otel` for W3C Trace Context correlation, with a producer and an APM deep-link consumer on either side of it, gains per-attribute source spans on the identity tables, and `StatifierUI.Trace.Projection` redacts values out of a stream so a capture can travel without carrying any. ### Added - The Livebook inspector's diagram can be moved to any macrostep in the event log and back, pairing the two panes into a comprehension surface for one point in a run rather than only the live tip (sui-3gg). Four buttons above the diagram - **|< First**, **< Prev**, **Next >**, **Live** - drive it; the selected macrostep's entry in the log is opened and marked `- shown in the diagram`, and a note above the diagram names the point on screen. - `StatifierUI.EventLog.configuration_at/2` returns the configuration in force at a macrostep, distinguishing `{:quiescent, configuration}` from `{:carried, from, configuration}` (the macrostep never settled, so an earlier one's configuration is shown) and `:before_first`. A carried configuration is never presented as a measured one - which is what surfaces `sui-dc7`'s halting macrostep out loud instead of silently. - `StatifierUI.Inspector` gained the `:selection` option (`:live` or `{:macrostep, n}`), plus `points/1`, `step/3`, `resolution/2`, and `selection_note/2`. Every decision the scrubber makes lives here, so a LiveView or other host gets the same behaviour without Kino. - `StatifierUI.EventLog.Markdown.render/2` gained `:selected`, which suffixes one macrostep's summary with `- shown in the diagram`. Nothing here re-derives a configuration: every one it can show was stamped by the engine on a `trace.macrostep_stable`, and a caught-up stream got there through statifier ADR-0034 replay. Time travel is a read of replay output as data (ADR-0002's inherited clause), so selecting a macrostep neither touches the session nor needs anything new from the engine. - `StatifierUI.Trace.DeepLink` builds a URL into a host's APM backend from the wire format's `otel` correlation key (ADR-0013), the consuming half of the producer shipped with `sui-6e4`. The URL template is host configuration - `"https://apm.example.com/trace/{trace_id}?span={span_id}"`, with `{trace_id}`, `{span_id}`, `{session}`, and `{macrostep}` available and substituted values percent-encoded - because only the host knows which backend its spans went to. - `StatifierUI.EventLog.DeepLink`, the rendering seam over an `StatifierUI.EventLog.t()`: `from_opts/1` reads a renderer's `:deep_link` option, `for_macrostep/2` and `for_log/2` answer per macrostep, and `markdown/3` renders the inline Markdown link. - `StatifierUI.EventLog.Markdown.render/2` and every `StatifierUI.Inspector` fold take the same `:deep_link` option. A macrostep whose messages carry `otel` gets a `[trace](...)` link at the end of its event-log summary line, and `Inspector.selection_note/2` gains an `[open trace](...)` link for the macrostep on screen. - `docs/telemetry.md` gains a section on the consuming end of the `otel` key. A malformed template raises where the option is read, so a typo cannot quietly produce URLs that resolve nowhere. A step with no correlation - no template configured, no `otel` key on the stream, or ids that are not W3C Trace Context hex - renders no link and no error, which is the normal case for every stream captured with no bridge attached, and every pane then renders exactly what it rendered before. This package still calls no OpenTelemetry API and gains no dependency. - `StatifierUI.Trace.Subscriber` accepts an `:otel_context` resolver - `(session_id, macrostep -> {:ok, %{trace_id: binary, span_id: binary}} | :none)` - and stamps the wire format's `otel` envelope key from it on `trace.*` and `effect.*` messages, the producer half of ADR-0013. The ids come from the host; this package still calls no OpenTelemetry API and gains no dependency. A resolver answering `:none`, returning a malformed or half pair, or raising leaves the key absent rather than failing the trace, and a projected stream carries the key unchanged. - `StatifierUI.Trace.Otel`, the pure module deciding which messages may carry `otel` and whether an answer is well-formed W3C Trace Context hex. - `docs/telemetry.md` is published with the other guides on hexdocs. Without an `:otel_context` resolver nothing changes: the key is absent everywhere and golden traces stay byte-comparable. - `StatifierUI.DatamodelExplorer` carries `session.start`'s `projection` header on the pane struct and exposes it as `projected?/1` and `projection_profile/1`, so a host can surface the profile name alongside the mode (ADR-0012). - `StatifierUI.DatamodelExplorer.edit_disabled_reason/1` and `/2`, with the boolean forms `editable?/1` and `editable?/2`: ADR-0012's rule that no value-editing affordance may be offered over a projected stream, or over a redacted slot, as a function a write path can consult. The reason is a sentence written to be shown, naming the profile or the slot. The pane still has no write path of its own; this is the guard whatever builds one asks first. - `StatifierUI.DatamodelExplorer.Markdown` renders that reason under a live pane's header when the stream is projected, instead of leaving the reader to guess why every value reads `(redacted)`. `StatifierUI.EventInjection` is explicitly **excluded** from the same rule and its moduledoc records why: its palette is composed from a fixtures bundle the operator already holds in full, never from observed values, so projection cannot reach it. - Such an event now carries an `error` object naming the failure kind, the expression, the span within it, and the absolute, pre-resolved document location of the failing subexpression - so a consumer underlines it directly with no span composition of its own. `docs/wire-format.md` now states the end-exclusive convention for spans and locations explicitly. - `StatifierUI.EventLog.configuration_at/2` gained a fourth outcome, `{:final, configuration}` - macrostep `n` halted the run, and this is the configuration it exited in. It is kept distinct from `{:quiescent, configuration}` for the same reason `{:carried, ...}` is: a configuration the chart *exited* in is not one it *settled* in, and `StatifierUI.Inspector.selection_note/2` words the two differently ("at the final configuration the run halted in"). - `StatifierUI.EventLog.Macrostep` gained `final_configuration` and `stamped/1`, and `StatifierUI.Inspector.points/1` gained `final?` beside `quiescent?` - a halting macrostep is not quiescent, and a scrubber saying so is not the same as one saying it has nothing to show. - `StatifierUI.Trace.Projection` projects a trace stream down to structure, transitions, outcomes and ordering, replacing datamodel and payload values with the reserved `{"$redacted": true}` sentinel (ADR-0012). Build a profile with `profile/2` and pass it to `StatifierUI.Trace.Subscriber.start_link/1` as `:projection`; every message is projected before it is buffered or fanned out, so a projected stream can be rendered, encoded or persisted without any of those having held a value. - A profile allows values back by path prefix (`allow_paths`, matching `effect.datamodel_change`'s `location_path` encoding) or by naming an unlocated position (`allow_positions`). A prefix longer than a write's own path descends into the written value, so an allowed leaf passes while its withheld siblings are redacted. `allow_source: false` additionally redacts `session.start`'s chart source. - `session.start` carries a `projection` header naming the mode and profile whenever the stream is projected, so a projected capture is always distinguishable from a full one. - `StatifierUI.Value` decodes `{"$redacted": true}` to the new `:redacted` atom and encodes it back; `StatifierUI.Shape` gains a matching `:redacted` shape that renders as `redacted`. - `StatifierUI.Live` - read-only LiveView function components for a host application's ops views: `ops_view/1` composing `status/1`, `scrubber/1`, `diagram/1`, and `event_log/1` over one trace stream in wire format v1, live or persisted. Compiled only when the optional `:phoenix_live_view` dependency is present (ADR-0004); without it every component raises with instructions. `docs/ops-embedding.md` is the embedding guide. - `StatifierUI.Live.State` - the pure read model a host keeps in its socket: `new/2` over a persisted message list, `push/2` for a live subscriber's fan-out (dropping any message whose `seq` is not newer than the newest one held, so the `add_listener` then `sync/2` overlap costs nothing), `sync/2` to pull a subscriber's buffer and stats in one call, and `scrub/2` / `select/2` over `StatifierUI.Inspector`'s selection. - The event log renders as HTML rather than Markdown in a LiveView host, so clicking a macrostep entry moves the diagram to it - the link the Livebook pane cannot have, because a Markdown document has no click target. - `docs/ops-embedding.md` - embedding the ops view in a host LiveView, live and persisted, with the styling hooks and the Mermaid client the diagram pane expects a host to supply. - `StatifierUI.Trace.Capture` makes recording, saving, and reloading a trace one call each: `record/3` off a live `Statifier.Session`, `save/2` to a JSON Lines file, `load/1` back into a message list. - `StatifierUI.Trace.Json.decode/1` and `decode_lines/1` read the wire format back into `StatifierUI.Trace.Message` structs, over the new `StatifierUI.Trace.Message.from_map/1`. `docs/ops-embedding.md` has cited `decode/1` since it was written; it now exists. - `StatifierUI.Kino.inspect_trace/3` reopens a saved trace in the Livebook inspector, recompiling the chart from the SCXML the trace carries when the caller does not supply a machine. - `StatifierUI.Inspector.persisted_status/1` renders the status header for a stream read from storage, which has no subscriber counts to report. - `docs/wire-format.md` specifies JSON Lines as the file framing and states the v1 round-trip law: decoding and re-encoding a conformant stream reproduces its bytes. - `session.start`'s `states` and `transitions` identity tables now carry an `attribute_locations` object per row, mapping an attribute's name to that attribute's own value span. Key presence is the contract: an entry exists only for an attribute the author actually wrote, so `attribute_locations["type"]` being absent is how a consumer tells a transition that defaulted to external from one written `type="external"` - a question the lowered `type` value cannot answer. A consumer wanting hover precision on a transition's `event` or `target`, or a state's `id` or `initial`, now has it from `session.start` alone; reading the `%Statifier.Document{}` tree for it is no longer necessary. Requires a statifier that carries `attribute_locations` on the compiled Machine (statifier 2.0.0 and later). - `StatifierUI.Live.ExpressionInput` - an expression field with completion, offering predicator's own grammar (operators, keywords, literal words, duration units, and every function the host's providers resolve) alongside the datamodel paths the host declares. It is the affordance statifier_blocks ADR-0005 defers to this package, and it drops into that editor's `expression_component` seam as `&StatifierUI.Live.ExpressionInput.expression_input/1` (sui-wqr). The field carries no event of its own: it renders an `` with the `name` it was given, so edits - typed or completed - arrive through the host form's existing `phx-change`. - `StatifierUI.Expression` - the completion source behind it, pure and without LiveView: `completions/2` returns `{label, insert, kind, detail}` entries read from `Predicator.Vocabulary` and the supplied paths, so a host can render its own control over the same list. - **This package now ships JavaScript**, as source under `assets/`, per ADR-0009. A host adds `"statifier_ui": "file:../deps/statifier_ui/assets"` to its `assets/package.json` and spreads `StatifierUIHooks` from `js/index.js` into its `LiveSocket` hooks. The one hook, `StatifierUIExpressionInput`, upgrades the field from a native `` to a caret-aware completion list; it imports nothing, and a host that registers no hook keeps a working field. Hook names and export names are public API. See the ADR-0009 note of 2026-09-02 for the layout. ### Changed - `StatifierUI.Inspector.event_log/1` is now `event_log/2`, taking the same options as the other fold functions. The one-argument call is unchanged in behaviour. - A transition written `type="internal"` now carries an `[internal]` marker in the diagram. SCXML's `external` default stays unmarked, so the two no longer render identically. - `StatifierUI.Diagram`'s moduledoc gained a "Known limits of this projection" section: lifted-edge geometry (including edges between two regions of one parallel state), self-edge notation for internal transitions, pseudo-states drawn as ordinary nodes, shallow-versus-deep history distinguishable only by label, executable content not drawn, and layout left entirely to Mermaid. These are the accepted limits of the Mermaid backend rather than defects; ADR-0008's elkjs renderer is where they are addressed. - The trace wire format reserves `otel` as an envelope key: an optional object carrying the W3C Trace Context `trace_id` and `span_id` of the OpenTelemetry span covering a message's macrostep, legal on `trace.*` and `effect.*` messages only (ADR-0013). No producer emits it yet, the format version stays `1`, and a stream with no correlation context attached is byte-unchanged - but a payload may no longer use `otel` as a key. - The wire format's reserved one-key `$`-prefixed shape admits `$redacted`, making five reserved forms rather than four. The format version stays `1`: no existing stream changes, and full fidelity remains the default and is byte-unchanged. - Nothing existing moves. Every row keeps its element-level `location` unchanged, and `attribute_locations` is `{}` for an element that wrote no attributes, for the synthesized initial transition, and for a Machine compiled by an older engine - in each case a consumer falls back to `location`, the granularity this format offered before. The format version stays `1`; the addition is additive per ADR-0005. - `cond_location` is retained rather than superseded. It falls back to the transition's own `location` when a guard was written without a recorded span, where `attribute_locations` simply omits the key, so the two answer different questions. Prefer `attribute_locations["cond"]` for new work. - `contents` and `data` rows are unchanged and carry no `attribute_locations`. - `predicator` is now a direct dependency at `~> 9.1`, the release that carries `Predicator.Vocabulary`. It arrived only through `statifier` before; the completion source reads the vocabulary itself, and a host on a predicator without it gets its declared paths and no grammar entries rather than an error (sui-vsx). ### Fixed - `StatifierUI.Diagram.render/2` no longer drops transitions the Mermaid projection has no obvious notation for. A targetless transition - the spec-legal way to run executable content without changing configuration - was rendered as nothing at all, so a state that handles an event read as one that ignores it; it is now drawn as a self-edge marked `[internal]`. A history state's default transition, which lives in `history_default` rather than in the selectable `transitions` list, was dropped the same way, leaving the `(H)` / `(H*)` label naming a pseudo-state whose fallback target was invisible; it is now drawn with a `[default]` marker. - An event whose data is an expression-evaluation failure no longer fails to normalize. Previously `StatifierUI.Value.encode/1` rejected the failure payload and the whole trace message was dropped, so the diagnostic a consumer most needs never reached the wire. - The configuration pane now shows a halted chart's final configuration (sui-dc7). A run that ends by entering a top-level `` never reaches quiescence in its last macrostep, so it emits no `trace.macrostep_stable` for it; `StatifierUI.Inspector` read only that message type and therefore kept highlighting the state the chart had *left*, while the datamodel pane showed the assignment that moved it out. Both stamping messages are read now, newest wins. The wire format is what settles that `trace.done` may be read this way: its `configuration` field is defined as "the full configuration as it stood at exit, a genuine set, sorted ascending" - the same shape and the same authority as a `trace.macrostep_stable` payload. Nothing here re-derives an exit configuration from the exit sets that precede `trace.done`; the format version is unchanged and the engine is untouched. - `StatifierUI.EventLog.Markdown` no longer raises `Protocol.UndefinedError` when a `session.terminated` message carries a non-string `reason`. It and the datamodel explorer now render a withheld value as `(redacted)` rather than as unbound or as a literal one-key map. - `docs/wire-format.md` no longer says `session.start`'s `data.value_location` is present only when the compiler recorded a value span. A conformant producer always emits it, falling back to the element's own span, exactly as the surrounding prose already said - so a consumer need not handle its absence. ## [0.2.0] 2026-08-27 Fixtures become executable. ADR-0006 adds named datasets and free-standing expressions to a fixture bundle, `StatifierUI.TruthTable` evaluates the two against each other into a result matrix, and a bundle can now travel with a single reusable chart fragment rather than with a whole chart - so a palette entry carries its own worked examples and a host can run them in its own suite. ### Added - `StatifierUI.Fixtures` gains `datasets` and `expressions` fields (ADR-0006): named example datamodels for evaluating expressions against, and named free-standing predicator expressions carrying an `expect` map keyed by dataset name. - `StatifierUI.Fixtures.Source` gains optional `datasets/0` and `expressions/0` callbacks so a host can supply the two new maps from Elixir alongside `scenarios/0` and `example_events/0`. - `StatifierUI.Fixtures.Lint` reports an expression matching no compiled guard and an `expect` key naming no dataset, both as warnings. - `StatifierUI.Fixtures.Expectations` runs every `expect` entry against its named dataset and reports whether the stated value held, for wiring into a host's own test suite. - Depends directly on `predicator` (`~> 9.0`) rather than only transitively through `statifier`. - `StatifierUI.TruthTable` evaluates a bundle's expressions across its datasets and returns the ADR-0006 result matrix, one cell per `(expression, dataset)` pair. A cell's verdict is `:satisfied`, `:unsatisfied`, `:undefined`, `:value`, `:error`, or `:missing_dataset` - deliberately not `true` / `false`, so predicator's three-valued `undefined` cannot be collapsed into false by Elixir truthiness. - `StatifierUI.TruthTable.Markdown` renders that matrix as Markdown, with datasets down the rows and expressions across the columns by default, or transposed with `orientation: :expressions_as_rows`. Every cell spells its value out as a word and adds emphasis on top, so the three truth values stay distinct in plain text. - `StatifierUI.Kino.truth_table/2` wraps the rendered matrix in a `Kino.Markdown` widget for a Livebook cell. It needs no session and no Phoenix; without the optional `:kino` dependency the stub points at the pure renderer instead. - `StatifierUI.Fixtures.Bundle` lets an ADR-0003/ADR-0006 fixture bundle travel with one reusable chart fragment instead of with a whole chart, so a palette entry can carry its own executable examples. A fragment supplies its bundle as a `StatifierUI.Fixtures` struct, an atom-keyed Elixir map, a string-keyed sidecar map, or a path to a `.fixtures.json` file; all four route through the existing validation and converge on one struct. - `StatifierUI.Fixtures.Bundle.discover/2` loads every entry's bundle across a palette of modules, and `discover_dir/2` does the same for a directory of `.fixtures.json` files. Neither is all-or-nothing: a fragment that ships no examples is reported as an absence, and one malformed bundle is reported against its own name while the rest still load. - `StatifierUI.Fixtures.Bundle.Markdown` renders a fragment's "test this step" panel - its truth table and its expectation results together - and `render_discovery/2` renders a whole palette's worth. The expectations summary reports four counts rather than a pass or a fail, because `Expectations.check/2` and `Fixtures.Lint` deliberately disagree about whether an `expect` key naming no dataset is a failure or a warning. - `StatifierUI.Kino.test_panel/2` and `StatifierUI.Kino.palette_panel/2` wrap those renderings as `Kino.Markdown` widgets. Like `truth_table/2` they need no session and no chart; without the optional `:kino` dependency the stubs point at the pure renderers instead. - `docs/fixture-bundles.md` documents the convention and walks an embedder through wiring a palette entry's bundle, discovering a whole palette, and running every fragment's expectations in a host suite. ## [0.1.1] 2026-08-24 Documentation-only release: brings the hexdocs to the shared fleet standard. No code changes. ### Changed - Unpublishes the ADRs from hexdocs; they remain in the repository under `docs/adr/`. - Fixes the five broken links in the published docs - repo-relative references (research doc, ADRs, inspector notebook, architecture's research link, LICENSE) now resolve as absolute GitHub URLs or badges. - Adds a badge row (CI, Hex version, downloads, hexdocs, license) and a Documentation index to the README, and corrects the stale claim that the project has no CI. - `mix docs` now builds with zero warnings. ## [0.1.0] 2026-08-22 First release: authoring, observing, and debugging components for the [statifier](https://hex.pm/packages/statifier) statechart engine, consuming its effect stream through the language-neutral trace wire format (format version 1). The Livebook inspector is the first assembled frontend; the panes underneath it are pure folds any other frontend can render. ### Added - `StatifierUI.Diagram.render/2` renders a compiled machine and an active configuration as Mermaid `stateDiagram-v2` source for `Kino.Mermaid`, with composite nesting, parallel regions, active-state highlighting, and cross-hierarchy transitions lifted to the composite level with a `[lifted: ...]` marker. - `StatifierUI.EventLog.build/1` folds a trace message stream into a log grouped by `(macrostep, round)`, ordered by the producer's stamps rather than arrival, and `StatifierUI.EventLog.Markdown.render/2` renders it as collapsible Markdown for `Kino.Markdown`, with wire-format indexes resolved to state and transition names by `StatifierUI.EventLog.Labels`. - `StatifierUI.EventInjection.build/1` turns an ADR-0003 fixture bundle (or `nil`) into the event-injection pane model: a sorted palette of editable event buttons via `StatifierUI.EventInjection.Palette`, a `free_form_only?` flag for the fixture-less degraded mode, and `send/2`/`send_draft/3` to deliver a `StatifierUI.EventInjection.Draft` through `Statifier.Session.send_event/2` - the ordinary recordable input path, per statifier ADR-0029. - `StatifierUI.DatamodelExplorer.build_authoring/3` and `build_live/2` build a read-only datamodel tree - document `` declarations, spec 5.10.1 system variables, predicator provider functions in scope, and either a fixture scenario or a live session's datamodel with entries marked `changed?` per macrostep - and `StatifierUI.DatamodelExplorer.Markdown.render/2` renders it as Markdown for `Kino.Markdown`. - `StatifierUI.Kino.inspect/3` assembles the Livebook inspector: the configuration diagram, datamodel explorer, event injection, and event log panes composed over one shared subscriber, live-updating, detaching cleanly on cell re-evaluation. Compiled only when the optional `:kino` dependency is present. - `StatifierUI.Trace.Subscriber.attach/3` accepts `catch_up: true`: on a session started with `record: true` the missed prefix is replayed into the buffer atomically with the subscription (statifier ADR-0049); an unrecorded session falls back to live delivery with a `:not_recorded` diagnostic the inspector surfaces as "Live-only". - `StatifierUI.Inspector` - the pure pane-assembly fold the Kino shell renders, usable by any other frontend. - `notebooks/inspector.livemd` - the demo notebook, doubling as the milestone's manual acceptance test. - Serializes statifier's `DatamodelChange` effect as the `effect.datamodel_change` wire type, so consumers can observe datamodel values as they are written instead of only the variable names `session.datamodel` carries. New types are additive under the wire format's must-ignore rule. - Every `effect.*` wire message carries the engine's `round` stamp in its envelope, alongside `macrostep` and `microstep`; consumers reading older recorded streams must still tolerate `effect.*` messages without the key.