Skip to content

Releases

v1.71.0

Choose a tag to compare

@github-actions github-actions released this 10 Nov 01:18
Immutable release. Only release title and notes can be modified.
d5cbc69

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

  • 🟪⬛ a lexicon people write, a glossary Trax derives (#147) (d5cbc69)

v1.70.0

Choose a tag to compare

@github-actions github-actions released this 09 Nov 20:38
Immutable release. Only release title and notes can be modified.
545e184

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

  • 🟪 derived invokes match the host, enum strings type as unions (#146) (545e184)

Features

  • 🟦⬛ ordered replays, a Board page, the site's look in the console, and a light theme (#144) (ae86adc)

v1.69.1

Choose a tag to compare

@github-actions github-actions released this 09 Nov 17:14
Immutable release. Only release title and notes can be modified.
34a5ed1

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

  • 🟫🟪🟧🟦⬛ fixes found building the home prompt's app (#143) (34a5ed1)
  • ⬛ the home page's prompt says what the app is before how to build it (#140) (2e034e9)

v1.69.0

Choose a tag to compare

@github-actions github-actions released this 09 Nov 01:53
Immutable release. Only release title and notes can be modified.
7f1369a

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 with CLIENT_DIVERGENCE.
  • The TypeScript client and the generated client refuse an http: endpoint on a host other than
    loopback. Set allowInsecureTransport (on TraxConnection for 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.revision may be null (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, MaxMessageSize and MaxResponseSize options, 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() or AllowAnonymousOperations() deliberately.
    RequireAuthorization() alone no longer starts.
  • RabbitMQ. UseRabbitMq and UseRabbitMqInvalidation need a SigningKey of at least 32
    bytes shared by every process on the exchange, and amqps:// to a broker on another host. Upgrade
    every process together, or run with AllowUnsignedMessages() 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 Add must be at least 32 characters outside Development.
  • Broadcast output. A non-operator subscriber that reads output from a [TraxBroadcast]
    train needs AllowOutputForBroadcastSubscribers<TTrain>().
  • trax generate now writes trains that require the User role, and the generic saveSnapshot
    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-gherkin derives 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 the Policy actor.
  • Views. Read-only queries across machines under a derived read rule, with persisted documents
    and a generated views.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...
Read more

v1.68.0

Choose a tag to compare

@github-actions github-actions released this 20 Oct 18:31
Immutable release. Only release title and notes can be modified.
503c577

1.68.0 (2026-10-20)

🟨🟩🟪🟧🟦 Parallel leaves experimental, and three fixes (#84)

  • Parallel is no longer experimental: remove any NoWarn of TRAXEXP001.
  • Each Parallel branch logs under a scope and traces under an Activity carrying 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

  • 🟦🟥 the operations console works where persisted operations are required (#80) (59794eb)
  • 🟦 the console is the one operator dashboard, organised by what an operator works with (#87) (24e6ca9)
  • 🟨🟩🟪🟧🟦 Parallel leaves experimental, and three fixes (#84) (5a0533e)

v1.67.0

Choose a tag to compare

@github-actions github-actions released this 16 Oct 23:40
Immutable release. Only release title and notes can be modified.
bef13b6

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

  • ⬛ refuse an OpenAPI property named like its type instead of renaming it (#75) (bef13b6)

Features

  • 🟦⬛🟥 a page writes every document it sends (#74) (7bf662e)

v1.66.0

Choose a tag to compare

@github-actions github-actions released this 16 Oct 19:13
Immutable release. Only release title and notes can be modified.
ee4e459

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 in Models/.
  • 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

  • 🟦⬛🟥 a page fetches only what it asks for, and entity answers no longer stop the host (#73) (ee4e459)
  • website,trains: the Trax book, and a roadmap back to 1.0 (#72) (8e9982c)
  • website: a prompt to paste into an agent beside the hero (#70) (bc9eb6b)

v1.65.0

Choose a tag to compare

@github-actions github-actions released this 16 Oct 02:51
Immutable release. Only release title and notes can be modified.
912dca5

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

  • 🟨🟪🟧 fix what a first build from the docs alone hit (#64) (335b87f)
  • 🟨🟪 let a state spawn a child machine and wait for it to end (#69) (912dca5)

v1.64.0

Choose a tag to compare

@github-actions github-actions released this 15 Oct 22:31
Immutable release. Only release title and notes can be modified.
faff683

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. --check exits 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 gets CLIENT_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.StartedBy carries the starter to every run
    of a manifest, and a retried run answers retriedAs. A queued run the host cannot read ends its stream with a
    problem after repeated failures; subscribe again.
  • ⬛🟦 useRunProgress follows nothing after another user signs in until it is given a run id again, and
    followRunProgress ends with CONNECTION_CHANGED when configureTrax closes its socket.
  • 🟪🟦 A machine waiting on a run it invoked answers its owner invokedRun { runId }.

Breaking for clients

  • 🟪🟦 machineChanged is replaced by <machine>Changed(id), typed per machine.
  • 🟪🟦 Refusal codes are one enum, spelled GUARD_FAILED everywhere, extensions.code included.
  • 🟪🟦 Context and input enums of a machine are spelled as stored (HighPriority).
  • 🟪 @traxsharp/state-machine drops useMachine, createSnapshotClient and createHttpExecutor;
    createMachineExecutor requires 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, and useRemembered<Machine>() keeps each user's instance under its own key for that user. The
    runtime still serves format 1.
  • 🟪 An effect-bound trigger takes no input in the generated send. Install graphql-ws beside the package.
  • 🟪 A trigger bound with RunsOnce may not also be used on another edge; the build says so.
  • 🟪 A request on a generated server made before the last configureTrax stops its controller with
    CONNECTION_CHANGED instead 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-machine has 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,
    and UsePersistedOperations no longer exposes the operations namespace. ExposeOperationsNamespace is 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 from UsePersistedOperations is refused at startup.
  • 🟦 operations holds only what the operations dashboard does: machineDocuments, declaredChain, and the
    execution(id), manifest(id) and workQueue(id) reads are removed in favour of the client manifest export,
    runGraph and the detail reads. Monitors read /trax/health.

See the machine wire changes migration guide for the upgrade.

All changes

Features

  • 🟨🟪🟧🟦⬛🟥 generated clients, and operations is admin only (#57) (faff683)

v1.63.1

Choose a tag to compare

@github-actions github-actions released this 14 Oct 21:26
Immutable release. Only release title and notes can be modified.
a963d70

1.63.1 (2026-10-14)

Bug Fixes

  • stage the npm tarball by its local path (#54) (7bc7606)