fascicle 0.12.1 → 0.12.5

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (47) hide show
  1. package/CHANGELOG.md +113 -38
  2. package/README.md +16 -15
  3. package/dist/{adapters-hmnJOOgf.js → adapters-CutexJd3.js} +12 -12
  4. package/dist/adapters-CutexJd3.js.map +1 -0
  5. package/dist/adapters.d.ts +10 -10
  6. package/dist/adapters.js +1 -1
  7. package/dist/agents.d.ts +13 -3
  8. package/dist/agents.js +12 -5
  9. package/dist/agents.js.map +1 -1
  10. package/dist/{core-DDRhHu5P.js → core-DdJEhyQc.js} +122 -488
  11. package/dist/core-DdJEhyQc.js.map +1 -0
  12. package/dist/{engine-b4ZH8esY.js → engine-CdXegeqC.js} +201 -380
  13. package/dist/engine-CdXegeqC.js.map +1 -0
  14. package/dist/index.d.ts +111 -25
  15. package/dist/index.js +446 -48
  16. package/dist/index.js.map +1 -1
  17. package/dist/{invoke-CyKNhvBw.js → invoke-CH_eJZeS.js} +8 -8
  18. package/dist/{invoke-CyKNhvBw.js.map → invoke-CH_eJZeS.js.map} +1 -1
  19. package/dist/leading_system-BUCT-PwD.js +330 -0
  20. package/dist/leading_system-BUCT-PwD.js.map +1 -0
  21. package/dist/mcp.d.ts +5 -5
  22. package/dist/mcp.js +10 -9
  23. package/dist/mcp.js.map +1 -1
  24. package/dist/otel.d.ts +21 -3
  25. package/dist/otel.js +232 -12
  26. package/dist/otel.js.map +1 -1
  27. package/dist/stdio.d.ts +2 -2
  28. package/dist/stdio.js +2 -2
  29. package/dist/testing.d.ts +1 -1
  30. package/dist/testing.js +3 -2
  31. package/dist/testing.js.map +1 -1
  32. package/dist/{trajectory-cSLNlHzh.d.ts → trajectory-ByoOQZ6T.d.ts} +10 -10
  33. package/dist/trajectory-D1eq9eue.js +81 -0
  34. package/dist/trajectory-D1eq9eue.js.map +1 -0
  35. package/dist/{types-BCtKsxrX.d.ts → types-BK0UW28o.d.ts} +3 -3
  36. package/dist/{types-CXBB4aIM.d.ts → types-CLigYA62.d.ts} +30 -4
  37. package/dist/{types-BqUY6nRX.d.ts → types-DBpU27sQ.d.ts} +7 -2
  38. package/dist/ui.d.ts +1 -1
  39. package/dist/ui.js +1 -1
  40. package/dist/ui.js.map +1 -1
  41. package/dist/viewer.d.ts +8 -8
  42. package/dist/viewer.js +16 -15
  43. package/dist/viewer.js.map +1 -1
  44. package/package.json +10 -5
  45. package/dist/adapters-hmnJOOgf.js.map +0 -1
  46. package/dist/core-DDRhHu5P.js.map +0 -1
  47. package/dist/engine-b4ZH8esY.js.map +0 -1
package/CHANGELOG.md CHANGED
@@ -1,5 +1,80 @@
1
1
  # Changelog
2
2
 
3
+ ## v0.12.5 — 2026-08-21
4
+
5
+ Everything in v0.12.4 ships here for the first time: that version was tagged but never reached npm, because its publish run failed on the gate described below. Upgrading from v0.12.3 picks up both sections.
6
+
7
+ ### Fixed
8
+
9
+ - **A type error only CI could see.** `examples/otel-grafana/main.ts` imports `fascicle/otel`, which had no `tsconfig` `paths` entry, so TypeScript fell through to the package `exports` map and resolved the subpath from `./dist/otel.d.ts`. That file is present on any machine that has built before, so the `types` slot passed locally and failed on CI's clean checkout, where `pnpm check` runs ahead of `pnpm build`. `fascicle/viewer` carried the same gap with no importer to expose it yet. Both point at source now, and the `deps` slot fails if a published `exports` subpath ever loses its mapping again.
10
+
11
+ ### Internal
12
+
13
+ - **A failed check job keeps its evidence.** checkride prints one pass/fail line per slot and writes each tool's real output to `.check/`, so a red run named the failing slot without saying why. Every workflow that runs the suite now uploads that directory as an artifact on failure, minus the coverage and mutation report trees that account for most of its size.
14
+ - **The `claude_cli` spawn tests no longer race their own mock.** Both SIGTERM escalator tests slept 150ms to let the mock install its handler before signalling it, which is a bet on how long a cold Node start takes: measured spawn to handler ran from 42ms idle to 127ms under a process spawn storm against that budget. The mock now signals readiness through a file and the tests wait for it.
15
+
16
+ ## v0.12.4 — 2026-08-21
17
+
18
+ ### Added
19
+
20
+ - **Per-step model timing, and tokens per second derived from it.** Every step the tool loop produces carries a `StepTiming` block (`started_at`, `duration_ms`, and `first_chunk_ms` on streamed turns), stamped so only the successful attempt is measured: failed attempts, backoff waits, and tool execution never inflate the number. `throughput()` derives tokens per second from a `GenerateResult`, a step array, or a single step, and names its basis (`decode` when every turn streamed, `blended` when any window includes network and prefill). The ollama native adapter passes the daemon's own nanosecond durations through `provider_reported.ollama` verbatim.
21
+
22
+ - **The trajectory stream is dashboard-ready: retry events and opt-in OTel metrics.** `response_received` carries the full flat per-turn record, every absorbed retry becomes a `turn_retry` event (attempt, classified failure kind, HTTP status, and the honored backoff delay), and the closing `engine.generate` span reports step and tool-call counts. On the `fascicle/otel` side, span meta flattens one level so a dashboard can query `fascicle.usage.input_tokens`, and a new opt-in `metrics` option records the GenAI semconv client histograms plus cost and retry instruments, tagged with provider and model.
23
+
24
+ - **A Grafana walkthrough.** `docs/grafana.md` tells the end-to-end story for the `fascicle/otel` bridge: the mental model, a three-step keyless demo against the `grafana/otel-lgtm` container, wiring for a real app, what each metric means, and hand-built panel queries, with an importable dashboard JSON beside the example.
25
+
26
+ ### Changed
27
+
28
+ - **Every example lives in its own folder now, with a README and a screenshot of a real run.** The 28 single-file demos moved to `examples/<name>/main.ts`, the seven app workspaces kept their layout and gained screenshots, and the shared agents library got a README. The screenshots are captures rather than mockups: keyless demos as terminal renders, local Ollama and `claude` sessions for the model-backed ones, the viewer UI, and Grafana dashboard and Tempo trace views fed by the demo. Every cross-reference in `docs/`, the README, and the site follows the new paths.
29
+
30
+ - **`structured-output` and `tool-loop` run on the `openrouter` provider.** The pair used to require `ANTHROPIC_API_KEY`; they now read `OPENROUTER_API_KEY`, matching `live-smoke`, and their hand-rolled key guards are gone because `create_engine` already rejects an empty `api_key` with a message that names the fix.
31
+
32
+ ## v0.12.3 — 2026-08-19
33
+
34
+ ### Changed
35
+
36
+ - **Every id in a flow is a JavaScript identifier now.** Ids are read back as property names, because a `chain` binding merges its result into the growing record under its own name, and a binding you cannot destructure is one the record cannot offer. That constraint used to be emergent and unenforced, so `chain.step('user id', ...)` quietly cost you shorthand destructuring while `step('user id', ...)` beside it looked like it worked. `step`, `chain.step`, `chain`'s input name, and `define_agent` now hold ids to one rule and throw at construction when it is broken, naming both the spelling they would have picked and where the prose belongs instead. Nothing normalizes an id on your behalf, because a silent rewrite maps `my-id`, `my.id`, and `my id` onto a single key and would have to stay bug-for-bug in sync with the equivalent type-level rewrite. Generated ids moved to satisfy the same rule: a `model_call` without an explicit id reads `model_call_<hash>_<n>` rather than `model_call:<hash>:<n>`, and `loop` no longer folds its display name into its id, which is `loop_<n>` unconditionally. Code that parses either shape needs updating.
37
+
38
+ - **`compose` takes its config last, like everything else.** `compose(name, inner)` was the last positional-name holdout in the API, and its one string did two jobs, because it was the display label and the id prefix at once, so renaming a composite for readability moved its trajectory id. The form is `compose(inner, { name })` now, matching `sequence`, `parallel`, `pipe`, and the rest, and the id is `compose_<n>` with the label living only in `config.display_name`. The type is `ComposeConfig` rather than `ComposeOptions`, because the argument is required, which is the rule the rest of the composition layer already followed and AGENTS.md now states. The trade is that a composite that used to surface as `judge_llm_3` in an `error_path` surfaces as `compose_3`, with `judge_llm` still its span label. Set `id:` on the `model_call` inside it when a path has to name the role.
39
+
40
+ - **`StepMetadata.display_name` is `name`, and it finally does something.** The field had been declared since the type landed and nothing in `src/` ever read it, so a step carried a display channel on paper and none in practice, which is why step ids kept getting written for human eyes and then resisted becoming checkpoint keys. Every consumer that renders a step for a human now resolves the same order through `resolve_display_name`: `config.display_name` first, then `meta.name`, then the step's kind. `describe.json` echoes `meta` verbatim, so the key it emits changed with the field.
41
+
42
+ - **Six adapter and viewer types are named `Config` now.** A factory's trailing argument is named for whether you can drop it. It is `XConfig` when the argument is required and `XOptions` when it can be omitted, which is a rule `src/core` and `src/composites` had followed everywhere without anyone writing it down. The adapters and the viewer had not. `FilesystemLoggerOptions`, `FilesystemStoreOptions`, `HttpLoggerOptions`, `BroadcasterOptions`, `ServerOptions`, and `TailOptions` each take a required argument that carries required fields, so all six end in `Config` now, and the parameter each factory takes is `config` rather than `options`. AGENTS.md states the rule. `GenerateOptions` and `EngineConfig` keep the names they have, because the required-argument test and the required-field test disagree on both and neither name reads wrong.
43
+
44
+ - **Error messages name the remedy and carry the value.** Nineteen runtime messages were rewritten against the one already in the tree that got it right, `no provider specified: pass ... (configured: anthropic, ollama)`, which states the symptom, the fix, and the state the caller needs. Six numeric-bound errors stated a constraint and swallowed the input, so `turn_timeout_ms must be > 0` now reports what it got, matching the `retry: max_attempts ... got X` shape that already existed. `engine_disposed_error`, the `checkpoint` and `gate` anonymous-step guards, tool approval with no handler, and the `claude_cli` execute-closure rejection each name what to do next. Nothing about the errors' types, `kind` discriminants, or thrown classes moved; code that matches on an error's message text rather than its `kind` will need updating, which is the reason `kind` exists.
45
+
46
+ - **`provider_not_configured_error` reports what the engine can route to.** The error meaning "you named a provider this engine has no adapter for" withheld the list you would check the name against. It now takes the configured names as an optional second constructor argument, exposes them as a readonly `configured` array, and prints them, exactly as its sibling `provider_required_error` already did.
47
+
48
+ - **`fascicle-viewer` prefixes every line it writes.** Five of its eight stderr lines carried a `fascicle-viewer:` prefix and three did not, so `watching <path>` and `viewer at <url>` were anonymous in a terminal running more than one thing, while `shutting down` beside them was labelled. All of them carry it now, and a bad `--port` or `--buffer` says what a valid value looks like instead of only echoing the rejected one.
49
+
50
+ ### Added
51
+
52
+ - **A display label on chain bindings and on agents.** `chain.step(name, fn, { name })` and its arm form `chain.step(name, arm, select, { name })` label the binding's span and its `describe` line without touching the record key, which is the same split `step(id, fn, { name })` gives a plain step. `define_agent` gained `config.id` beside `config.name`, so an agent whose frontmatter reads `name: Change Triage` keeps that prose as its label and takes `id: 'change_triage'` as its identity. The `agent.call` event carries both now, since the two can differ and a consumer holding only the name could not join back to the span.
53
+
54
+ - **The identifier rule and the label rule are exported.** `is_valid_step_id`, `suggest_step_id`, and `assert_valid_step_id` come out of `fascicle`, so a harness that mints ids of its own can hold them to the same rule the factories use, and can reuse the message shape rather than inventing a second one. `resolve_display_name` is exported beside them for anything that renders a step tree and wants the label a span would have opened under.
55
+
56
+ - **The `security` slot gates the check suite.** `pnpm audit --audit-level=high` had sat outside the loop since the checkride config landed, as a `check:security` script nothing ran, so a new high advisory reached a release without failing anything. The slot is now in the default set, which is what CI runs, and clearing it took one devDependency bump (`markdownlint-cli2` 0.23.2, whose pinned `js-yaml` is patched), a `vite ^8.0.16` override for the `server.fs.deny` bypass under vitest, and a lockfile re-resolution that carried the other twelve advisories across. `check:security` is now `checkride --only security`, so the gate has one implementation rather than two that can disagree. Nothing in the published package changed: every advisory was dev-tree only, and `dependencies` is still empty.
57
+
58
+ - **The `prose` slot: how the words read is checked now.** The gate covered types, structure, dead code, spelling, and markdown lint, and nothing looked at the writing. Vale runs over markdown and TypeScript doc comments with rules the repo owns outright, copied in rather than installed, so disagreeing with one means editing it. `.vale/exemplars/` holds seven excerpts of the author's own published writing, verbatim and nothing later than 2022, so no sample can have been shaped by a model, and an `exemplars` check fails on any diff to them. `scripts/prose-health.mjs` measures the thing vale cannot see, which is a whole file drifting compressed, and ratchets each file against its own past rather than against a target.
59
+
60
+ - **Two prose rules that reach string literals.** Vale maps `ts = js`, which lints doc comments and leaves the code alone, so no user-facing message in this package had ever been checked against a house rule. `rules/no-latin-abbrev-in-strings.yml` and `rules/no-em-dash-pair-in-strings.yml` mirror the vale rules of the same name into ast-grep, run in the `struct` slot, and cover `src`, `test`, and `examples`. Message *shape* stays a matter of judgment and gets no rule, because "does this name a remedy" is not something a matcher can decide.
61
+
62
+ ### Fixed
63
+
64
+ - **The docs printed a peer-dependency error the package does not emit.** `providers.md` twice and `troubleshooting.md` once showed `missing peer dependency 'X'. Install it with: pnpm add X`, while the code has long said `Install it with your package manager, e.g., ... or npm install X`. The docs now quote the message as thrown.
65
+
66
+ - **The `fascicle-viewer` help and the doc that documents it disagreed.** `--buffer <n>` sat one space short of the four flags beside it, and `docs/viewer.md` had the same block correctly aligned. The usage example in the CLI's own header comment was misaligned in the other direction.
67
+
68
+ - **Comments and markdown that describe a layout this repo left behind.** Four doc comments narrated design history rather than present behavior, three named a contract test, a provider option, and source paths that do not exist, and `src/core/BACKLOG.md` still carried the `@repo/core` package name from the workspace v0.8.0 collapsed into one. The `claude_cli` test README listed 9 of its 14 test files, promised a `grep` that finds all 31 spec items when it finds 22, and documented a `RUN_E2E=1` gate that appears nowhere else in the repo. The amplify example's layout tree advertised a `src/state.ts` that the app deliberately does not have, its flow being built on `chain` bindings.
69
+
70
+ ### Internal
71
+
72
+ - **`docs/` was moved toward the voice in the exemplars.** A sweep across every page restored the relative clauses a compression pass had eaten, split the sentences doing too much, and put the doc comments back in the present tense. Headings went to Chicago Title Case, 232 of them, chosen over AP because AP accepts "Where to Put the Harness" and rejects "Where to Go Next", a distinction no writer can predict. A `HeadingCase` rule holds the line.
73
+
74
+ - **The three site pages were rewritten.** `site/*.html` is the one body of hand-written prose here that nothing gates, because vale is scoped to markdown and TypeScript and the prose-health corpus is `docs/` plus the top-level markdown. Extracting the text nodes and running both tools over them turned up eleven error-level violations that would have failed the `prose` slot anywhere else. The hero pitch leads with the claim rather than the mechanism now, and the primitive groups are separated.
75
+
76
+ - **The `claude_cli` spec items are all tagged.** The README promised that `grep -R '§12 #'` finds every one of the 31 items and it found 22. Tagging the missing nine restored the claim, and turned up two existing tags that pointed at the wrong item.
77
+
3
78
  ## v0.12.1 — 2026-08-18
4
79
 
5
80
  ### Added
@@ -22,7 +97,7 @@
22
97
 
23
98
  - **Every type a public signature names.** The composer configs (`SequenceOptions`, `ParallelOptions`, `BranchConfig`, `MapConfig`, `PipeOptions`, `RetryConfig`, `FallbackOptions`, `TimeoutOptions`, `CheckpointConfig`, `SuspendConfig`, `ScopeOptions`, `StashOptions`, `UseOptions`, `GateConfig`), the run vocabulary (`RunOptions`, `StreamingRunHandle`, `StepFn`, `CleanupFn`), the schema vocabulary (`ToolSchema`, `AnySchema`, `SchemaIssue`), `ClaudeCliErrorReason`, and the extractors `StepInput<s>` / `StepOutput<s>` are exported now, and `is_step` joins `is_step_kind` at runtime. Writing the wrapper factories the blueprint teaches no longer requires `Parameters<typeof run>[2]`.
24
99
 
25
- - **A typed error path.** Every fascicle error class declares `path`, and `error_path(err)` reads it off any thrown value, including a foreign error the runner tagged on its way out. The documented diagnostic previously required a cast.
100
+ - **A typed error path.** Every Fascicle error class declares `path`, and `error_path(err)` reads it off any thrown value, including a foreign error the runner tagged on its way out. The documented diagnostic previously required a cast.
26
101
 
27
102
  - **CommonJS consumers can `require()` the package.** Each export entry gained a `default` condition pointing at the same ESM file, so Node's native `require(esm)` resolves it on the supported Node 24 floor. No CJS build, no second artifact.
28
103
 
@@ -86,9 +161,9 @@
86
161
 
87
162
  - **Compile-time joint checking for literal `sequence` tuples.** Each child of a literal tuple must accept its predecessor's output, and a mismatch errors on the offending element. Arrays built at runtime still degrade to unknown boundaries; annotate the outer `Step<In, Out>` to keep the flow's boundary checked.
88
163
 
89
- - **Docs for the layering.** `docs/leaf-arm-spine.md` names the leaf / arm / spine shape and the decision rules at each layer, `docs/advanced-composition.md` covers the demoted tier (`scope`/`stash`/`use`, plain `ensemble`, `tournament`, `improve`/`learn`), and `examples/newsroom.ts` is the vocabulary tour that uses every primary primitive once.
164
+ - **Docs for the layering.** `docs/leaf-arm-spine.md` names the leaf / arm / spine shape and the decision rules at each layer, `docs/advanced-composition.md` covers the demoted tier (`scope`/`stash`/`use`, plain `ensemble`, `tournament`, `improve`/`learn`), and `examples/newsroom/main.ts` is the vocabulary tour that uses every primary primitive once.
90
165
 
91
- - **A one-file style pair in the examples.** `examples/release_notes.ts` and `examples/release_notes_direct.ts` build the same release-notes flow two ways — composed through `chain` and arms, and written straight through as one function — so the cost and the benefit of composing are readable side by side rather than asserted. `docs/blueprint.md` is rebuilt around `chain` and points at the pair.
166
+ - **A one-file style pair in the examples.** `examples/release-notes/main.ts` and `examples/release-notes-direct/main.ts` build the same release-notes flow two ways (composed through `chain` and arms, and written straight through as one function), so the cost and the benefit of composing are readable side by side rather than asserted. `docs/blueprint.md` is rebuilt around `chain` and points at the pair.
92
167
 
93
168
  ### Changed
94
169
 
@@ -117,9 +192,9 @@
117
192
 
118
193
  ### Changed
119
194
 
120
- - **A tool's JSON Schema no longer requires the fields that carry a default.** Provider payloads were emitted through Standard JSON Schema's *output* direction, which describes a value that has already been parsed: defaults are filled in by then, so `z.object({ city: z.string(), units: z.string().default('celsius') })` reached the model as `required: ["city","units"]`. That asked the model to supply a value the schema itself supplies, and made a defaulted field indistinguishable from a mandatory one. Emission now uses the *input* direction, which describes what the model should produce, so the same tool arrives as `required: ["city"]`. The input direction on its own also drops `additionalProperties: false` — the guard that stops a model inventing keys, and a prerequisite of several providers' strict and constrained-decode modes — so it is composed with a pass that closes every object node the vendor left open. This is the same pairing `@ai-sdk/provider-utils` applies to every `kind: 'ai_sdk'` provider (all seven fascicle configures by default), so the native adapters and `claude_cli` now send what the AI SDK path was already sending rather than a second, stricter shape for the same tool. Two restraints keep the closing pass from asserting more than the vendor did: an existing `additionalProperties` is never overwritten, so `z.looseObject`, a `z.record`'s value schema, and a server that published `true` all stay open (the AI SDK overwrites these); and a node is closed only if it declares `properties`, so a bare `{ type: 'object' }` — how a freeform payload is advertised — is left alone instead of being narrowed to "no keys permitted". One capability comes with it: `.output()` throws on a schema carrying a transform (`Transforms cannot be represented in JSON Schema`), so a tool whose schema contained one could not reach a native provider at all; the input direction emits it. **Breaking** on the wire for any tool or structured-output schema with a `.default()` or `.catch()` field: that field moves out of `required`, at every depth, including inside arrays and unions. Schemas without one are byte-identical to before, key order included. A knock-on for MCP: v0.10.3 made an inbound server's advertised schema reach the provider verbatim, and closing objects narrows that — a server that declares `properties` but says nothing about `additionalProperties` now has `additionalProperties: false` added on the native transports. The AI SDK path already did this to those same schemas, so the effect is that MCP tools now behave the same across all transports rather than differing by the one in use.
195
+ - **A tool's JSON Schema no longer requires the fields that carry a default.** Provider payloads were emitted through Standard JSON Schema's *output* direction, which describes a value that has already been parsed: defaults are filled in by then, so `z.object({ city: z.string(), units: z.string().default('celsius') })` reached the model as `required: ["city","units"]`. That asked the model to supply a value the schema itself supplies, and made a defaulted field indistinguishable from a mandatory one. Emission now uses the *input* direction, which describes what the model should produce, so the same tool arrives as `required: ["city"]`. The input direction on its own also drops `additionalProperties: false` (the guard that stops a model inventing keys, and a prerequisite of several providers' strict and constrained-decode modes), so it is composed with a pass that closes every object node the vendor left open. This is the same pairing `@ai-sdk/provider-utils` applies to every `kind: 'ai_sdk'` provider (all seven Fascicle configures by default), so the native adapters and `claude_cli` now send what the AI SDK path was already sending rather than a second, stricter shape for the same tool. Two restraints keep the closing pass from asserting more than the vendor did: an existing `additionalProperties` is never overwritten, so `z.looseObject`, a `z.record`'s value schema, and a server that published `true` all stay open (the AI SDK overwrites these); and a node is closed only if it declares `properties`, so a bare `{ type: 'object' }` (how a freeform payload is advertised) is left alone instead of being narrowed to "no keys permitted". One capability comes with it: `.output()` throws on a schema carrying a transform (`Transforms cannot be represented in JSON Schema`), so a tool whose schema contained one could not reach a native provider at all; the input direction emits it. **Breaking** on the wire for any tool or structured-output schema with a `.default()` or `.catch()` field: that field moves out of `required`, at every depth, including inside arrays and unions. Schemas without one are byte-identical to before, key order included. A knock-on for MCP: v0.10.3 made an inbound server's advertised schema reach the provider verbatim, and closing objects narrows that — a server that declares `properties` but says nothing about `additionalProperties` now has `additionalProperties: false` added on the native transports. The AI SDK path already did this to those same schemas, so the effect is that MCP tools now behave the same across all transports rather than differing by the one in use.
121
196
 
122
- - **`loop` no longer wraps its output in a result envelope.** It returned `Step<i, LoopResult<o>>` — `{ value, converged, rounds }` — so anything that wanted the projected value had to strip `.value` first, and every one of the six in-repo call sites did: `adversarial` and `consensus` each carried a whole `pipe` for it, `improve` had an `improve_unwrap` step, the researcher agent wrapped its loop in a second `step` that called `inner.run` by hand (skipping the loop's own span) purely to return `result.value`, and both example apps hopped through `.value` at the read site. The envelope was a second projection channel layered over the one `loop` already had: `finish` is where the final state becomes the output, and it was already handed a piece of loop metadata (`round: number`) that no call site used. It now receives all of it — `finish: (state, outcome: LoopOutcome) => o`, with `LoopOutcome` being `{ converged, rounds }` — and `loop` returns `Step<i, o>`: exactly what `finish` projects, nothing around it. Non-convergence is still data rather than error; it arrives as an argument instead of a wrapper, which is why this shape was chosen over an `unwrap: true` flag (that would have needed two return types on one function, and would have discarded `converged` silently — the datum the whole convention rests on). Nothing is lost by dropping the envelope, because `finish` and the `loop({...})` call site always have the same author: the old shape is `finish: (state, outcome) => ({ value: state, ...outcome })`, opt-in in one line. Trajectories are unaffected: a traced composer's span records `{ id }` only, so `converged` and `rounds` were never in the trace to begin with. **Breaking:** `LoopResult` is gone from the published surface, replaced by `LoopOutcome`; a `loop` step's output type is now `o`; and a `finish` that declared a second parameter now receives the outcome object where the round count used to be. `docs/composition.md`, `docs/api-reference.md`, and `docs/deliberation-as-composition.md` state the new shape. In `examples/pr-improve` the `LOOP_RESULT` scope key becomes `FINAL_STATE`, since what the loop stashes is now the carry-state itself — whose own `round` field counts the same rounds the envelope reported.
197
+ - **`loop` no longer wraps its output in a result envelope.** It returned `Step<i, LoopResult<o>>` (`{ value, converged, rounds }`), so anything that wanted the projected value had to strip `.value` first, and every one of the six in-repo call sites did: `adversarial` and `consensus` each carried a whole `pipe` for it, `improve` had an `improve_unwrap` step, the researcher agent wrapped its loop in a second `step` that called `inner.run` by hand (skipping the loop's own span) purely to return `result.value`, and both example apps hopped through `.value` at the read site. The envelope was a second projection channel layered over the one `loop` already had: `finish` is where the final state becomes the output, and it was already handed a piece of loop metadata (`round: number`) that no call site used. It now receives all of it (`finish: (state, outcome: LoopOutcome) => o`, with `LoopOutcome` being `{ converged, rounds }`), and `loop` returns `Step<i, o>`: exactly what `finish` projects, nothing around it. Non-convergence is still data rather than error; it arrives as an argument instead of a wrapper, which is why this shape was chosen over an `unwrap: true` flag (that would have needed two return types on one function, and would have discarded `converged` silently — the datum the whole convention rests on). Nothing is lost by dropping the envelope, because `finish` and the `loop({...})` call site always have the same author: the old shape is `finish: (state, outcome) => ({ value: state, ...outcome })`, opt-in in one line. Trajectories are unaffected: a traced composer's span records `{ id }` only, so `converged` and `rounds` were never in the trace to begin with. **Breaking:** `LoopResult` is gone from the published surface, replaced by `LoopOutcome`, and a `loop` step's output type is now `o`. A `finish` that declared a second parameter now receives the outcome object where the round count used to be. `docs/composition.md`, `docs/api-reference.md`, and `docs/deliberation-as-composition.md` state the new shape. In `examples/pr-improve` the `LOOP_RESULT` scope key becomes `FINAL_STATE`, since what the loop stashes is now the carry-state itself — whose own `round` field counts the same rounds the envelope reported.
123
198
 
124
199
  ### Internal
125
200
 
@@ -139,23 +214,23 @@
139
214
 
140
215
  ### Added
141
216
 
142
- - **`ai` is now an optional peer dependency.** It was the last mandatory peer on a package whose own `dependencies` block is empty, so `pnpm add fascicle` forced an install of the AI SDK core even for a `transport: 'native'`-only or `claude_cli`-only setup that never imports it. `ai` is loaded lazily from the one `ai_sdk` turn seam (`src/engine/generate.ts`), same as every `@ai-sdk/*` provider package, so it drops to `peerDependenciesMeta: { ai: { optional: true } }` alongside them; a missing `ai` reports through the same `load_optional_peer` message step 7 named it in. `docs/providers.md` and `README.md` now show `ai` alongside each `ai_sdk`-kind provider's install snippet, since the official `@ai-sdk/*` packages only peer-depend on `zod`, not `ai` — installing just `@ai-sdk/anthropic` no longer pulls `ai` in transitively now that fascicle's own peer is optional.
217
+ - **`ai` is now an optional peer dependency.** It was the last mandatory peer on a package whose own `dependencies` block is empty, so `pnpm add fascicle` forced an install of the AI SDK core even for a `transport: 'native'`-only or `claude_cli`-only setup that never imports it. `ai` is loaded lazily from the one `ai_sdk` turn seam (`src/engine/generate.ts`), same as every `@ai-sdk/*` provider package, so it drops to `peerDependenciesMeta: { ai: { optional: true } }` alongside them; a missing `ai` reports through the same `load_optional_peer` message step 7 named it in. `docs/providers.md` and `README.md` now show `ai` alongside each `ai_sdk`-kind provider's install snippet, since the official `@ai-sdk/*` packages only peer-depend on `zod`, not `ai` — installing just `@ai-sdk/anthropic` no longer pulls `ai` in transitively now that Fascicle's own peer is optional.
143
218
 
144
219
  - **`BenchOptions` gains `abort`, and a cancelled bench rejects instead of returning a report.** `bench` accepted no signal at all and defaulted `install_signal_handlers` to `false`, so there was no cancellation path through a bench run. The signal now forwards to every per-case `run` and is re-checked before each case is claimed, so an abort halts scheduling at the queue rather than only cancelling work already in flight, and it is checked once more before the report is built, so neither a full fan-out (no queue to halt) nor a flow that ignores `ctx.abort` can yield a report for a run the caller cancelled. An `aborted_error` raised inside a case or a judge propagates rather than being flattened into `ok: false`. Abort reasons follow core's shape: an `Error` reason propagates verbatim, anything else is wrapped in `aborted_error`.
145
220
 
146
221
  ### Changed
147
222
 
148
- - **`zod` is now an optional peer dependency, and fascicle has zero mandatory peers.** It was the last one: `ai` went optional earlier in this release, and the Standard Schema migration removed every internal zod import from `src/` except the type-only one in `src/mcp/serve.ts` (`McpServer.registerTool` accepts nothing else). `zod` drops to `peerDependenciesMeta: { zod: { optional: true } }` alongside every other peer, so `pnpm add fascicle` alone builds and runs a flow against `transport: 'native'` or `claude_cli` — no AI SDK, no schema library. Schemas accept any Standard Schema implementation (zod, ArkType, Valibot, …); installing zod remains necessary only if that is the vendor you choose. The `no-core-npm-dep-except-zod` and `no-engine-npm-dep-except-ai-zod` ast-grep rules, which permitted an npm dependency neither zone still uses, are replaced by `no-core-npm-dep` and `no-engine-npm-dep`: core and engine (outside `providers/`) now depend on no npm package at all, matching the `#schema`/`#policy` bottom-of-DAG zones that already carry the vendor-specific code. `README.md`, `docs/getting-started.md`, `VALUES.md`, and `SECURITY.md` state the zero-mandatory-peers posture directly.
223
+ - **`zod` is now an optional peer dependency, and Fascicle has zero mandatory peers.** It was the last one: `ai` went optional earlier in this release, and the Standard Schema migration removed every internal zod import from `src/` except the type-only one in `src/mcp/serve.ts` (`McpServer.registerTool` accepts nothing else). `zod` drops to `peerDependenciesMeta: { zod: { optional: true } }` alongside every other peer, so `pnpm add fascicle` alone builds and runs a flow against `transport: 'native'` or `claude_cli` — no AI SDK, no schema library. Schemas accept any Standard Schema implementation (zod, ArkType, Valibot, …); installing zod remains necessary only if that is the vendor you choose. The `no-core-npm-dep-except-zod` and `no-engine-npm-dep-except-ai-zod` ast-grep rules, which permitted an npm dependency neither zone still uses, are replaced by `no-core-npm-dep` and `no-engine-npm-dep`: core and engine (outside `providers/`) now depend on no npm package at all, matching the `#schema`/`#policy` bottom-of-DAG zones that already carry the vendor-specific code. `README.md`, `docs/getting-started.md`, `VALUES.md`, and `SECURITY.md` state the zero-mandatory-peers posture directly.
149
224
 
150
225
  - **The trajectory wire format is now read through hand-written guards instead of zod schemas.** The five exported schemas — `trajectory_event_schema`, `span_start_event_schema`, `span_end_event_schema`, `emit_event_schema`, and `custom_event_schema` — put a zod object on the published surface of a package that is dropping zod to an optional peer, so a consumer who never writes a zod schema still resolved zod to read a trajectory file. They are replaced by `parse_trajectory_event(value)`, which returns the same `safeParse` shape (`{ success: true, data }` / `{ success: false, error }`), and four type guards: `is_span_start_event`, `is_span_end_event`, `is_emit_event`, `is_custom_trajectory_event`. What parses is unchanged, deliberately down to the permissiveness: an event is any non-array object carrying a string `kind`, so a `span_start` line missing its `span_id` is still accepted as an event (the old ordered union fell through to `custom_event_schema` for exactly that case) and the well-known guards are recognizers layered on top rather than gates. `is_custom_trajectory_event` therefore answers `true` for well-known kinds too, matching `custom_event_schema` before it. Two visible differences: a successful parse now hands the wire value straight back rather than a shallow zod clone, so nothing is dropped on the way through — including a literal `__proto__` key, which zod's clone silently swallowed and which now rides along as the inert own property `JSON.parse` produced (no prototype is mutated either way) — and the failure `error` is a plain `Error` rather than a `ZodError`, so code reading `.issues` off it needs the line itself instead (the viewer's `on_parse_error` already receives that as its second argument). The exported types keep their names (`SpanStartEvent`, `SpanEndEvent`, `EmitEvent`, `CustomTrajectoryEvent`, `ParsedTrajectoryEvent`) and shapes, joined by `TrajectoryParseResult`. **Breaking:** any of the five schema exports, or `ZodError`-shaped handling of a rejected line.
151
226
 
152
- - **Every schema fascicle validates now runs through Standard Schema, so validation failures read the same whichever library produced them.** Tool inputs, structured-output parsing, `suspend` resume data, and both `run_stdio` IO checks called zod's `safeParse` directly and reported whatever zod handed back. They now go through the vendor-neutral `~standard.validate` interface, so an ArkType or Valibot schema validates on the same path a zod one does. Two things consumers can see change shape. The message fed back to a model on a rejected tool call (and the schema repair prompt, and `schema_validation_error.message`) was zod's own multi-line JSON dump of its issue objects; it is now one line of `path: message` clauses with dotted paths — `city: Invalid input: expected string, received number; opts.deep: Invalid input: expected boolean, received string`. And the `cause` on a `run_stdio` `validate_input` / `validate_output` failure now carries `{ message, path }` issues instead of zod's issue objects, so the `code` and `expected` fields are gone from that JSON. Nothing that was validated before validates differently: only the report changed.
227
+ - **Every schema Fascicle validates now runs through Standard Schema, so validation failures read the same whichever library produced them.** Tool inputs, structured-output parsing, `suspend` resume data, and both `run_stdio` IO checks called zod's `safeParse` directly and reported whatever zod handed back. They now go through the vendor-neutral `~standard.validate` interface, so an ArkType or Valibot schema validates on the same path a zod one does. Two things consumers can see change shape. The message fed back to a model on a rejected tool call (and the schema repair prompt, and `schema_validation_error.message`) was zod's own multi-line JSON dump of its issue objects; it is now one line of `path: message` clauses with dotted paths — `city: Invalid input: expected string, received number; opts.deep: Invalid input: expected boolean, received string`. And the `cause` on a `run_stdio` `validate_input` / `validate_output` failure now carries `{ message, path }` issues instead of zod's issue objects, so the `code` and `expected` fields are gone from that JSON. Nothing that was validated before validates differently: only the report changed.
153
228
 
154
- - **Schema failures are now reported vendor-neutrally end to end, closing out the zod-shaped naming and reporting left over from the Standard Schema migration.** `schema_validation_error` (thrown by `generate` and the `claude_cli` adapter after repair attempts are exhausted) carried a field named `.zod_error`; it is renamed `.schema_issues` and now holds the vendor-neutral `{ message, path? }` issue list directly rather than an `Error` wrapping a pre-formatted string. The engine's `schema_validation_failed` trajectory event's `zod_issues` field is renamed `schema_issues` (same one-line formatted string as before). `suspend`'s `resume_validation_error.issues` — called out above as unchanged — now also carries the vendor-neutral issue list instead of a hand-rolled reproduction of zod's `{ formErrors, fieldErrors }` shape. The internal `format_zod_error` helper is gone; formatting goes through `format_schema_issues` everywhere. **Breaking:** code reading `schema_validation_error.zod_error`, `resume_validation_error.issues.formErrors` / `.fieldErrors`, or a trajectory consumer reading `schema_validation_failed.zod_issues` needs to move to the renamed fields and shapes.
229
+ - **Schema failures are now reported vendor-neutrally end to end, closing out the zod-shaped naming and reporting left over from the Standard Schema migration.** `schema_validation_error` (thrown by `generate` and the `claude_cli` adapter after repair attempts are exhausted) carried a field named `.zod_error`; it is renamed `.schema_issues` and now holds the vendor-neutral `{ message, path? }` issue list directly rather than an `Error` wrapping a pre-formatted string. The engine's `schema_validation_failed` trajectory event's `zod_issues` field is renamed `schema_issues` (same one-line formatted string as before). `suspend`'s `resume_validation_error.issues` (called out above as unchanged) now also carries the vendor-neutral issue list instead of a hand-rolled reproduction of zod's `{ formErrors, fieldErrors }` shape. The internal `format_zod_error` helper is gone; formatting goes through `format_schema_issues` everywhere. **Breaking:** code reading `schema_validation_error.zod_error`, `resume_validation_error.issues.formErrors` / `.fieldErrors`, or a trajectory consumer reading `schema_validation_failed.zod_issues` needs to move to the renamed fields and shapes.
155
230
 
156
231
  - **An inbound MCP tool now reaches the model with the schema its server actually advertised.** The bridge converted a server's JSON Schema into a Zod schema so the tool loop could validate it, and the provider path then converted that Zod back into JSON Schema — a round trip the old file's own header conceded was lossy. It dropped every value constraint on the way through: `minLength`, `maxItems`, `format`, `pattern`, and `enum` descriptions were modeled as plain types, so a model calling an MCP tool was told less about its arguments than the server had published. The bridge now builds a Standard Schema directly over the advertised JSON Schema, and emission hands that schema back verbatim in both directions, so what the server declared is what the provider receives. Validation is unchanged in reach — structure, types, enums, const, unions, and required keys are checked, value constraints are not, extra keys still pass through to the server, and anything unrecognized still accepts — because the server re-validates its own arguments and is the authority on them. Two visible consequences of verbatim emission: a server that declares `additionalProperties: false` now has that reach the provider instead of being loosened away, and `$schema` / `$id` keys the server published now ride along on the transports that accept them. The MCP path no longer imports zod at all. **Breaking:** the `fascicle/mcp` export `json_schema_to_zod` is renamed `json_schema_to_standard` and returns a `ToolSchema` rather than a `z.ZodType`, so a caller using it directly validates through `~standard.validate` (async) instead of `safeParse`.
157
232
 
158
- - **The `zod` peer dependency is pinned to exactly `4.4.3`, up from `^4.0.0`.** fascicle is moving to emit provider JSON Schema through Standard JSON Schema (`~standard.jsonSchema`) rather than `z.toJSONSchema`, and that interface does not exist before zod 4.2.0: on 4.1.12 `~standard.jsonSchema` is `undefined`, so the old `^4.0.0` range named a floor that cannot work. The pin is exact rather than a range so that the one version fascicle is tested against is the one version it promises; 4.2.0 and 4.4.3 emit byte-identical draft-2020-12 schemas, so this is a choice about which version is guaranteed, not about behaviour. **Breaking:** an install that resolves zod to any other version, including a later patch such as 4.4.4, now reports a peer dependency conflict, and a project whose other packages peer-depend on a zod range excluding 4.4.3 cannot satisfy both at once. zod is an optional peer as of this release, which lifts the requirement for anyone who never installs it, but a consumer using zod schemas with fascicle still has to be on 4.4.3.
233
+ - **The `zod` peer dependency is pinned to exactly `4.4.3`, up from `^4.0.0`.** Fascicle is moving to emit provider JSON Schema through Standard JSON Schema (`~standard.jsonSchema`) rather than `z.toJSONSchema`, and that interface does not exist before zod 4.2.0: on 4.1.12 `~standard.jsonSchema` is `undefined`, so the old `^4.0.0` range named a floor that cannot work. The pin is exact rather than a range so that the one version Fascicle is tested against is the one version it promises; 4.2.0 and 4.4.3 emit byte-identical draft-2020-12 schemas, so this is a choice about which version is guaranteed, not about behaviour. **Breaking:** an install that resolves zod to any other version, including a later patch such as 4.4.4, now reports a peer dependency conflict, and a project whose other packages peer-depend on a zod range excluding 4.4.3 cannot satisfy both at once. zod is an optional peer as of this release, which lifts the requirement for anyone who never installs it, but a consumer using zod schemas with Fascicle still has to be on 4.4.3.
159
234
 
160
235
  - **`retry` (composition layer) now jitters its backoff by default and caps it at 30s.** `RetryConfig` gains `max_delay_ms` (defaults to 30_000, matching the engine retry layer's cap) and `jitter` (defaults to `true`), both now expressed through the `#policy` backoff algebra the engine retry layer already used. Un-jittered retries from concurrent callers stampede back onto a recovering dependency in lockstep, and jittering is cheapest to add now, before `retry` has callers depending on its old exact-doubling delays. **Breaking:** a `retry(...)` call with a large `backoff_ms` or high `max_attempts` now serves a longer, randomized delay per attempt and is capped at 30s where it was previously uncapped; pass `jitter: false` and an explicit `max_delay_ms` to keep the old behavior exactly. `retry.test.ts` pins the default-on jitter clamped to an explicit cap, and the old exact-doubling assertion now runs with `jitter: false`.
161
236
 
@@ -174,7 +249,7 @@
174
249
  ### Internal
175
250
 
176
251
  - **The cookbook gains an escalation-tiering recipe: judge the cheap model's actual work, escalate only on real trouble.** Where `fallback` escalates on a throw, the recipe escalates on mediocrity. It covers the single-request shape (a buffered weak draft, a fail-open judge expressed as `fallback` around the judge so a dead judge serves the draft rather than escalating, and an escalate-or-serve `branch` that emits the verdict into the trajectory), a multi-turn latch that holds a confirmation streak in `loop` carry-state (an escalate verdict increments, a decline resets, a fail-open judge holds, two confirmations latch the run onto the strong tier), and a calibration method for deciding when the weak tier is enough (RESCUE/LOSS/SAFE/HARD quadrants over a strong-tier baseline plus a stratified weak-tier probe, harnessed with `bench` and pinned with `regression_compare`). The multi-provider fallback recipe picks up a `handoff` example.
177
- - **`docs/comparison.md` places NVIDIA's Switchyard.** A wire-level routing proxy is a different layer, not competition: aligned with fascicle on keeping routing policy outside the model surface (its `libsy` library hands every model call back to the caller, the same separation as adapters passed in per run and verbatim model resolution), different on where routing belongs (rewriting traffic for clients you cannot modify versus explicit composition when you own the call site), and usable today as one more OpenAI-compatible gateway behind the compat recipe in `docs/providers.md`.
252
+ - **`docs/comparison.md` places NVIDIA's Switchyard.** A wire-level routing proxy is a different layer, not competition: aligned with Fascicle on keeping routing policy outside the model surface (its `libsy` library hands every model call back to the caller, the same separation as adapters passed in per run and verbatim model resolution), different on where routing belongs (rewriting traffic for clients you cannot modify versus explicit composition when you own the call site), and usable today as one more OpenAI-compatible gateway behind the compat recipe in `docs/providers.md`.
178
253
  - **The check runner (checkride) is upgraded from 0.6.0 to 0.12.1.**
179
254
 
180
255
  ## v0.10.1 — 2026-08-07
@@ -201,7 +276,7 @@
201
276
 
202
277
  ### Internal
203
278
 
204
- - **The Bedrock guardrail docs show how to read the trace the change above made readable.** `docs/providers.md` gains a worked read of `provider_reported.bedrock.trace` beside the existing guardrail recipe, `docs/troubleshooting.md` gains an entry for the symptom that actually gets reported ("the guardrail seems ignored, the output came back unchanged"), and the adapter docstring carries the same claim at the source. The entry separates policy from wiring: a PII action of `NONE` detects without rewriting, so unchanged output is the configured behaviour rather than a dropped `guardrailConfig`, and the way to test the wiring instead is a deliberately invalid `guardrailIdentifier`: AWS rejects the call only if the config reached the Converse command, so a call that succeeds is the failure signal.
279
+ - **The Bedrock guardrail docs show how to read the trace the change above made readable.** `docs/providers.md` gains a worked read of `provider_reported.bedrock.trace` beside the existing guardrail recipe, `docs/troubleshooting.md` gains an entry for the symptom that actually gets reported ("the guardrail seems ignored, the output came back unchanged"), and the adapter docstring carries the same claim at the source. The entry separates policy from wiring: a PII action of `NONE` detects without rewriting, so unchanged output is the configured behaviour rather than a dropped `guardrailConfig`. The way to test the wiring instead is a deliberately invalid `guardrailIdentifier`. AWS rejects the call only if the config reached the Converse command, so a call that succeeds is the failure signal.
205
280
 
206
281
  ## v0.9.11 — 2026-08-05
207
282
 
@@ -237,11 +312,11 @@ work is in the docs surface, the example apps, and the check suite.
237
312
  ### Fixed
238
313
 
239
314
  - **`docs/blueprint.md`'s `state.ts` snippet did not compile.** It declared its scope-state readers over `ReadonlyMap` and called `.get()`, but `use(keys, fn)` hands `fn` a plain object projection of the requested keys. The snippet now shows the real shape, with the `ReadonlyMap` variant documented for readers that go through `ctx.state` inside a step body instead.
240
- - **`examples/pr-improve` could not run on its own default provider.** It defaulted every role to `'sonnet'`/`'opus'` and claimed in comments that the engine expands those per provider. It does not — `model` is passed to the provider verbatim — so the documented default path (`FASCICLE_PROVIDER=anthropic`) sent a literal `"sonnet"` and got a not-found error. There is now one per-provider model table, resolved once and threaded as data, which also removes a second copy of that table and makes the `FASCICLE_MODEL_*` overrides reach the flow; they were previously parsed and discarded.
315
+ - **`examples/pr-improve` could not run on its own default provider.** It defaulted every role to `'sonnet'`/`'opus'` and claimed in comments that the engine expands those per provider. It does not (`model` is passed to the provider verbatim), so the documented default path (`FASCICLE_PROVIDER=anthropic`) sent a literal `"sonnet"` and got a not-found error. One per-provider model table now resolves once and threads through as data, which also removes a second copy of that table and makes the `FASCICLE_MODEL_*` overrides reach the flow; they were previously parsed and discarded.
241
316
 
242
317
  ### Internal
243
318
 
244
- - **The check suite is now [checkride](https://www.npmjs.com/package/checkride) 0.6.0**, replacing the hand-rolled orchestrator. `scripts/check.mjs`, `check-links.mjs`, `check-doc-snippets.mjs`, and `check-publish.mjs` are deleted (~960 lines) in favour of built-in slots; `scripts/check-deps.mjs` stays as the one custom check, since the core/engine dependency invariant is fascicle-specific. The `pnpm check` / `check:all` / `check:json` / `check:bail` contract is unchanged and `pnpm check --changed` is new.
319
+ - **The check suite is now [checkride](https://www.npmjs.com/package/checkride) 0.6.0**, replacing the hand-rolled orchestrator. `scripts/check.mjs`, `check-links.mjs`, `check-doc-snippets.mjs`, and `check-publish.mjs` are deleted (~960 lines) in favour of built-in slots; `scripts/check-deps.mjs` stays as the one custom check, since the core/engine dependency invariant is Fascicle-specific. The `pnpm check` / `check:all` / `check:json` / `check:bail` contract is unchanged and `pnpm check --changed` is new.
245
320
  - **Existing debt is grandfathered in `checkride.baseline.json`** (308 diagnostics across lint, struct, dead, dupes, health, spell). The gate ratchets: frozen debt passes, new findings fail. The `dupes` and `health` slots are now enforced rather than folded into a single fallow invocation that could not fail on them.
246
321
  - The packaging gate gains `publint` and splits the old monolithic `publish` step into `pack`, `smoke`, and `attw` (pinned to the `esm-only` profile). Doc snippets are typechecked against the built `.d.ts` as part of `pnpm check:publish`, rather than as a separate CI step.
247
322
  - **The blueprint is machine-checked on the examples.** All six composition apps carry its ast-grep rules, run for every app by a new `examples` check slot; `check:rules` was previously invoked by no CI job and no slot, and the library's own rules never matched the example apps because their `files:` globs are anchored at the repo root. `vitest` now globs `examples/*/src/**/__tests__`, so `swebench`'s and `amplify`'s suites, which had never executed, run in CI: 13 example tests became 51.
@@ -252,7 +327,7 @@ work is in the docs surface, the example apps, and the check suite.
252
327
 
253
328
  ### Added
254
329
 
255
- - **`define_agent` call-shaping config.** `DefineAgentConfig` accepts `model` and `schema_repair_attempts`, closing the gap where the blueprint's "models are threaded as data" rule could not be followed on the `fascicle/agents` surface (and where schema repair — set on every model call observed in production consumers — required dropping to a stage factory). Precedence: `config.model` > frontmatter `model` > engine default; the blueprint's stage-factory section now states the same rule.
330
+ - **`define_agent` call-shaping config.** `DefineAgentConfig` accepts `model` and `schema_repair_attempts`, closing the gap where the blueprint's "models are threaded as data" rule could not be followed on the `fascicle/agents` surface (and where schema repair, set on every model call observed in production consumers, required dropping to a stage factory). Precedence: `config.model` > frontmatter `model` > engine default; the blueprint's stage-factory section now states the same rule.
256
331
  - Two blueprint reference apps translated from production consumers, workspace-wired with stub-engine tests and the blueprint's ast-grep rules: `examples/change-triage/` (deterministic detectors + one schema-mode model call, a score floor the model cannot undercut, a privacy screen on the model's view) and `examples/docs-concierge/` (grounded Q&A with number-based citations, a `define_agent` stage, and a one-way gate that prefers abstaining over confidently wrong).
257
332
 
258
333
  ### Changed
@@ -264,12 +339,12 @@ work is in the docs surface, the example apps, and the check suite.
264
339
  ### Added
265
340
 
266
341
  - **`fascicle/agents` subpath.** `define_agent` — the markdown-plus-schema agent loader the blueprint recommends for simple one-prompt agents — is now importable by consumers via `import { define_agent } from 'fascicle/agents'`. It was previously reachable only inside the repo. Ships as its own bundle entry (`dist/agents.js`), smoke-verified at build time.
267
- - A dedicated architecture page on the site (`site/blueprint.html`): the agent blueprint's one rule, adoption tiers, module contracts, anti-patterns, and ast-grep enforcement story, linked from both existing pages. `AGENTS.md` and the README now route agents and humans building *on* fascicle to `docs/blueprint.md` first, and a new `examples/README.md` indexes the example apps around it.
342
+ - A dedicated architecture page on the site (`site/blueprint.html`): the agent blueprint's one rule, adoption tiers, module contracts, anti-patterns, and ast-grep enforcement story, linked from both existing pages. `AGENTS.md` and the README now route agents and humans building *on* Fascicle to `docs/blueprint.md` first, and a new `examples/README.md` indexes the example apps around it.
268
343
  - Opt-in `build` + `publish` steps in the check runner, included by `pnpm check:all`: the tsdown bundle with export smoke imports, and the npm pack manifest + `@arethetypeswrong/cli` validation. Packaging regressions now fail the done-gate instead of surfacing at release time.
269
344
 
270
345
  ### Changed
271
346
 
272
- - Documentation synced with the implementation across `docs/` and the site. The composition surface is documented as 21 primitives (adding `ensemble_step`, `improve`, and `learn` to every list and to the site's interactive tour); site code samples now show the real config-object APIs (`branch` / `map` / `ensemble` / `tournament` / `consensus`, `adversarial`'s required `accept`, `suspend`'s required `on`, `retry`'s `backoff_ms`); engine docs corrected for `claude_cli` reasoning-effort forwarding (`CLAUDE_CODE_EFFORT_LEVEL`), the `'timeout'` member of `DEFAULT_RETRY.retry_on`, the real missing-peer error message, `inherit_env` semantics, the full `EngineConfig` shape, and the complete error and Engine-method lists.
347
+ - Documentation synced with the implementation across `docs/` and the site. The composition surface is documented as 21 primitives (adding `ensemble_step`, `improve`, and `learn` to every list and to the site's interactive tour). Site code samples now show the real config-object APIs (`branch` / `map` / `ensemble` / `tournament` / `consensus`, `adversarial`'s required `accept`, `suspend`'s required `on`, `retry`'s `backoff_ms`). Engine docs are corrected for `claude_cli` reasoning-effort forwarding (`CLAUDE_CODE_EFFORT_LEVEL`), the `'timeout'` member of `DEFAULT_RETRY.retry_on`, the real missing-peer error message, `inherit_env` semantics, the full `EngineConfig` shape, and the complete error and Engine-method lists.
273
348
  - The reference agents (reviewer, documenter, researcher) moved from `src/agents/` to `examples/agents/` as copy-pasteable demo code — they were never published (their markdown prompts do not ship in `dist/`), and their own docstring called them canonical examples. Their behavior tests still run in the default suite. `src/agents` now contains exactly the published surface: `define_agent`.
274
349
 
275
350
  ### Internal
@@ -280,8 +355,8 @@ work is in the docs surface, the example apps, and the check suite.
280
355
 
281
356
  ### Added
282
357
 
283
- - `docs/blueprint.md`: a standard app architecture for building on fascicle — one composition layer, three adoption tiers, markdown prompts, normalized module shapes, stub-engine testing, and field-observed anti-patterns distilled from the example apps and production consumers.
284
- - Three ast-grep boundary rules wired into `examples/pr-improve` (runnable via `check:rules`): `create_engine` confined to `engine.ts`, no imperative loops in `flow.ts`, and fascicle value imports confined to the files allowed to know about it.
358
+ - `docs/blueprint.md`: a standard app architecture for building on Fascicle — one composition layer, three adoption tiers, markdown prompts, normalized module shapes, stub-engine testing, and field-observed anti-patterns distilled from the example apps and production consumers.
359
+ - Three ast-grep boundary rules wired into `examples/pr-improve` (runnable via `check:rules`): `create_engine` confined to `engine.ts`, no imperative loops in `flow.ts`, and Fascicle value imports confined to the files allowed to know about it.
285
360
 
286
361
  ## v0.9.5 — 2026-07-12
287
362
 
@@ -335,7 +410,7 @@ work is in the docs surface, the example apps, and the check suite.
335
410
  ### Changed
336
411
 
337
412
  - **Breaking (peer dependencies): AI SDK v7.** The `ai` peer floor is now `^7.0.0` with no v6 compatibility window, and every AI SDK provider peer moves to its v7-line major: `@ai-sdk/anthropic` `^4`, `@ai-sdk/openai` `^4`, `@ai-sdk/google` `^4`, `@ai-sdk/amazon-bedrock` `^5`, `@ai-sdk/openai-compatible` `^3`, `@openrouter/ai-sdk-provider` `^3`, `ai-sdk-ollama` `^4`. Upgrade the whole set together. Fascicle's own API is unchanged: the v7 renames (`system` to `instructions`, `fullStream` to `stream`, `experimental_output` to `output`, `stepCountIs` to `isStepCount`) land at the SDK boundary only, so `generate({ system })` and friends keep their names.
338
- - Usage and cost accounting is verified against v7's nested token-detail shape (`inputTokenDetails`/`outputTokenDetails`, cache-inclusive `inputTokens`, reasoning-inclusive `outputTokens`) with concrete-value tests per provider. On `@ai-sdk/anthropic` v4, cache read and write tokens now fold into `inputTokens` upstream, which makes fascicle's cost subtraction formula exact instead of skewed for cache-heavy Anthropic calls.
413
+ - Usage and cost accounting is verified against v7's nested token-detail shape (`inputTokenDetails`/`outputTokenDetails`, cache-inclusive `inputTokens`, reasoning-inclusive `outputTokens`) with concrete-value tests per provider. On `@ai-sdk/anthropic` v4, cache read and write tokens now fold into `inputTokens` upstream, which makes Fascicle's cost subtraction formula exact instead of skewed for cache-heavy Anthropic calls.
339
414
 
340
415
  ### Fixed
341
416
 
@@ -344,16 +419,16 @@ work is in the docs surface, the example apps, and the check suite.
344
419
 
345
420
  ### Internal
346
421
 
347
- - Releases are now published from CI with npm Trusted Publishing (OIDC) and a signed provenance attestation, gated by a required-reviewer GitHub Environment (`.github/workflows/publish.yaml`). No long-lived npm token exists anywhere; verify a release with `npm audit signatures`. This makes v0.9.0 the first provenance-attested fascicle publish (see `research/provenance-publish-spec.md`).
348
- - Agent-layer boundary ADR: fascicle stays on the single-turn seam (`generateText`/`streamText`) and declines the v7 agent layer (`ToolLoopAgent`, `WorkflowAgent`, `HarnessAgent`, `toolApproval`, `@ai-sdk/otel`), recorded in `research/explorations/2026-07-ai-sdk-agent-layer-boundary.md` and linked from `docs/providers.md`.
349
- - `examples/live_smoke.ts`: a manual release smoke gate that runs one tool-loop flow streamed and non-streamed against OpenRouter and an OpenAI-compatible backend, checking the tool round trip, stream/record text parity, and usage/cost accounting. Live network, so it stays out of the test suite by design.
422
+ - Releases are now published from CI with npm Trusted Publishing (OIDC) and a signed provenance attestation, gated by a required-reviewer GitHub Environment (`.github/workflows/publish.yaml`). No long-lived npm token exists anywhere; verify a release with `npm audit signatures`. This makes v0.9.0 the first provenance-attested Fascicle publish (see `research/provenance-publish-spec.md`).
423
+ - Agent-layer boundary ADR: Fascicle stays on the single-turn seam (`generateText`/`streamText`) and declines the v7 agent layer (`ToolLoopAgent`, `WorkflowAgent`, `HarnessAgent`, `toolApproval`, `@ai-sdk/otel`), recorded in `research/explorations/2026-07-ai-sdk-agent-layer-boundary.md` and linked from `docs/providers.md`.
424
+ - `examples/live-smoke/main.ts`: a manual release smoke gate that runs one tool-loop flow streamed and non-streamed against OpenRouter and an OpenAI-compatible backend, checking the tool round trip, stream/record text parity, and usage/cost accounting. Live network, so it stays out of the test suite by design.
350
425
  - Dev toolchain sweep: vitest 4.1.10, oxlint 1.73, oxlint-tsgolint 0.24, tsdown 0.22.3, zod 4.4.3, `@types/node` 26, fallow 3, and friends.
351
426
 
352
427
  ## v0.8.16 — 2026-07-07
353
428
 
354
429
  ### Added
355
430
 
356
- - `fascicle/ui` subpath for streaming a run into an AI SDK `useChat` UI: `to_ui_message_response`, `pipe_ui_message_stream_to_response`, and `to_ui_message_chunks` translate trajectory `model_chunk` events onto the AI SDK UI message wire. Ships with `docs/human-in-the-loop.md` and `examples/hitl_http.ts` covering suspend/confirm/resume over HTTP.
431
+ - `fascicle/ui` subpath for streaming a run into an AI SDK `useChat` UI: `to_ui_message_response`, `pipe_ui_message_stream_to_response`, and `to_ui_message_chunks` translate trajectory `model_chunk` events onto the AI SDK UI message wire. Ships with `docs/human-in-the-loop.md` and `examples/hitl-http/main.ts` covering suspend/confirm/resume over HTTP.
357
432
 
358
433
  ### Changed
359
434
 
@@ -403,7 +478,7 @@ work is in the docs surface, the example apps, and the check suite.
403
478
 
404
479
  ### Added
405
480
 
406
- - Native constrained decoding for schema-constrained `model_call` on local providers (Ollama and LM Studio), exposed as a new `structured_output` provider capability: the schema now constrains the provider's decode (e.g. Ollama's `format`) instead of prompting for JSON and scraping it, so local-model structured output no longer fails validation on the first call. The prompt-based path remains the fallback, and hosted providers are unchanged.
481
+ - Native constrained decoding for schema-constrained `model_call` on local providers (Ollama and LM Studio), exposed as a new `structured_output` provider capability: the schema now constrains the provider's decode (for example, Ollama's `format`) instead of prompting for JSON and scraping it, so local-model structured output no longer fails validation on the first call. The prompt-based path remains the fallback, and hosted providers are unchanged.
407
482
  - Live GitHub star count on the marketing site's nav button.
408
483
 
409
484
  ### Internal
@@ -517,7 +592,7 @@ work is in the docs surface, the example apps, and the check suite.
517
592
 
518
593
  ### Changed
519
594
 
520
- - **Breaking: model resolution is now a verbatim pass-through.** `model` is an opaque string sent to the provider unchanged; `provider` selects the transport. There is one canonical input shape — separate `provider` + `model` params — and no interpretation in between.
595
+ - **Breaking: model resolution is now a verbatim pass-through.** `model` is an opaque string sent to the provider unchanged; `provider` selects the transport. One canonical input shape remains — separate `provider` + `model` params — with no interpretation in between.
521
596
  - Removed the `provider:model` colon shorthand. Pass `{ provider: 'openrouter', model: 'anthropic/claude-sonnet-4.5' }` instead of `model: 'openrouter:anthropic/claude-sonnet-4.5'`. Model ids that contain colons (Ollama tags like `qwen3-coder:30b`, Bedrock `...-v1:0`) now ride through untouched.
522
597
  - Removed the built-in `MODEL_FAMILIES` catalog and the `families` engine-config field. Family tokens (`opus`, `sonnet`, `gpt`, `gemini`) no longer expand — pass the provider's concrete id. (The `claude_cli` transport still resolves `opus`/`sonnet`/`haiku` itself, via the CLI.)
523
598
  - Removed the user alias table: `Engine.register_alias` / `unregister_alias` / `resolve_alias` / `list_aliases` and `EngineConfig.aliases`. Keep your own name→id map in your harness if you want shortcuts.
@@ -566,17 +641,17 @@ work is in the docs surface, the example apps, and the check suite.
566
641
  - `examples/swebench`: `claude_cli` provider option, selectable via `SWEBENCH_PROVIDER`.
567
642
 
568
643
  ### Changed
569
- - **Breaking.** `create_engine` no longer ships default aliases — the alias table starts empty and is reserved for your own named pins. The built-in `cli-*`, `or:*`, `gemini-pro`/`gemini-flash`, and `gpt-4o*` aliases are gone; use `{ model, provider }` pairs (e.g. `{ model: 'sonnet', provider: 'claude_cli' }`) or the colon form (`openrouter:meta-llama/llama-3.3-70b-instruct`).
644
+ - **Breaking.** `create_engine` no longer ships default aliases — the alias table starts empty and is reserved for your own named pins. The built-in `cli-*`, `or:*`, `gemini-pro`/`gemini-flash`, and `gpt-4o*` aliases are gone; use `{ model, provider }` pairs (for example, `{ model: 'sonnet', provider: 'claude_cli' }`) or the colon form (`openrouter:meta-llama/llama-3.3-70b-instruct`).
570
645
  - **Breaking.** `resolve_model` signature is now `resolve_model(model, provider, { families, aliases })`. Resolution order: colon-form `provider:id` → user alias → family lookup → pass-through specific id. When `model`/`provider` are omitted, `model` defaults to `sonnet` and `provider` resolves to per-call → `defaults.provider` → the sole configured provider → `anthropic`.
571
646
 
572
647
  ### Fixed
573
- - A family with no entry for the chosen provider (e.g. `opus` on `openai`) now throws the descriptive `model_family_unavailable_error` instead of the generic not-found path.
648
+ - A family with no entry for the chosen provider (for example, `opus` on `openai`) now throws the descriptive `model_family_unavailable_error` instead of the generic not-found path.
574
649
 
575
650
  ## v0.4.3 — 2026-05-10
576
651
 
577
652
  ### Added
578
653
  - `examples/swebench` — 5-instance smoke harness against SWE-bench Verified. Ships a `Sandbox` seam (`noop` / `local` / `docker` factories), five per-case tools (`read_file`, `write_file`, `run_command` argv-only, `list_files`, `grep_files`), a `solve_instance` flow that captures `git diff` against `base_commit`, and `evaluate_with_sb_cli` for the real eval. Scaling to the 500-instance Verified set is a scale change, not a shape change.
579
- - `examples/pr-improve` Phase C, PR B: builder dispatches by provider. `make_builder_call` now takes `worktree_root` and `provider` explicit params; under `claude_cli` it keeps the schema-only path that delegates to the CLI's built-in Read/Write/Edit, and under API providers (`anthropic`, `openrouter`) it returns a `model_call` configured with the worktree-scoped tools from `make_builder_tools(worktree_root)`. The `Step<string, GenerateResult<Handoff>>` contract is unchanged; `flow.ts` ripples in one place via a new `FlowEnv = { worktree_root, provider }` arg to `build_flow`. The portability proof — same end-to-end result under `--provider claude_cli` and `--provider anthropic` — is now live.
654
+ - `examples/pr-improve` Phase C, PR B: builder dispatches by provider. `make_builder_call` now takes `worktree_root` and `provider` explicit params; under `claude_cli` it keeps the schema-only path that delegates to the CLI's built-in Read/Write/Edit, and under API providers (`anthropic`, `openrouter`) it returns a `model_call` configured with the worktree-scoped tools from `make_builder_tools(worktree_root)`. The `Step<string, GenerateResult<Handoff>>` contract is unchanged; `flow.ts` ripples in one place via a new `FlowEnv = { worktree_root, provider }` arg to `build_flow`. The portability proof (same end-to-end result under `--provider claude_cli` and `--provider anthropic`) is now live.
580
655
 
581
656
  ### Internal
582
657
  - `examples/pr-improve`: split `CLOUD_SPEC.md` out as the active spec for the remaining AWS/Fargate/Terraform deployment work (Fargate worker, webhook Lambda, single Terraform module). `SPEC.md` keeps a deprecation banner and is preserved as historical context.
@@ -605,16 +680,16 @@ work is in the docs surface, the example apps, and the check suite.
605
680
  ## v0.4.1 — 2026-05-09
606
681
 
607
682
  ### Added
608
- - `examples/pr-improve`: an automated PR-improvement pipeline composed as a four-stage fascicle flow — reviewer (sonnet) → pragmatist (opus, default-reject) → builder (sonnet) → build-reviewer (opus) — inside a bounded `loop` with `guard`-driven convergence. Routes every model call through the engine, so the same flow runs against `anthropic`, `openrouter`, or a local `claude_cli` subprocess by changing one env var. Includes `--pr` mode for posting review suggestions back to a GitHub PR via safe-spawn `gh`/`git` wrappers, and a `bin/pr-improve` entrypoint.
683
+ - `examples/pr-improve`: an automated PR-improvement pipeline composed as a four-stage Fascicle flow — reviewer (sonnet) → pragmatist (opus, default-reject) → builder (sonnet) → build-reviewer (opus) — inside a bounded `loop` with `guard`-driven convergence. Routes every model call through the engine, so the same flow runs against `anthropic`, `openrouter`, or a local `claude_cli` subprocess by changing one env var. Includes `--pr` mode for posting review suggestions back to a GitHub PR via safe-spawn `gh`/`git` wrappers, and a `bin/pr-improve` entrypoint.
609
684
 
610
685
  ### Fixed
611
686
  - `@repo/engine` schema validation: `schema.ts` now tolerates fenced JSON code blocks in model output and emits a new `schema_validation_failed` trajectory event when validation fails, instead of throwing without observability. `generate.ts` extracts multiple JSON candidates from a single response and picks the first that parses, recovering from leading prose or partial fences.
612
- - `@repo/engine` `claude_cli` provider: schema-repair attempt count is now configurable (was: hard-coded), giving callers control over the retry-vs-fail-fast tradeoff.
687
+ - `@repo/engine` `claude_cli` provider: schema-repair attempt count is now configurable (was hard-coded), giving callers control over the retry-vs-fail-fast tradeoff.
613
688
 
614
689
  ## v0.4.0 — 2026-05-07
615
690
 
616
691
  ### Fixed
617
- - `claude_cli` adapter: `build_env` now seeds the standard process-env keys (`PATH`, `HOME`, `SHELL`, `USER`, `LOGNAME`, `LANG`, `TMPDIR`) under every `auth_mode` (was: only inherited under `oauth`). Sandbox-enabled runs under `auto`/`api_key` previously spawned with an empty `PATH` and failed with `ENOENT` looking up `greywall`/`bwrap`. Set `inherit_env: false` to opt out of the standard-key seeding.
692
+ - `claude_cli` adapter: `build_env` now seeds the standard process-env keys (`PATH`, `HOME`, `SHELL`, `USER`, `LOGNAME`, `LANG`, `TMPDIR`) under every `auth_mode` (was only inherited under `oauth`). Sandbox-enabled runs under `auto`/`api_key` previously spawned with an empty `PATH` and failed with `ENOENT` looking up `greywall`/`bwrap`. Set `inherit_env: false` to opt out of the standard-key seeding.
618
693
  - `claude_cli` adapter: greywall sandbox plan now writes a temp settings JSON (`{ network: { allowHosts }, filesystem: { allowWrite } }`) and forwards `--settings <path>` instead of the removed `--allow-host`/`--rw` flags. greywall 0.3.0+ rejected the old flags as unknown and exited 1. Consumers managing their own settings file can pass `sandbox.settings_path` to skip the temp-file generation.
619
694
  - `fascicle-viewer` CLI: replaced the fragile `argv[1].endsWith('/cli.ts'|'/cli.js')` self-execution guard with an `import.meta.url`-based check. The umbrella bundles `cli.ts` into `dist/index.js`, so any consumer whose entry script was named `cli.js` was accidentally hijacked into running the viewer at import time.
620
695
 
@@ -644,8 +719,8 @@ work is in the docs surface, the example apps, and the check suite.
644
719
  - `bench` primitive in `@repo/composites`: online counterpart to `learn`. `bench(flow, cases, judges, options?)` runs a flow against a fixture set, scores each output via judges, and returns a structured `BenchReport` with per-case results and summary (pass_rate, mean_scores per judge, total/mean cost). Per-case observability via `trajectory_dir` (one JSONL per case) and `live_url` (push to a viewer); both can be combined. Cost is tracked in-process by intercepting `cost` events on the trajectory pipeline.
645
720
  - `judge_equals`, `judge_with`, `judge_llm` in `@repo/composites`: stock judges over `{ input, output, meta }`. `judge_llm` takes a `Step<string, string>` model so composites stays engine-free; users wire their own `model_call({...})` into the judge.
646
721
  - `regression_compare`, `read_baseline`, `write_baseline`: diff two `BenchReport`s against `pass_rate`, per-judge means, and a relative cost threshold (default 10%). Doesn't short-circuit; full delta + per-case report.
647
- - `tee_logger` adapter in `@repo/observability`: fan one `TrajectoryLogger` contract out to N sinks. First sink's `start_span` id is canonical; per-sink ids are translated back on `end_span`; sinks that throw don't derail the others.
648
- - `examples/bench_reviewer.ts` + `bench/reviewer/{cases.json,baseline.json}`: end-to-end driver against `@repo/agents`'s `reviewer`. `WRITE_BASELINE=1` records, subsequent runs compare and exit 1 on regression.
722
+ - `tee_logger` adapter in `@repo/observability`: fan one `TrajectoryLogger` contract out to N sinks. First sink's `start_span` id is canonical, and per-sink ids are translated back on `end_span`. Sinks that throw don't derail the others.
723
+ - `examples/bench-reviewer/main.ts` + `bench/reviewer/{cases.json,baseline.json}`: end-to-end driver against `@repo/agents`'s `reviewer`. `WRITE_BASELINE=1` records, subsequent runs compare and exit 1 on regression.
649
724
  - Cost rendering in the viewer: per-span cost badges that roll up the tree, plus a header running total (`<n> events · <m> errors · $<total>`). Run filter narrows the total. Cost attribution uses an open-span stack per `run_id`; format is 4 decimals under $0.01, 2 decimals otherwise.
650
725
  - `examples/amplify` opt-in viewer push via `AMPLIFY_VIEWER_URL`: tees the on-disk trajectory with `http_logger` when set; standalone runs without the env var keep the existing single-sink behaviour.
651
726
 
@@ -661,7 +736,7 @@ work is in the docs surface, the example apps, and the check suite.
661
736
  ## v0.3.5 — 2026-04-30
662
737
 
663
738
  ### Added
664
- - `@repo/viewer` package and `fascicle-viewer` CLI: minimal in-repo dev dashboard for visualizing a fascicle run as it executes. Single static HTML page (vanilla JS, no build step), an SSE-fed span tree with active/error/emit highlighting, and a click-to-expand event log. Two transports feed one in-process broadcaster: file-tail (`fascicle-viewer .trajectory.jsonl`) for the primary case and HTTP push (`fascicle-viewer --listen` plus the new `http_logger`) for low-latency or remote attach. Localhost-only by default. Programmatic embed via `start_viewer({...})`. See `packages/viewer/README.md`.
739
+ - `@repo/viewer` package and `fascicle-viewer` CLI: minimal in-repo dev dashboard for visualizing a Fascicle run as it executes. Single static HTML page (vanilla JS, no build step), an SSE-fed span tree with active/error/emit highlighting, and a click-to-expand event log. Two transports feed one in-process broadcaster: file-tail (`fascicle-viewer .trajectory.jsonl`) for the primary case and HTTP push (`fascicle-viewer --listen` plus the new `http_logger`) for low-latency or remote attach. Localhost-only by default. Programmatic embed via `start_viewer({...})`. See `packages/viewer/README.md`.
665
740
  - `http_logger` adapter in `@repo/observability`: a `TrajectoryLogger` that POSTs each event as one line of NDJSON to a configured URL. Drops on transport error, never blocks the user flow. Wire format mirrors `filesystem_logger` byte-for-byte and parses back via `trajectory_event_schema`.
666
741
 
667
742
  ### Internal
@@ -678,7 +753,7 @@ work is in the docs surface, the example apps, and the check suite.
678
753
  ## v0.3.3 — 2026-04-29
679
754
 
680
755
  ### Added
681
- - `improve` composite in `@repo/composites`: bounded online self-improvement loop with parallel proposers, structured lessons accumulator, plateau detection, and configurable wall-clock + round budgets. Online counterpart to `learn`. Example at `examples/improve.ts`.
756
+ - `improve` composite in `@repo/composites`: bounded online self-improvement loop with parallel proposers, structured lessons accumulator, plateau detection, and configurable wall-clock + round budgets. Online counterpart to `learn`. Example at `examples/improve/main.ts`.
682
757
  - `ensemble_step` composite: Step-based sibling of `ensemble` for cases where scoring is itself a `Step`. Returns `winner_id`, `winner`, structured `winner_scored`, and the full `scored` map.
683
758
 
684
759
  ## v0.3.2 — 2026-04-29
@@ -693,7 +768,7 @@ work is in the docs surface, the example apps, and the check suite.
693
768
  ## v0.3.1 — 2026-04-29
694
769
 
695
770
  ### Internal
696
- - Colocated unit tests under `__tests__/` subfolders (e.g. `packages/core/src/branch.ts` ↔ `packages/core/src/__tests__/branch.test.ts`); cross-cutting tests under `packages/<name>/test/` are unchanged.
771
+ - Colocated unit tests under `__tests__/` subfolders (for example, `packages/core/src/branch.ts` ↔ `packages/core/src/__tests__/branch.test.ts`); cross-cutting tests under `packages/<name>/test/` are unchanged.
697
772
 
698
773
  ## v0.3.0 — 2026-04-29
699
774
 
@@ -704,7 +779,7 @@ work is in the docs surface, the example apps, and the check suite.
704
779
  - `amplify` self-improvement loop example with a demo helper providing chart, measure, and reset utilities.
705
780
  - `learn` example with smoke test.
706
781
  - `EffortLevel` extended with `xhigh` and `max`, and reasoning support added to the `claude_cli` adapter.
707
- - `spec/plans/ideas.md` capturing possible directions to build on fascicle.
782
+ - `spec/plans/ideas.md` capturing possible directions to build on Fascicle.
708
783
 
709
784
  ### Changed
710
785
 
package/README.md CHANGED
@@ -12,9 +12,9 @@ No framework lifecycle. No ambient state. No decorators. Adapters are passed in
12
12
  pnpm add fascicle
13
13
  ```
14
14
 
15
- fascicle is ESM-only and requires Node >= 24. `ai`, `zod`, and every provider SDK are optional peers — install only the ones you use. `pnpm add fascicle` alone builds and runs a flow against `transport: 'native'` or `claude_cli`, with no AI SDK package and no schema library installed at all; schemas accept any [Standard Schema](https://standardschema.dev) — zod, ArkType, Valibot, whichever you already use. See [docs/providers.md](./docs/providers.md).
15
+ Fascicle is ESM-only and requires Node >= 24. `ai`, `zod`, and every provider SDK are optional peers — install only the ones you use. `pnpm add fascicle` alone builds and runs a flow against `transport: 'native'` or `claude_cli`, with no AI SDK package and no schema library installed at all; schemas accept any [Standard Schema](https://standardschema.dev) — zod, ArkType, Valibot, whichever you already use. See [docs/providers.md](./docs/providers.md).
16
16
 
17
- No API key on hand? Several runnable examples need zero keys: [examples/hello.ts](./examples/hello.ts), [examples/suspend_resume.ts](./examples/suspend_resume.ts), and [examples/viewer_demo.ts](./examples/viewer_demo.ts) use no engine at all, and [examples/newsroom.ts](./examples/newsroom.ts) runs the full vocabulary against the bundled stub engine from `fascicle/testing`.
17
+ No API key on hand? Several runnable examples need zero keys: [examples/hello/main.ts](./examples/hello/main.ts), [examples/suspend-resume/main.ts](./examples/suspend-resume/main.ts), and [examples/viewer-demo/main.ts](./examples/viewer-demo/main.ts) use no engine at all, and [examples/newsroom/main.ts](./examples/newsroom/main.ts) runs the full vocabulary against the bundled stub engine from `fascicle/testing`.
18
18
 
19
19
  ## A 60-second tour
20
20
 
@@ -80,7 +80,7 @@ Plus `run`, `run.stream`, and `describe`. And inside any step body, `ctx.call(st
80
80
 
81
81
  **AI engine.** `create_engine(config)` returns one `generate` surface across eight providers. Two axes: `model` is an opaque id sent to the provider verbatim (`claude-opus-4-8`, `gpt-4o`, `us.anthropic.claude-sonnet-4-20250514-v1:0`), and `provider` names the transport (`anthropic`, `bedrock`, `openrouter`, `claude_cli`, …) — swap `provider` to move a call between transports. Reasoning effort (`'none'` through `'max'`) is translated per provider. Cost estimation uses a pricing table with per-engine overrides.
82
82
 
83
- The engine core is SDK-agnostic: providers plug in behind a neutral single-turn seam, as one of three kinds. Most built-ins wrap Vercel's AI SDK (`ai_sdk`); five providers can instead run `transport: 'native'` (raw HTTP, no AI SDK in the path, no peer to install) — `anthropic` on the Messages API, `openai`/`openrouter`/`lmstudio` on a shared OpenAI Chat Completions core, and `ollama` on its own `/api/chat` endpoint; and `claude_cli` delegates to an external agent. All inherit the same tool loop, retry, cost, and trajectory, and `custom_providers` registers your own adapter of any kind without touching fascicle. See [docs/providers.md](./docs/providers.md).
83
+ The engine core is SDK-agnostic: providers plug in behind a neutral single-turn seam, as one of three kinds. Most built-ins wrap Vercel's AI SDK (`ai_sdk`). Five providers can instead run `transport: 'native'` (raw HTTP, no AI SDK in the path, no peer to install) — `anthropic` on the Messages API, `openai`/`openrouter`/`lmstudio` on a shared OpenAI Chat Completions core, and `ollama` on its own `/api/chat` endpoint. The third kind is `claude_cli`, which delegates to an external agent. All inherit the same tool loop, retry, cost, and trajectory, and `custom_providers` registers your own adapter of any kind without touching Fascicle. See [docs/providers.md](./docs/providers.md).
84
84
 
85
85
  **Adapters injected per run.** Trajectory loggers and checkpoint stores ship under the `fascicle/adapters` subpath:
86
86
 
@@ -93,7 +93,7 @@ await run(flow, input, {
93
93
  });
94
94
  ```
95
95
 
96
- `filesystem_logger` writes synchronously (each event blocks the event loop briefly), which is fine for dev tools and short-lived runs; see [docs/concepts.md](./docs/concepts.md#adapter-limits) before wiring it into a long-running server. Span parentage is threaded through the runner, so span trees stay correct under `parallel`/`map` concurrency. The `TrajectoryLogger` and `CheckpointStore` contracts (exported from `fascicle`) are tiny — roll your own to push events to Honeycomb, S3, etc.
96
+ `filesystem_logger` writes synchronously (each event blocks the event loop briefly), which is fine for dev tools and short-lived runs; see [docs/concepts.md](./docs/concepts.md#adapter-limits) before wiring it into a long-running server. Span parentage is threaded through the runner, so span trees stay correct under `parallel`/`map` concurrency. The `TrajectoryLogger` and `CheckpointStore` contracts (exported from `fascicle`) are tiny — roll your own to push events to Honeycomb, S3, and so on.
97
97
 
98
98
  `run.stream(flow, input)` returns `{ events, result }` for incremental observation, and `run.until_suspended(flow, input)` drives human-in-the-loop flows: a `suspend` gate resolves to a typed outcome with a `resume` closure instead of throwing.
99
99
 
@@ -107,7 +107,7 @@ const engine = make_stub_engine([
107
107
  ]);
108
108
  ```
109
109
 
110
- **Markdown-defined agents.** When an agent is just a prompt plus an output schema, `define_agent` (the `fascicle/agents` subpath) folds a markdown file — frontmatter `name` / `model` / `temperature`, body as the prompt — and a zod schema into a `Step<i, o>`:
110
+ **Markdown-defined agents.** When an agent is just a prompt plus an output schema, `define_agent` (the `fascicle/agents` subpath) folds a markdown file (frontmatter `name` / `model` / `temperature`, with the body as the prompt) and a zod schema into a `Step<i, o>`:
111
111
 
112
112
  <!-- snippet: check -->
113
113
  ```typescript
@@ -192,9 +192,9 @@ await handle.close();
192
192
 
193
193
  For zero-latency streaming from inside a long-running flow, pair it with `http_logger` from `fascicle/adapters`. See [docs/viewer.md](./docs/viewer.md) for the full transport story.
194
194
 
195
- ## Building an app on fascicle
195
+ ## Building an app on Fascicle
196
196
 
197
- **[docs/blueprint.md](./docs/blueprint.md) is the recommended architecture for apps built on fascicle** — distilled from the reference apps and production consumers. One composition layer (`flow.ts`) that holds the whole topology, `create_engine` confined to one file, prompts as markdown with frontmatter, zod schemas as the stage contracts, stub-engine testing, and [ast-grep rules](./examples/pr-improve/rules/) that turn each boundary into a build failure. If you are a coding agent scaffolding a new fascicle app, follow the blueprint and its checklist.
197
+ **[docs/blueprint.md](./docs/blueprint.md) is the recommended architecture for apps built on Fascicle** — distilled from the reference apps and production consumers. One composition layer (`flow.ts`) that holds the whole topology, `create_engine` confined to one file, prompts as markdown with frontmatter, zod schemas as the stage contracts, stub-engine testing, and [ast-grep rules](./examples/pr-improve/rules/) that turn each boundary into a build failure. If you are a coding agent scaffolding a new Fascicle app, follow the blueprint and its checklist.
198
198
 
199
199
  The canonical worked example is [examples/pr-improve/](./examples/pr-improve/), with its design rationale in [examples/pr-improve/docs/architecture.md](./examples/pr-improve/docs/architecture.md).
200
200
 
@@ -204,7 +204,7 @@ The canonical worked example is [examples/pr-improve/](./examples/pr-improve/),
204
204
  - [docs/getting-started.md](./docs/getting-started.md) — install and run your first flow
205
205
  - [docs/concepts.md](./docs/concepts.md) — step-as-value, trajectories, cancellation
206
206
  - [docs/composition.md](./docs/composition.md) — full composition surface: the 22 primitives, run/stream, checkpointing
207
- - [docs/leaf-arm-spine.md](./docs/leaf-arm-spine.md) — the three-layer shape of a fascicle flow and how to choose the right primitive at each layer
207
+ - [docs/leaf-arm-spine.md](./docs/leaf-arm-spine.md) — the three-layer shape of a Fascicle flow and how to choose the right primitive at each layer
208
208
  - [docs/advanced-composition.md](./docs/advanced-composition.md) — the primitives to reach for last (`scope`/`stash`/`use`, `ensemble`, `tournament`, `improve`/`learn`) and when they earn their keep
209
209
  - [docs/api-reference.md](./docs/api-reference.md) — the public surface at a glance
210
210
  - [docs/configuration.md](./docs/configuration.md) — engine config, defaults, pricing, retries
@@ -215,14 +215,15 @@ The canonical worked example is [examples/pr-improve/](./examples/pr-improve/),
215
215
  - [docs/testing.md](./docs/testing.md) — testing flows with stub, script, and capture engines
216
216
  - [docs/regression-testing-model-behavior.md](./docs/regression-testing-model-behavior.md) — regression-testing model behavior with mutation-tested judges and a committed score baseline
217
217
  - [docs/human-in-the-loop.md](./docs/human-in-the-loop.md) — suspend/resume approval over HTTP and streaming to a `useChat` UI via `fascicle/ui`
218
- - [docs/writing-a-harness.md](./docs/writing-a-harness.md) — building a runner around fascicle
219
- - [docs/embedding-under-a-harness.md](./docs/embedding-under-a-harness.md) — running a fascicle agent as somebody's child process
218
+ - [docs/writing-a-harness.md](./docs/writing-a-harness.md) — building a runner around Fascicle
219
+ - [docs/embedding-under-a-harness.md](./docs/embedding-under-a-harness.md) — running a Fascicle agent as somebody's child process
220
220
  - [docs/troubleshooting.md](./docs/troubleshooting.md) — first-run errors and what they mean
221
- - [docs/comparison.md](./docs/comparison.md) — how fascicle compares to LangChain, Mastra, and others
222
- - [docs/adoption-decision.md](./docs/adoption-decision.md) weighs whether to adopt fascicle: the honest case, the risks, and when to reach for something else
223
- - [docs/roadmap.md](./docs/roadmap.md) — what has shipped, what is being considered, and what fascicle deliberately will not do
224
- - [examples/](./examples/) — runnable reference flows; start with [examples/newsroom.ts](./examples/newsroom.ts), the vocabulary tour
221
+ - [docs/comparison.md](./docs/comparison.md) — how Fascicle compares to LangChain, Mastra, and others
222
+ - [docs/adoption-decision.md](./docs/adoption-decision.md) weighs whether to adopt Fascicle: the honest case, the risks, and when to reach for something else
223
+ - [docs/roadmap.md](./docs/roadmap.md) — what has shipped, what is being considered, and what Fascicle deliberately will not do
224
+ - [examples/](./examples/) — runnable reference flows; start with [examples/newsroom/main.ts](./examples/newsroom/main.ts), the vocabulary tour
225
225
  - [docs/viewer.md](./docs/viewer.md) — viewer details and transport options
226
+ - [docs/grafana.md](./docs/grafana.md) — shipping a run's traces and metrics to a Grafana dashboard over OpenTelemetry
226
227
 
227
228
  ## Contributing
228
229
 
@@ -230,7 +231,7 @@ Fascicle is early and not accepting outside pull requests yet. Bug reports and f
230
231
 
231
232
  ## Development
232
233
 
233
- This repo is a **single package**. The code is organized as deep modules under `src/` (`core`, `engine`, `composites`, `agents`, `adapters`, `mcp`, `stdio`, `ui`, `otel`, `policy`, `schema`, `testing`, `viewer`), each reachable only through its barrel via the `#<module>` import alias. The umbrella surface at the `src/` root is what publishes to npm as `fascicle`. Architectural boundaries (e.g. core cannot import adapters; engine imports core type-only; no `process.env` outside the audited exceptions) are enforced by the ast-grep rules in `rules/` and a directory-level boundary DAG in `fallow.toml`. The 7 apps under `examples/*/` are separate workspace members that consume the library via `fascicle: workspace:*`.
234
+ This repo is a **single package**. The code is organized as deep modules under `src/` (`core`, `engine`, `composites`, `agents`, `adapters`, `mcp`, `stdio`, `ui`, `otel`, `policy`, `schema`, `testing`, `viewer`), each reachable only through its barrel via the `#<module>` import alias. The umbrella surface at the `src/` root is what publishes to npm as `fascicle`. Architectural boundaries (for example, core cannot import adapters, engine imports core type-only, and no `process.env` outside the audited exceptions) are enforced by the ast-grep rules in `rules/` and a directory-level boundary DAG in `fallow.toml`. The 7 apps under `examples/*/` are separate workspace members that consume the library via `fascicle: workspace:*`.
234
235
 
235
236
  ```bash
236
237
  pnpm install