Changelog
All notable changes to this project will be documented in this file.
The format is based on Keep a Changelog.
[Unreleased]
[0.17.1] - 2026-11-02
- The demo server copes with a taken port: on a terminal it names the holder and offers to kill it, take the next free port or quit; without one it moves to the next free port and says so (#77)
Fixed
- The demo server copes with a taken port: on a terminal it names the holder and offers to kill it, take the next free port or quit; without one it moves to the next free port and says so (#77) (#77)
[0.17.0] - 2026-11-02
- The demo's accounts are a table, not a slice:
demoaccounts.Openkeeps the book in anaccountstable in the same pglike database, read and written by the daily run,check fundsandpost, so balances survive a restart and a second App over the same database carries on where the first left off. The business date to process is read from the runs on open rather than starting over. The guide's decision table gains the row for the state the steps change; An instance page carries its progress dots as a line under the title: one dot per step of the run's revision, coloured by latest state, so a reader sees the shape of the run before the table
Added
- An instance page carries its progress dots as a line under the title: one dot per step of the run's revision, coloured by latest state, so a reader sees the shape of the run before the table (#71)
Changed
- The demo's accounts are a table, not a slice:
demoaccounts.Openkeeps the book in anaccountstable in the same pglike database, read and written by the daily run,check fundsandpost, so balances survive a restart and a second App over the same database carries on where the first left off. The business date to process is read from the runs on open rather than starting over. The guide's decision table gains the row for the state the steps change (#70)
[0.16.0] - 2026-11-02
- Step data lives in the host's tables: the guide states the pattern (a typed table in the same database, keyed to the engine's rows by
run_idorstep_id, written by the stage that first holds the data and read back by every later stage and the instance page) with a decision table of where each kind of data lives, and the demo follows it: apaymentstable written by the batch's receive stage, keyed to each payment's run, stamped by post, so a failed payment resumes from the database alone over a restart.Options.DSNopens the demo over a file; Reset discards it
Changed
- Step data lives in the host's tables: the guide states the pattern (a typed table in the same database, keyed to the engine's rows by
run_idorstep_id, written by the stage that first holds the data and read back by every later stage and the instance page) with a decision table of where each kind of data lives, and the demo follows it: apaymentstable written by the batch's receive stage, keyed to each payment's run, stamped by post, so a failed payment resumes from the database alone over a restart.Options.DSNopens the demo over a file; Reset discards it (#69)
[0.15.0] - 2026-11-01
- A definition states its place among parents and children.
Step.ManybecomesStep.Mode: unset starts one child,OneAtATimea loop (the next child when the previous is through, or when an operator starts it),AllAtOncea fan-out; breaking for hosts that setMany.Step.Givenis prose for what a child is given, since the engine hands it only its key and business date, andStep.Joinson a later step names the child-starting step whose children it waits for. The parent's definition page says of each child-starting step how it starts its children, what it gives them and which step waits for all, warning when a fan-out has no join; the child's page says who starts it, how, and given what. The picture draws a loop arrow for one at a time, stacked boxes for all at once, and a dashed edge into the joining step; A definition is drawn twice, across in one row (diagram.Across,<type>.svg) and down in one column (diagram.Down,<type>.down.svg), and the pages show the one that fits the screen, down on a phone, through a<picture>media query. The four-column grid goes: d2 fills a grid column first, so a long definition read downwards with diagonal jumps, and a grid cell cannot take the loop arrow of a one-at-a-time step. In a row or a column every edge is routed around the boxes.diagram.Definitionanddiagram.Instancetake the direction; the demo'sdefd2writes both files. Breaking for hosts callingdiagram; Progress dots:view.Views.Progressrenders a run's steps as a row of coloured dots for a host's own page about the thing the run is about (bytestone-scan's batch page), one per step in the order the run's revision recorded, green completed, red failed, amber waiting or running, yellow cancelled, white not run, each titled with the step and its status, the row linking to the instance page. Inline spans, no SVG
Added
- Progress dots:
view.Views.Progressrenders a run's steps as a row of coloured dots for a host's own page about the thing the run is about (bytestone-scan's batch page), one per step in the order the run's revision recorded, green completed, red failed, amber waiting or running, yellow cancelled, white not run, each titled with the step and its status, the row linking to the instance page. Inline spans, no SVG (#63)
Changed
- A definition states its place among parents and children.
Step.ManybecomesStep.Mode: unset starts one child,OneAtATimea loop (the next child when the previous is through, or when an operator starts it),AllAtOncea fan-out; breaking for hosts that setMany.Step.Givenis prose for what a child is given, since the engine hands it only its key and business date, andStep.Joinson a later step names the child-starting step whose children it waits for. The parent's definition page says of each child-starting step how it starts its children, what it gives them and which step waits for all, warning when a fan-out has no join; the child's page says who starts it, how, and given what. The picture draws a loop arrow for one at a time, stacked boxes for all at once, and a dashed edge into the joining step (#61) - A definition is drawn twice, across in one row (
diagram.Across,<type>.svg) and down in one column (diagram.Down,<type>.down.svg), and the pages show the one that fits the screen, down on a phone, through a<picture>media query. The four-column grid goes: d2 fills a grid column first, so a long definition read downwards with diagonal jumps, and a grid cell cannot take the loop arrow of a one-at-a-time step. In a row or a column every edge is routed around the boxes.diagram.Definitionanddiagram.Instancetake the direction; the demo'sdefd2writes both files. Breaking for hosts callingdiagram(#62)
[0.14.0] - 2026-11-01
- The definitions list has a Role column, read from the registry: parent when a step of the definition starts children, child when another definition's step starts it, both when both, blank for a workflow that stands alone. Its Steps column shows the first four steps and counts the rest, so a twelve-step workflow is a line, not a paragraph
Changed
- The definitions list has a Role column, read from the registry: parent when a step of the definition starts children, child when another definition's step starts it, both when both, blank for a workflow that stands alone. Its Steps column shows the first four steps and counts the rest, so a twelve-step workflow is a line, not a paragraph (#60)
[0.13.0] - 2026-10-28
- The instances queue lists top-level runs only: a run with children is found once and its children are read on its page, so bytestone-scan's batches are no longer buried under their scans and photos. A filter naming a purpose, workflow, revision or key lists children too, since the operator asked for them by name;
statusandsincealone stay top level.RunFilter.TopLevelis the store side: only the runs with no parent; The instances page is one table, active first then newest, with a Purpose column leading to that purpose's queue in place of the per-purpose sections and their headlines. The page navigation sits together in one group: Previous, up to five page links around the current one (the first, the last, the current and its neighbours, an ellipsis over each gap), Next.Store.CountMatchingcounts the runs aRunFiltermatches, for the page count; breaking for a host with its ownStoreorview.Reader; The queue's Workflow and Revision columns become one What column,ship-3f: the workflow type and the last two characters of its revision, linked to the definition; the revision in full stays on the instance page, leading to the queue of that revision's instances, and the headline's workflow leads to its queue. ASpecifichook onview.Viewsnames the host's own page for an instance: wherever one is linked — queue row, headline, a parent's children — that page is preferred, with an Instance button beside it to the generic instance page; the View button goes; The demo has a master–detail example: a payment batch (PAY-0001) whose sub-process step starts one payment child (PAY-0001/3) per payment and whosesettlestage waits until none is active, failing the batch if any payment failed. The simulation page pays the next batch, optionally with one payment failing to post; paying again retries the failed payment and settles the same batch. The batch's instance page lists its payments as children, each linking back up, andDetailsays what each is about. Payments debit the demo accounts, so the next end of day shows the lower balances.
Added
- The demo has a master–detail example: a payment batch (
PAY-0001) whose sub-process step starts one payment child (PAY-0001/3) per payment and whosesettlestage waits until none is active, failing the batch if any payment failed. The simulation page pays the next batch, optionally with one payment failing to post; paying again retries the failed payment and settles the same batch. The batch's instance page lists its payments as children, each linking back up, andDetailsays what each is about. Payments debit the demo accounts, so the next end of day shows the lower balances. (#54)
Changed
- The instances queue lists top-level runs only: a run with children is found once and its children are read on its page, so bytestone-scan's batches are no longer buried under their scans and photos. A filter naming a purpose, workflow, revision or key lists children too, since the operator asked for them by name;
statusandsincealone stay top level.RunFilter.TopLevelis the store side: only the runs with no parent (#44) - The instances page is one table, active first then newest, with a Purpose column leading to that purpose's queue in place of the per-purpose sections and their headlines. The page navigation sits together in one group: Previous, up to five page links around the current one (the first, the last, the current and its neighbours, an ellipsis over each gap), Next.
Store.CountMatchingcounts the runs aRunFiltermatches, for the page count; breaking for a host with its ownStoreorview.Reader(#45) - The queue's Workflow and Revision columns become one What column,
ship-3f: the workflow type and the last two characters of its revision, linked to the definition; the revision in full stays on the instance page, leading to the queue of that revision's instances. ASpecifichook onview.Viewsnames the host's own page for an instance: wherever one is linked — queue row, a parent's children — that page is preferred, with an Instance button beside it to the generic instance page; the View button goes (#52)
[0.12.0] - 2026-10-26
Store.DeleteRunremoves a run with its steps and every run under it, at any depth, with theirs: a host deleting the thing a run was about (bytestone-scan deleting a batch) takes the runs out of the queue's history rather than leaving them cancelled; A run is active while it is still work to do (pending, running, waiting, failed) and inactive once terminal:RunStatus.InHandbecomesActiveandRunFilter.InHandFirstbecomesActiveFirst; the queue, the docs and the comments say active. Breaking for hosts that calledInHand
Added
Store.DeleteRunremoves a run with its steps and every run under it, at any depth, with theirs: a host deleting the thing a run was about (bytestone-scan deleting a batch) takes the runs out of the queue's history rather than leaving them cancelled (#43)
Changed
- A run is active while it is still work to do (pending, running, waiting, failed) and inactive once terminal:
RunStatus.InHandbecomesActiveandRunFilter.InHandFirstbecomesActiveFirst; the queue, the docs and the comments say active. Breaking for hosts that calledInHand(#46)
[0.11.0] - 2026-10-24
- Instances page: the Filter and Clear buttons line up with the filter inputs; Bulma's field margin no longer pushes them down; Child runs:
Runner.StartChildstarts an instance under a parent, recorded pending for the host's tick to run;RunRecord.ParentID,RunFilter.ParentIDandStore.CountDescendants(schema v6 addsparent_run_id); aStepwithChildandManyis a sub-process, drawn as one collapsed ⊞ box linking to the child definition; the instance page lists a run's children and links a child to its parent; TheDefinitionsregistry starts empty: a host sees only the workflows it runs.DailyUpdateis exported for gobank to register; the release definition,WorkflowReleaseandReleaseStagesleave the library for the demo app (task-plus declares its own);cmd/defd2moves into the demo; Docs build: d2 pictures render at scale 1 with a fixed width, before the markdown pass checks them;diagramwraps more than four steps into rows of four so a long definition stays legible across the page
Added
- Child runs:
Runner.StartChildstarts an instance under a parent, recorded pending for the host's tick to run;RunRecord.ParentID,RunFilter.ParentIDandStore.CountDescendants(schema v6 addsparent_run_id); aStepwithChildandManyis a sub-process, drawn as one collapsed ⊞ box linking to the child definition; the instance page lists a run's children and links a child to its parent (#35)
Changed
- The
Definitionsregistry starts empty: a host sees only the workflows it runs.DailyUpdateis exported for gobank to register; the release definition,WorkflowReleaseandReleaseStagesleave the library for the demo app (task-plus declares its own);cmd/defd2moves into the demo (#36)
Fixed
- Instances page: the Filter and Clear buttons line up with the filter inputs; Bulma's field margin no longer pushes them down (#28)
- Docs build: d2 pictures render at scale 1 with a fixed width, before the markdown pass checks them;
diagramwraps more than four steps into rows of four so a long definition stays legible across the page (#40)
[0.10.0] - 2026-10-21
- Cancel: an operator ends an instance from the queue — a terminal
cancelledstatus,Store.CancelRun, and a Cancel button beside View for instances in hand but not running, offered when the host setsview.Views.Cancel
Added
- Cancel: an operator ends an instance from the queue — a terminal
cancelledstatus,Store.CancelRun, and a Cancel button beside View for instances in hand but not running, offered when the host setsview.Views.Cancel(#32)
[0.9.0] - 2026-10-21
- Rewind: an operator sends an instance back to an earlier stage, which and every later stage run again on the next tick;
Stage.Finalrefuses a rewind past work that must not be redone
Added
- Rewind: an operator sends an instance back to an earlier stage, which and every later stage run again on the next tick;
Stage.Finalrefuses a rewind past work that must not be redone (#29)
[0.8.0] - 2026-10-17
- sqlstore writes stamps fixed-width, so runs and steps list in time order within a second; schema v5 pads the stamps already written; Docs: a database schema page, a d2 diagram of the tables and their keys and a table of every column, held to the live schema by a test
Added
- Docs: a database schema page, a d2 diagram of the tables and their keys and a table of every column, held to the live schema by a test (#22)
Fixed
- sqlstore writes stamps fixed-width, so runs and steps list in time order within a second; schema v5 pads the stamps already written (#20)
Roadmap
- #11 Workflows page as a work queue — the default view is the current
instances, running, waiting and failed first, then the newest
completed, capped at n and grouped by purpose with each purpose's
newest instance as its headline ("upgrade: 0.4.2 running via
blue-green"). Filter is a GET form (purpose, workflow, status,
since, key contains, n), served and in WASM alike, backed by a
RunFilteronStore.ListRunsin place of the bare limit so the filtering is SQL. Drill-down is purpose → workflow (revisions as a filter) → instance → steps. Replaces the flat 500-row Instances page and the per-type list repeated on Definitions
[0.7.0] - 2026-10-17
- Instances page as a filterable work queue; Store.ListRuns takes a RunFilter (#11)
Added
RunFilter(#11):Store.ListRunstakes a filter — workflow types, statuses, created since (to the second), key contains (ignoring case,%and_literal), revision — orders (InHandFirst: the queue's order) and pages (Offset,Limit), all in the one SQL query.storetest.FilteredRunsis the contract.
Changed
Store.ListRuns(ctx, limit)is nowListRuns(ctx, RunFilter)(breaking;RunFilter{Limit: n}is the old call), and so isview.Reader's.- Instances page is a work queue (#11): the instances in hand (pending,
running, waiting, failed) first, then the completed, newest first in
each, n to a page (default 50, at most 500) with Previous/Next
(
?page=N), grouped by purpose with the purpose's newest instance as its headline. A GET form filters by purpose, workflow, status, since, key contains and n, on the server and in the WASM build alike. Drill-down is by link: purpose → workflow → revision → instance. A definition's page shows the same queue for its workflow in place of its own 500-run list.
[0.6.0] - 2026-10-17
- view package: reusable workflow pages (#21); demo account paging (#18)
Added
viewpackage (#21): the workflow pages (instances, an instance laid over the steps it ran, definitions, a definition with its instances, definition pictures and each instance as d2) as onehttp.Handlerover a read-only store. The host wraps pages in its layout viaFrameand adds type-specific content viaDetail. A stage shows its latest record by time, whatever order the store lists them in. Timestamps carry the date to the millisecond, and durations round to their scale, so runs of hours read as well as runs of milliseconds.
Changed
- Demo app uses
view; its account table and paging are itsDetail. - Demo app: an instance's account steps are paged, 50 per page with
Previous/Next and page links (
?page=N, clamped), in account order (#18). Previously only the first 50 were shown, in record order.
[0.5.0] - 2026-10-16
- Purpose and revision (#4): runs record and render the step list they ran
Added
- Purpose and revision (#4). A
Purpose(name, description) on eachDefinitionsays what the workflow achieves; it lives in the registry only, and the demo's definitions pages show it. ARevisionis the step list an attempt ran:RunPipelineandRunDailyrecord it on the run at creation and again at each restart, so a retry under changed code carries the new list. Instance pages anddiagram.Instancerender from the recorded revision throughDefinition.StepsFor, and the demo flags an instance whose revision is not the current one. Schema v4 (expand) addsrevisionandstep_namestoworkflow_runs; runs from before it render from the live definition as before.
Changed
Store.RestartRuntakes the new attempt'sRevision(breaking forStoreimplementations outside this module).
[0.4.0] - 2026-10-15
- Compensation: Stage.Undo reverses a completed stage when a later one fails (#3)
Added
- Compensation (#3):
Stage.Undoreverses a completed stage's work when a later stage fails. The runner undoes the completed stages before the failure in reverse order, nearest first, removes each undone stage's step so the next attempt runs it again, and names what was undone in the run's error; anUndothat fails is reported, keeps its step and stops the undoing there. A stage withoutUndokeeps its step and its work as before.Store.DeleteStepremoves a run's steps by name, in the memory and SQL stores and thestoretestcontract; no schema change. Written for gobank-deploy's perf and scenario runs, whose created server bills while a failed run sits.
Roadmap
- Compensation (#3):
Stage.Undoreverses a completed stage when a later one fails, so the next attempt starts from the first stage whose work no longer stands
[0.3.0] - 2026-10-09
- update documentation
Added
- Docs: writing workflows (
writing-workflows.md), the authoring contract: vocabulary, declaring a definition, the stage outcome table, resume and what it demands, what the host supplies, testing, drawing, a worked example compiled asexample_test.go, and a checklist runnertestpackage:OnlyRunandSteps, the store checks a workflow's own tests make, extracted from gobank-deploy's three flow harnesses
Roadmap
- Writing workflows: the authoring contract as a documentation section,
with a worked example compiled as
example_test.goand therunnertestkit
[0.2.0] - 2026-10-08
- Release prep
Added
- Waiting stages:
Stage.Untilis a condition the stage waits on. While it is false the run is parked aswaiting(a new run and step status) andRunPipelinereturns; the caller's next call re-evaluates it and continues the same attempt, so a wait survives a restart and only the status is persisted. Once it holds,Runexecutes if set.Store.WaitRunandStore.ResumeRunare the transitions; no schema change - Docs: comparison with other workflow engines (
research/comparison.md): Go libraries and the larger systems set against this one, with feature matrices, the closest relatives and a table of gaps and candidate additions
Roadmap
- Waiting stages:
Stage.Until, one mechanism for durable waits and human tasks; the caller's tick re-enters waiting runs
[0.1.3] - 2026-09-27
- Release pipeline runner, keyed instances, step status, definition diagrams, demo app
Added
-
Demo app (
cmd/demo,task demo, and in the docs as a WASM service-worker build): About, Workflows menu with time-ordered instances and a definitions explorer, instance pages showing state and steps, a simulation driver, and go-dbexplorer over the live schema -
internal/demoaccounts: the shared demo DayProcessor, with an injectable one-off failure -
releaseworkflow definition andRunner.RunPipeline: a keyed (version) multi-step instance whose steps are the pipeline stages; a failed stage stops the run and the next run resumes from it. Available from the demo app's simulation page with a choice of stage to fail -
Definition.StepsandInstanceKey: definitions describe their steps; the app's definition pages lead with them -
RunRecord.Key,StepResult.StatusandError;Store.FindRunByKey,RestartRun,DeleteSteps;storetestpackage with the Store contract checks -
diagrampackage andcmd/defd2: d2 source generated from the definitions registry, one diagram per definition, and an instance diagram with steps coloured by state; rendered into the docs and shown in the demo app, where an instance's d2 is downloadable -
Schema v2 (expand: instance key, step status) and v3 (contract: drop the date-only unique index)
Changed
- A retry is a new attempt at the same instance:
RunDailyrestarts the failed run in place instead of creating another, so the instance id is stable
Fixed
- A retry after a failed run no longer leaves two instances for one date in the memory store, and is no longer rejected by the SQL store's unique index
Roadmap
- Pipelines:
RunPipeline, an instance keyed by version whose steps are the stages, resumed from the failed stage; d2 from the registry (cmd/defd2); the demo app
[0.1.2] - 2026-09-25
- Schema versions, workflow definitions with instance counts by state
Added
- Schema versioning through gobank-db migrations:
sqlstore.Migrations, theSchemaVersionconstant andsqlstore.Store.SchemaVersion(ctx);sqlstore.Newrecords applied versions inschema_migrations Definitionsregistry of workflow types andStore.CountRuns, the number of instances of each definition in every state; shown on the daily processing demo with the schema version- Docs: workflow definitions, instance states and schema versions on the landing page
Changed
- SQL store moved to the
sqlstorepackage (sqlstore.New,sqlstore.Store); the core package no longer links database drivers, which keeps the WASM demo small
Roadmap
- End-of-day processing:
RunDailyidempotent per business date,CatchUpover a gap, the SQL store with its versioned schema, theDefinitionsregistry
[0.1.1] - 2026-09-25
- Release pipeline demo, docs site, module path moved to git.bytestone.uk
Added
- Release pipeline demo (
demo/deploy.html): steps through shipping a new gobank version, with injected failure and resume that retries only the failed stage - Release pipeline diagram (
release-pipeline.d2, rendered bytask docs:d2): the eight stages and the task-plus code that runs each undertp release - Docs published at https://gobank-workflow.docs.bytestone.uk/
Changed
- Module path is now
git.bytestone.uk/hum3/gobank-workflow(was codeberg.org); go-postgres dependency moved togit.bytestone.uk/hum3/go-postgresv0.5.13
[0.1.0] - 2026-03-27
- Release prep
Added
- Initial project scaffold