Examples, quickstart, the live measurement — and a parallel branch that lost its assets

.github/workflows/ci.yml

@@ -21,5 +21,26 @@ jobs:
       # outside the declared list.
       - name: Test
         run: go test ./... -count=1
+      # Branches of a `parallel` step run in goroutines that share what the flow
+      # was given. That sharing is deliberate — an asset three branches need is
+      # fetched once — and it is exactly the kind of thing only the race
+      # detector notices: a bug here is a wrong answer on a busy day, not a
+      # crash on a quiet one.
+      - name: Race
+        run: go test ./... -count=1 -race
       - name: govulncheck
         run: go run golang.org/x/vuln/cmd/govulncheck@v1.3.0 ./...
+
+      # The example applications are SEPARATE modules — that is what keeps their
+      # dependencies (eino, an SDK, whatever the next one uses) out of the
+      # engine's go.mod, and it also means `go test ./...` above never sees
+      # them. Without this step an example rots quietly, and an example that
+      # does not build teaches the format wrong.
+      - name: Examples
+        run: |
+          for mod in examples/*/go.mod; do
+            dir=$(dirname "$mod")
+            echo "── $dir"
+            go vet -C "$dir" ./...
+            go test -C "$dir" ./... -count=1
+          done

.gitignore

@@ -19,6 +19,9 @@ PLAN.md
 *.out
 *.test
 coverage.*
+# Собранные примеры: `go build` в их каталоге кладёт бинарник рядом с исходником
+examples/*/simple-llm-app
+examples/*/eino-llm-app
 
 # Окружение
 .env

CHANGELOG.md

@@ -21,6 +21,47 @@ wrap skills in something of your own — front matter, a markdown body, several
 documents in one file — unwrap before calling and wrap the result back;
 anything else is refused rather than guessed at.
 
+## 2.2.3
+
+An engine fix; the format itself did not change.
+
+- **Fixed**: a branch of a `parallel` step did not inherit the assets, their
+  resolver, cache and context, working memory, or the application's vocabulary.
+  The sub-state was assembled by listing fields, and those six were not on the
+  list.
+
+  Nothing failed loudly. An unknown asset expands to an empty string by
+  contract, so `{{asset:x}}` inside a branch quietly became "" and the tool call
+  that needed it lost a required argument — with the error pointing at the
+  argument rather than at the substitution. Working memory and the vocabulary
+  went the same way: a step in a branch read a preview instead of the whole
+  value, and `one_of` lost its tie-breaker.
+
+  It stayed hidden because in a live catalogue of 29 skills no `call` step with
+  an asset had ever sat inside a `parallel` branch.
+
+  The branch state is now FORKED from the flow's and the few branch-local
+  fields are reset explicitly, so a field added to the engine reaches branches
+  by default. The list had the opposite default, and whoever adds a field is
+  not thinking about `parallel`.
+
+  The asset cache is shared with the branches rather than copied into them, so
+  an asset three branches need is still fetched once — under a lock held across
+  the resolve. CI now runs the race detector.
+
+- **Documented, not changed**: `Deps.OnStep` and `Deps.OnStepStart` fire from
+  the goroutine that ran the step, so inside a `parallel` they fire from several
+  at once and a callback that appends to a slice needs its own lock. The engine
+  does not serialise them on purpose — a lock there would hold up a branch for
+  the duration of somebody else's telemetry write. Found by the race detector
+  added above, in a test written the way an embedder would write it.
+
+- **Documented, not changed**: `Outcome.Steps` stops at a `parallel` — the steps
+  inside its branches are not in it, while `Outcome.Skipped` does include them.
+  Branch steps reach `OnStep` as they happen, so nothing is lost; but the two
+  fields disagree, and a reader who checks one and assumes the other loses an
+  afternoon. Now stated on the type and pinned by a test.
+
 ## 2.2.2
 
 An engine fix; the format itself did not change.