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

[inhuman]

What

Two example applications, a quickstart, a README written for a reader who
arrives cold, the live measurement that replaces three unbacked numbers — and
one real bug found along the way.

Format 2.2.2 → 2.2.3 (an engine fix; no field added, changed or removed).

The bug: a parallel branch lost six of the flow's fields

A branch's state was assembled by naming fields, and six were not named: the
assets, their resolver, cache and context, working memory, and the application's
vocabulary.

Nothing failed loudly, which is why it survived. An unknown asset expands to an
empty string by contract — that contract exists so a marker never reaches a
model — so {{asset:x}} inside a branch became "" and the tool call that
needed it lost a required argument. The error named the argument, not the
substitution.

Reproduced all three failure modes separately before fixing; they break
differently and all silently:

field	what it looks like
assets	a call loses a required argument
memory	a step reads a preview instead of the whole value
vocabulary	one_of loses its tie-breaker and stores nothing

It stayed hidden because in a live catalogue of 29 skills, not one call step
with an asset had ever sat inside a parallel branch.

Fixed by forking the parent state rather than rebuilding it, with the few
branch-local fields reset right after. A list has to be extended by whoever adds
a field to the engine, and that person is not thinking about parallel; forking
inverts the default, and what does NOT reach a branch is visible in one place.

The asset cache is shared with branches rather than cloned, so an asset three
branches need is fetched once — which makes it concurrent state, so it has a
lock, held across the resolve rather than around the map alone, and the mutex is
a pointer because a forked state copies the struct.

CI now runs -race. That was the widest hole here: parallel is goroutines
over shared state, and such bugs give a wrong answer under load rather than a
crash in the quiet. The first thing the detector caught was a test of my own —
see below.

Two properties documented, not changed

The step callbacks are concurrent. OnStep and OnStepStart fire from the
goroutine that ran the step, so inside a parallel they fire from several at
once. An embedder appending to a slice without a lock has a data race in
production. Not serialised inside the engine on purpose: a lock there would hold
up a branch for as long as somebody else's telemetry write takes.

Outcome.Steps stops at a parallel, Outcome.Skipped does not. Branch
steps reach OnStep as they happen, so nothing is lost — but the two fields
disagree, and that is invisible until somebody checks one and assumes the other.
Left as it is rather than "fixed": merging branch traces in would add entries for
every embedder reading that field, which is a behaviour change, not a bug fix. A
test pins the property and says what to do if it ever starts failing.

Examples

examples/ now holds the format AND how to embed it:

examples/skills/          the skill files, where they were
examples/simple-llm-app/  the engine embedded in ~200 lines, net/http only
examples/eino-llm-app/    the same, with the model reached through a framework

Both are separate modules, which is what keeps eino out of the engine's
go.mod — go list -deps ./... confirms it. Two guards hold that: the
self-containment walk skips nested modules, and a new test fails if a directory
with Go code loses its go.mod. Proven by deleting one — eino is reported as a
dependency of the engine on the next run.

CI vets and tests each example module separately, because go test ./... at the
top never descends into them.

Docs

QUICKSTART.md — fifteen minutes ending in an A/B the reader
runs themselves: one skill carrying both descriptions, same request, one flag
changed. 227 tokens as prose against 102 as steps, and on a request naming
nothing, prose answers while steps exit honestly. Steps 1–5 need no model:
the test stub charges by prompt length, and a test asserts the direction.

README gained what a cold reader looks for and never found: go get,
badges, a Status section (library v0.5.x, format 2.2.3, where it runs, and
the caveat that 1.x skills do not load until Migrate runs), and a "What this is
not" section — not a process orchestrator, not an agent framework, zero
dependencies as a consequence of being embedded, and when NOT to use it.

The measurement is real now. The three unbacked pairs of numbers are gone,
replaced by the event log of a working installation recomputed from the raw
rows: 23 skills, 5 280 turns, 20 significantly cheaper, 1 more expensive, 2
unchanged; with Holm–Bonferroni 16 of 23 survive. Stated as observational,
not an experiment — the periods are split by a date, not randomised, and other
things changed in those days. The skill that got worse is named plainly, followed
by the known ways a rewrite costs more.

A guard test keeps the two languages one document: same sections, same code
samples, every local link resolving.

Testing

• go vet ./... clean
• go test ./... -count=1 all green
• go test ./... -race all green — and the mutex proven load-bearing by
  removing it and watching the detector fire
• Both example modules vet and test green
• The bug was reproduced first, in three separate failure modes

No dependencies

• Production code still imports stdlib only (sync added, stdlib)
• eino lives in an example module and nowhere else

Format & API compatibility

• No field added, changed or removed; EngineVersion 2.2.2 → 2.2.3
• CHANGELOG.md updated
• Go API unchanged

Checklist

• Godoc added/updated for the documented properties
• No secrets / tokens in the diff

🤖 Generated with Claude Code