Repository navigation
Releases
v1.71.0
1.71.0 (2026-11-10)
🟪⬛ A lexicon people write, a glossary Trax derives (#147)
🟪⬛ A lexicon people write, a glossary Trax derives
A features directory now holds a lexicon (*.lexicon): a short line-based file in the style of
Gherkin that says what the features' words mean. trax machine from-gherkin elaborates it to
glossary.json, writes that beside the machines, and --check fails when it is stale. Everything
that follows a rule (context types, train input wiring, outcome reductions and examples) is filled
in, and every problem names a lexicon line. With --trains <dll> (or Lexicon.Read given the
assemblies) a train's fields are read from its records. trax lexicon format lines up a lexicon's
columns. A hand-written glossary.json still works with --glossary.
All changes
Features
v1.70.0
1.70.0 (2026-11-09)
🟦⬛ Ordered replays, a Board page, the site's look in the console, and a light theme (#144)
The console has a Board page
A machine served from features is drawn on its own Board page, under Overview, as an
event-storming board: paper notes in event storming's colours, one lane per machine, read in the
order its states are reached, each note listing the scenarios behind it. It used to be a tab on the
machine's page; that page now links it, and an old ?tab=board address opens it. A panel beside the
board lists the scenarios behind it, and stays in view while the board scrolls.
The console looks like traxsharp.net
The console uses the site's mint green, its type (Atkinson Hyperlegible Next and JetBrains Mono) and
the Trax .NET logo, in both its themes.
All changes
Bug Fixes
Features
v1.69.1
1.69.1 (2026-11-09)
🟫🟪🟧🟦⬛ Fixes found building the home prompt's app (#143)
🟫🟧 Stored JSON keeps dictionary keys as given
Queued inputs, manifest properties, saved run inputs and outputs, and junction log rows now write a
dictionary's keys as the caller gave them. Member names are still camelCase. Rows written before
keep their lowercased keys and read back as they did.
After the upgrade, a manifest whose input holds a dictionary with capitalised keys is reseeded with
the new casing. A run of it that failed with checkpoints before the upgrade is retried from the
start, since its stored input no longer matches, and an unrun one-time manifest with such an input
moves to its new seed time once.
🟪 Derivation warns of a policy waiting for another's result
FeatureMachines.Derive returns DerivedMachines.Warnings, and trax machine from-gherkin and
trax machine explain print them. A warning stops nothing.
All changes
Bug Fixes
v1.69.0
1.69.0 (2026-11-09)
🟪🟦⬛ .NET and Rust clients, and agent skills (#108)
A client for .NET frontends
Trax.StateMachine.Client drives a machine your host serves from Blazor, .NET MAUI, Avalonia, WPF or another
service. Give it the machine from your client manifest, an HttpClient and the socket endpoint. It sends every
operation by persisted id, follows the instance over the socket, predicts each event from the machine's IR in the
manifest with MachinePredictor.FromIr, and shows what the server stored. A refusal or a network failure comes back
as a SendOutcome, never an exception. See
.NET client.
Typed C# views, from the assembly or the manifest
trax machine generate --lang csharp writes a typed view of a machine (Checkout.g.cs): enums for its states and
triggers, a record per context and input, and a CheckoutClient with a typed method per event. A frontend that has
the host's client manifest and not its assembly passes --manifest in place of --assembly.
🤖 Generated with Claude Code
🟦⬛ Generate the operations console's client (#111)
The operations console's client is generated
The operations console now sends every request through a client trax client generates from its documents, the
same way an app's frontend does. trax client --operations <schema.graphql> --documents <glob> --out <dir> writes
it: a typed function per document, its persisted id, and the documents file a host registers. A host's client
manifest still never lists the operations surface, and who may run an operation is unchanged.
trax client also accepts a nullable variable passed to a non-null argument that has a default, as GraphQL allows.
🟪🟦⬛🟥 Clients predict only what they can evaluate, and the languages agree (#113)
Machine clients
- A client no longer predicts an event whose edge depends on a custom guard, custom reduction or
custom state requirement it has no handler for. It sends the event without a prediction, so the
server no longer refuses it withCLIENT_DIVERGENCE. - The TypeScript client and the generated client refuse an
http:endpoint on a host other than
loopback. SetallowInsecureTransport(onTraxConnectionfor a generated client) only on a
network you trust. A relative URL in a browser is unaffected. - The TypeScript client fails a non-2xx answer as
TRANSPORT_ERROR, as the .NET client does. ServerSnapshot.revisionmay benull(a custom store that records none); such an answer is
applied and not ordered.- Generated clients are client format 3; regenerate with this release's
trax client.
.NET client
AllowInsecureTransport,MaxMessageSizeandMaxResponseSizeoptions, and the cleartext and
size defaults above.
🟦⬛ Trax-console, the operations console in a terminal (#114)
trax-console
dotnet tool install -g Trax.Api.Console.Terminal installs the operations console for a terminal.
It shows runs, dead letters, the work queue, manifests, a run's trace and machines, and acts on them
with the same documents the browser console sends, so a host that serves the console has nothing new
to allow. With a command it answers in JSON lines for scripts and agents. It signs in with an API key
or bearer token from the environment or a file.
A C# client for the operations console
trax client --operations --lang csharp writes the console's client in C#, over the new
Trax.Client package, a .NET runtime for a host's persisted GraphQL documents.
Registering the console's documents without the page
app.UseTraxOperatorConsoleDocuments() registers the console's documents on a host that requires
persisted operations without serving the browser console, for a host operators reach only from a
terminal.
Upgrading
- Operations namespace. If it is exposed, declare
GateOperations(...), or call
GateOperationsToAuthenticatedUsers()orAllowAnonymousOperations()deliberately.
RequireAuthorization()alone no longer starts. - RabbitMQ.
UseRabbitMqandUseRabbitMqInvalidationneed aSigningKeyof at least 32
bytes shared by every process on the exchange, andamqps://to a broker on another host. Upgrade
every process together, or run withAllowUnsignedMessages()until they are. - Remote runners. Upgrade runners before schedulers: a scheduler with a signing key refuses an
unsigned run response. - API keys. Keys added with
Addmust be at least 32 characters outside Development. - Broadcast output. A non-operator subscriber that reads
outputfrom a[TraxBroadcast]
train needsAllowOutputForBroadcastSubscribers<TTrain>(). trax generatenow writes trains that require theUserrole, and the genericsaveSnapshot
refuses machines with guards, reducers, custom rules or a start that reads input.
🟪🟦⬛🟥 Catch the host up to a page that ran ahead, and settle every client operation (#122)
Catch the host up to a page that ran ahead of it
Every machine client can now plan and send the events that bring the host to where a form-driven page
is: syncTo in TypeScript (and createFormView's sync), SyncToAsync in .NET, sync_to in Rust.
Each view has unsaved for a leave guard. The planner is also available on its own (plan) and gives
the same answer in all three engines.
Safer, steadier clients
The .NET clients require an HttpClient with automatic redirects off. Every client refuses
scheme-relative and cleartext endpoints unless insecure transport is allowed, refuses to send a trigger
the machine does not declare, and settles every operation with a value: sends after a refused start,
streams the host refuses, and failures that used to leave the queue waiting.
⬛ A new logo, on the site, the README and every package (#125)
Every Trax package on nuget.org now shows the Trax icon.
🟪🟦⬛ Derive and serve machines from gherkin features (#134)
- Machines from features. Write a machine as Gherkin features and a glossary;
trax machine from-gherkinderives its IR, its access and the policies and views between
machines, and refuses to write a machine its own scenarios fail. Serve them with
ServeFeatures(directory), no machine class needed. - Policies. The server fires a trigger when another machine enters a state, once, across
hosts, recorded as thePolicyactor. - Views. Read-only queries across machines under a derived read rule, with persisted documents
and a generatedviews.g.ts. - New CLI commands:
trax machine from-gherkin,run,missing,usage,diagram. - Console: a Board tab on machines served from features.
- New packages:
Trax.StateMachine.Gherkin,Trax.StateMachine.Gherkin.Reqnroll. - Sample: the Bakery, a web page and API whose machines are written only as features.
All changes
Bug Fixes
- 🟪🟦⬛🟥 clients predict only what they can evaluate, and the languages agree (#113) (40c0ec8)
- 🟪🟦⬛🟥 the three machine clients answer every host the same way (#126) (b744260)
- 🟪🟦⬛🟥 the three machine clients read a real host the same way (#132) (d79a817)
- ⬛ build the site's colours and type on the logo (#129) (77c3f6b), closes #6cc596
- ⬛ every demo puts its run first, under one toolbar (#130) (27c27cf)
- ⬛ one description of your app, for the whole team (#136) (c704d8c)
- 🟩⬛ make the agent scenarios one point each (#117) (d6e5ba2)
Features
- 🟪🟦⬛🟥 catch the host up to a page that ran ahead, and settle every client operation (#122) (7b7ddb4)
- 🟪🟦⬛ .NET and Rust clients, and agent skills (#108) (c8ca3a3)
- 🟪🟦⬛ derive and serve machines from gherkin features (#134) (7f1369a), closes 35#59
- 🟦⬛ trax-console, the operations console in a terminal (#114) (0ecd592)
- 🟦⬛ generate the operations console's client (#111) (9fdc363)
- ⬛ a new logo, on the site, the...
v1.68.0
1.68.0 (2026-10-20)
🟨🟩🟪🟧🟦 Parallel leaves experimental, and three fixes (#84)
Parallelis no longer experimental: remove anyNoWarnof TRAXEXP001.- Each
Parallelbranch logs under a scope and traces under anActivitycarrying its branch path
(BranchDiagnostics.SourceName,BranchDiagnostics.BranchPathKey). - A state-machine write committed in this host reaches its watchers at once on SQLite, InMemory and Postgres in
poll mode;AddStateMachines(o => o.ChangeFeedPollInterval = ...)sets the poll for writes from other hosts. - The GIN-index startup warning no longer reports a scalar collection the filter input does not expose.
🟦🟥 The operations console works where persisted operations are required (#80)
The operations console now works on a host that requires persisted operations. A host that serves
it with UseTraxApiDashboard and runs UsePersistedOperations registers the console's own
documents when it starts, under trax_console_ ids, and the console sends them by id. Nothing to
configure. A console document the host cannot serve is left out with a log line. The operations
gate still applies to every request.
🟦 The console is the one operator dashboard, organised by what an operator works with (#87)
The operations console (Trax.Api.Dashboard) is now the one Trax dashboard, and the Blazor dashboard
(Trax.Dashboard) is removed: serve the console with UseTraxApiDashboard instead.
What changes for an operator
- Navigation by what you work with: Overview, Runs, Trains, Machines, Schedules, System, API admin. Old links redirect.
- The Overview leads with what needs attention, and every number opens the list behind it.
- State machines are drawn, with instance and stuck counts per state, the current state lit, and every transition kept.
- A run is drawn on its chain; a train shows its runs by step; manifests say when they run next, in words.
- Hosts report a heartbeat, a header search finds anything by id, filters live in the URL, and an action on everything
a list matches runs as a tracked bulk operation. HostAuthenticates(): a host that signs the browser in is not asked for a key.
All changes
Bug Fixes
- 🟪 the state-machine package documents every export, and stops exporting its fixtures (#76) (f3cf691)
- 🟦 a run's timeline keeps a step that ended while its first read was in flight (#90) (680d65e)
- 🟩🟧🟦⬛ startup errors link their fix; docs for newcomers (#94) (a80e4a6)
Features
v1.67.0
1.67.0 (2026-10-16)
🟦⬛🟥 A page writes every document it sends (#74)
A frontend writes the documents it sends
A host no longer generates a persisted document for each exposed train, and trax client no longer
writes a trains/ function per train. Write a .graphql document for each train a page calls,
generate its function with trax client --documents, and register the file with
ClientDocuments(path). A train answering EF entities that reference each other no longer stops
the host or fails every call for cost. Machine and runProgress documents are unchanged. See
"Reach trains through your own documents" under Upgrading.
Client documents read query models
A client document may select query models beside trains: paged, filtered and sorted in its text,
with only the filter's values as variables. Each query model's authorization still applies. The
host checks every field against the trains and query models it registered, and refuses a document
that passes a whole filter or sort as a variable.
All changes
Bug Fixes
Features
v1.66.0
1.66.0 (2026-10-16)
A prompt to paste into an agent beside the hero (#70)
A prompt to paste into an agent on the home page
The home page now offers a ready-made prompt that builds Battleship against the computer with
Trax and React, with a copy link.
The Trax book, and a roadmap back to 1.0 (#72)
- The docs' Tutorials section is now the Trax book. Chapter 1 builds a shop's order as a train.
- A train's folder holds its contract at the top, its junctions in
Junctions/and every other
type inModels/. - The roadmap lists each release since 1.0 with its version and month.
🤖 Generated with Claude Code
🟦⬛🟥 A page fetches only what it asks for, and entity answers no longer stop the host (#73)
A train answering with entities that refer back to each other starts again
A host exposing a train whose answer has a back-reference (an order's customer, and that customer's orders) refused
to start since 1.64. The generated document now leaves the field that leads back out, and the host logs each one.
A generated document past the host's own MaxExecutionDepth or operation cap now refuses the start, naming its
train, instead of failing every call.
Fetch only what a page needs
Write a .graphql document that selects part of a train's answer, run trax client --documents 'src/**/*.graphql',
and call the typed function it writes, whose result type holds exactly the fields you selected. Name the
trax.documents.json it writes in UsePersistedOperations(p => p.ClientDocuments(path)); the host checks and
registers every document when it starts. See "Fetch only what a component needs" in the docs.
Generated types follow the document
A generated train function now returns <Train>Result, the fields its document selects. types.g.ts keeps only
enums and inputs: code that imported an answer's type from the client imports the result type instead.
All changes
Bug Fixes
- 🟨🟧🟦 stored JSON nests 64 deep, one-offs keep their time, extensions keep Trax's fields (#71) (a7d7ca9)
Features
v1.65.0
1.65.0 (2026-10-16)
🟨🟪🟧 Fix what a first build from the docs alone hit (#64)
Machines that invoke trains on SQLite
A SQLite host with AddScheduler() no longer locks its database for 30 seconds every manifest
manager cycle. Its local worker pool starts one worker unless WorkerCount is set, and a job that
fails before its run starts fails the run at once, so the machine that invoked it reaches its
OnFailed target without waiting for the stale-pending reaper.
InvokedRun
A junction of a train a machine invokes can inject InvokedRun to learn the machine, the instance
and the user who owns it. Trax resolves it from the instance, not from anything the caller sends,
and resolving it anywhere else throws. Use it instead of carrying a user id or token in the
machine's context.
Rules.SetAll
One reduction can now fill several fields: SetAll(Set(...).FromInput(...), Set(...).FromInput(...)).
Smaller changes
- A scheduler with a database cleans up its own run records by default;
AddMetadataCleanup()
changes the settings. - The client manifest is written compact, and an output schema several outcomes share is written
once (manifest format 2). The generated twin writes it once too. Export the manifest again after
upgrading.
🟨🟪 A state can spawn a child machine and wait for it to end (#69)
A state can spawn a child machine
IStateBuilder.Spawns<TChild, TContext, TOutput>(c => c.ChildId) starts another machine whenever the state is
entered, owned by whoever owns the instance, and routes how it ends through the same OnDone, OnFailed and
OnCancelled an invoking state uses. On the child, Ends() and Fails() mark the states it ends in. The child's id
is written into the parent's context, leaving the state removes the child, and while the parent waits the child
cannot be discarded or saved by a client. IMachineInstances.Advance<TMachine>(Guid id, ...) drives a system-owned
child. The database gains snapshot_draft.spawned_by (migration 085, SQLite 044).
All changes
Bug Fixes
- 🟫🟧 a run closed before its train starts publishes its outcome (#65) (c1ec1d7)
- 🟧 LocalWorkerService names OutOfTrainOutcomes in its new namespace (#67) (4e0a133), closes #64 #65
- effect: migrate when pg_trgm lives in a schema off the search path (#61) (dd9f4ce)
- 🟪 corpus samples write an enum by its member name, as the server stores it (#66) (e74ae4c)
Features
v1.64.0
1.64.0 (2026-10-15)
🟨🟪🟧🟦⬛🟥 Generated clients, and operations is admin only (#57)
Generated clients
- ⬛
trax client --target react --manifest <file> --out <dir>writes a frontend's typed client:
each machine's twin and typed hooks, a typed function per train, the GraphQL types they use and
run-progress hooks.--checkexits 1 when the committed client is out of date. It deletes only files it wrote,
and refuses to write through a link under--out. - 🟪🟦 Hosts call
await app.RunTraxAsync(args);--trax-export-client <path>writes the client
manifest without serving or opening a database. - 🟦 Every
[TraxMutation]/[TraxQuery]train gets a persisted document the host registers. A
client of an older shape getsCLIENT_OUTDATED, not a validation error.
Following a run
- 🟨🟦
[TraxRunProgress]lets the caller who started a run read and follow it with
runProgress(runId); nobody else can.ScheduleOptions.StartedBycarries the starter to every run
of a manifest, and a retried run answersretriedAs. A queued run the host cannot read ends its stream with a
problem after repeated failures; subscribe again. - ⬛🟦
useRunProgressfollows nothing after anotherusersigns in until it is given a run id again, and
followRunProgressends withCONNECTION_CHANGEDwhenconfigureTraxcloses its socket. - 🟪🟦 A machine waiting on a run it invoked answers its owner
invokedRun { runId }.
Breaking for clients
- 🟪🟦
machineChangedis replaced by<machine>Changed(id), typed per machine. - 🟪🟦 Refusal codes are one enum, spelled
GUARD_FAILEDeverywhere,extensions.codeincluded. - 🟪🟦 Context and input enums of a machine are spelled as stored (
HighPriority). - 🟪
@traxsharp/state-machinedropsuseMachine,createSnapshotClientandcreateHttpExecutor;
createMachineExecutorrequires each machine's documents. - 🟪 The IR's effect edge no longer carries the server's type name.
- 🟪 Generated code is client format 2:
configureTrax({ url, headers, user })re-renders mounted hooks onto the
new connection, anduseRemembered<Machine>()keeps each user's instance under its own key for thatuser. The
runtime still serves format 1. - 🟪 An effect-bound trigger takes no input in the generated
send. Installgraphql-wsbeside the package. - 🟪 A trigger bound with
RunsOncemay not also be used on another edge; the build says so. - 🟪 A request on a generated server made before the last
configureTraxstops its controller with
CONNECTION_CHANGEDinstead of failing as a retryable transport error. - 🟦🟪 A machine may not hold one of Trax's own enums; give it an enum of its own.
- 🟪
@traxsharp/state-machinehas no runtime dependencies: valibot, which nothing used, is gone.
Operations is admin only
- 🟦 Persisted-operation management moved to a root
persistedOperations { ... }behind its own gate,
GateManagement(policy, roles), in GraphQL and both dashboards. It is not served until a host declares that gate,
andUsePersistedOperationsno longer exposes theoperationsnamespace.ExposeOperationsNamespaceis removed. - 🟦🟥 The management gate is checked on every dashboard read too, its policies run in the caller's scope, and a
store registration that declares a different gate fromUsePersistedOperationsis refused at startup. - 🟦
operationsholds only what the operations dashboard does:machineDocuments,declaredChain, and the
execution(id),manifest(id)andworkQueue(id)reads are removed in favour of the client manifest export,
runGraphand the detail reads. Monitors read/trax/health.
See the machine wire changes migration guide for the upgrade.