fascicle 0.12.0 → 0.12.3

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 (49) hide show
  1. package/CHANGELOG.md +148 -32
  2. package/README.md +25 -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 +22 -3
  8. package/dist/agents.js +74 -24
  9. package/dist/agents.js.map +1 -1
  10. package/dist/bin/fascicle-viewer.js +2 -2
  11. package/dist/{core-BkB2l1-e.js → core-DdJEhyQc.js} +314 -501
  12. package/dist/core-DdJEhyQc.js.map +1 -0
  13. package/dist/engine-J4lIxpw5.js +7000 -0
  14. package/dist/engine-J4lIxpw5.js.map +1 -0
  15. package/dist/index.d.ts +237 -178
  16. package/dist/index.js +617 -7771
  17. package/dist/index.js.map +1 -1
  18. package/dist/{invoke-JkzNf7-Y.js → invoke-CH_eJZeS.js} +8 -8
  19. package/dist/{invoke-JkzNf7-Y.js.map → invoke-CH_eJZeS.js.map} +1 -1
  20. package/dist/{leading_system-BVtGMweY.js → leading_system-BUCT-PwD.js} +31 -8
  21. package/dist/leading_system-BUCT-PwD.js.map +1 -0
  22. package/dist/mcp.d.ts +5 -5
  23. package/dist/mcp.js +10 -9
  24. package/dist/mcp.js.map +1 -1
  25. package/dist/otel.d.ts +1 -1
  26. package/dist/otel.js +4 -4
  27. package/dist/otel.js.map +1 -1
  28. package/dist/static/viewer.html +2 -1
  29. package/dist/stdio.d.ts +2 -2
  30. package/dist/stdio.js +2 -2
  31. package/dist/testing.d.ts +66 -15
  32. package/dist/testing.js +200 -34
  33. package/dist/testing.js.map +1 -1
  34. package/dist/trajectory-ByoOQZ6T.d.ts +114 -0
  35. package/dist/trajectory-D1eq9eue.js +81 -0
  36. package/dist/trajectory-D1eq9eue.js.map +1 -0
  37. package/dist/{types-BCtKsxrX.d.ts → types-BK0UW28o.d.ts} +3 -3
  38. package/dist/{types-CVdTBXE_.d.ts → types-DBpU27sQ.d.ts} +20 -3
  39. package/dist/{types-4l54cexm.d.ts → types-DU6cvoA4.d.ts} +9 -5
  40. package/dist/ui.d.ts +2 -2
  41. package/dist/ui.js +1 -1
  42. package/dist/ui.js.map +1 -1
  43. package/dist/viewer.d.ts +117 -0
  44. package/dist/viewer.js +659 -0
  45. package/dist/viewer.js.map +1 -0
  46. package/package.json +26 -12
  47. package/dist/adapters-hmnJOOgf.js.map +0 -1
  48. package/dist/core-BkB2l1-e.js.map +0 -1
  49. package/dist/leading_system-BVtGMweY.js.map +0 -1
package/CHANGELOG.md CHANGED
@@ -1,5 +1,121 @@
1
1
  # Changelog
2
2
 
3
+ ## v0.12.3 — 2026-08-19
4
+
5
+ ### Changed
6
+
7
+ - **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.
8
+
9
+ - **`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.
10
+
11
+ - **`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.
12
+
13
+ - **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.
14
+
15
+ - **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.
16
+
17
+ - **`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.
18
+
19
+ - **`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.
20
+
21
+ ### Added
22
+
23
+ - **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.
24
+
25
+ - **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.
26
+
27
+ - **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.
28
+
29
+ - **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.
30
+
31
+ - **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.
32
+
33
+ ### Fixed
34
+
35
+ - **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.
36
+
37
+ - **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.
38
+
39
+ - **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.
40
+
41
+ ### Internal
42
+
43
+ - **`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.
44
+
45
+ - **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.
46
+
47
+ - **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.
48
+
49
+ ## v0.12.1 — 2026-08-18
50
+
51
+ ### Added
52
+
53
+ - **The `gate` composite: paid work survives an approval pause.** `gate(inner, { id, store?, format?, name? })` runs `inner`, checkpoints its result under `gate:<id>`, then suspends with that result as the payload, so the approver sees what they are approving. Resuming passes the inner result through unchanged, and a fresh run after a process restart with the same store replays from the checkpoint instead of paying for the model call again. Built from public primitives only, so it renders as one composite node in `describe`; reach for raw `checkpoint` plus `suspend` when the decision must shape the output.
54
+
55
+ - **`chain` states its input type once.** `chain('question').input<Request>()` replaces `chain<Request, 'question'>('question')`; the refinement is available only on a freshly opened chain, before the first binding.
56
+
57
+ - **Arm-first chain bindings.** `.step(name, arm, select)` takes a composed `Step` and a selector from the record to the arm's input: the chain dispatches the arm and records it as the binding's describe child in one statement, so the run tree and the described tree cannot drift apart. The `fn` plus `{ arm }` form remains for bodies that invoke an arm conditionally, in a loop, or more than once.
58
+
59
+ - **Scripted and sequenced test doubles.** `make_script_engine(responses, options?)` plays a strict call-order queue whose entries are plain content values or `{ content?, tool_calls?, finish_reason?, usage?, throw? }`, so a converging loop, a tool-call path, or a provider error can be scripted without hand-rolling an engine; a `make_stub_engine` response's `content` may now be a function of the call and its per-route index. `text_of(opts)` reads the user-visible prompt out of a captured `GenerateOptions` whatever its shape, and `engine_from_generate(generate)`, the shell both factories are built on, is now exported for custom doubles. `docs/testing.md` is the new guide.
60
+
61
+ - **Caller-shaped generation knobs everywhere they were missing.** `temperature`, `max_tokens`, `top_p`, `turn_timeout_ms`, and `prepare_step` ride on `ModelCallConfig` (and so on `model_step`); the three sampling knobs also work as `EngineDefaults`, with the per-call value winning. `define_agent` accepts `provider`, `effort`, `temperature`, `max_tokens`, and `top_p` through both markdown frontmatter and code config, code winning over frontmatter and frontmatter over the engine default. Previously the only route to a temperature was frontmatter or dropping to `engine.generate` inside a step body.
62
+
63
+ - **Terminal and checkpoint trajectory events.** Every run now ends with `run_end` carrying `status: 'done' | 'failed' | 'aborted' | 'suspended'`, so a consumer no longer infers a failed run from silence, and a failing span records `error_name`, `error_kind`, and `error_path` alongside the message. Checkpoint lookups emit `checkpoint` with `status: 'hit' | 'miss' | 'read_error'`; a store that throws still degrades to a miss, but visibly. Guards: `is_run_end_event`, `is_checkpoint_event`.
64
+
65
+ - **`run.until_suspended` outcomes carry their `payload`.** A driver loop can render what is awaiting approval without threading a side channel out of the `on` callback.
66
+
67
+ - **A bare predicate as a `loop` guard.** `guard: (state) => boolean`, or a promise of one, no longer needs wrapping in a step that returns `{ stop, state }`.
68
+
69
+ - **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]`.
70
+
71
+ - **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.
72
+
73
+ - **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.
74
+
75
+ ### Changed
76
+
77
+ - **Provider resolution no longer falls back to `anthropic`.** With several providers configured and neither a per-call `provider` nor `defaults.provider`, `generate` throws the new `provider_required_error` naming what is configured, instead of quietly sending the call to Anthropic. Per-call choice, engine default, and sole-provider inference are unchanged. **Breaking**, and deliberately so for a provider-agnostic library: a multi-provider engine that leaned on the implicit default now has to say which one it meant.
78
+
79
+ - **A misspelled provider name is reported at construction.** A provider key matching no built-in and no custom adapter throws `engine_config_error` with `unknown provider '<name>'; built-in providers are: ...`, rather than claiming it is not configured on the engine that just declared it. The call-time `provider_not_configured_error` keeps its own meaning.
80
+
81
+ - **`chain`'s input type parameter defaults to `never`.** An unannotated `chain()` used to produce a spine that accepted anything at `run`; the omission now fails at the `run` call site. **Breaking** for chains that leaned on the inferred `unknown`: state the type with `chain<Input>()` or `chain('name').input<Input>()`. Every call site in this repo already annotated, so the sweep changed none of them.
82
+
83
+ - **The viewer moved to the `fascicle/viewer` subpath.** `start_viewer`, `run_viewer_cli`, `StartViewerOptions`, and `ViewerHandle` are no longer re-exported from the package root. **Breaking**, one import line. The subpath also publishes `create_broadcaster`, `start_server`, and `start_tail`, which existed in the barrel but could not be reached from the published surface. The `fascicle-viewer` bin is unaffected.
84
+
85
+ - **`sequence` type checking.** Runtime-built homogeneous arrays infer as `Step<T, T>` through a new overload instead of degrading to `Step<unknown, unknown>` (which let `run(seq, wrong_type)` compile), a sound spread inside a literal tuple no longer false-positives, and a joint mismatch resolves to a branded `SequenceJointMismatch<At, Expected, Got>`, so the first line of the error names the position and the two types instead of two lines about optional properties.
86
+
87
+ - **Anonymous step ids are `step_<n>`** (previously `anon_<n>`), and a `model_call` without an explicit `id` mixes in an instance counter, so two identical leaves are distinguishable in `describe` and the trajectory.
88
+
89
+ - **`describe` shows the model call's knobs.** Temperature, token cap, `top_p`, and turn timeout appear by value when set, with `has_prepare_step` alongside the existing flags.
90
+
91
+ ### Fixed
92
+
93
+ - **`fallback` no longer discards the primary error.** When the backup also fails, the primary error rides along as the backup error's `cause`, so the interesting failure, why the fallback happened at all, survives to the catch site.
94
+
95
+ - **`retry` rejects a non-finite `max_attempts` at construction.** A `NaN`, easy to produce from arithmetic on a missing config field, previously ran zero attempts and rejected with a literal `undefined`: no message, no stack.
96
+
97
+ - **`model_call` names a missing engine.** Constructing without one threw `Cannot read properties of undefined (reading 'generate')` at dispatch; it now throws a `TypeError` at construction saying which option is missing and where an `Engine` comes from.
98
+
99
+ - **The stub engine reports what failed a schema.** It surfaces the validation issues and throws the real `schema_validation_error`, so a test can exercise the same handling production takes; it previously computed the issues, dropped them, and threw a bare `Error`.
100
+
101
+ - **Docs no longer teach a model id that 404s.** Every family shorthand (`sonnet`, `opus`, `haiku`) on an API transport became a concrete id, since the engine sends `model` verbatim and only `claude_cli` resolves bare tokens; the README tour and the first-run examples were the worst of it. Several recipes moved to local Ollama and other open models. A compile-only snippet gate cannot catch a wrong id, which is how these survived.
102
+
103
+ - **The cookbook's multi-provider fallback recipe routes to two providers.** Neither `model_step` set `provider`, so both calls, including the one asking for `gpt-4o`, resolved to the same adapter.
104
+
105
+ - **`docs/composition.md` is the composition guide again.** It was an old module README, still titled `# core`, ending in a stray closing tag that rendered on GitHub, with a public-surface table missing a dozen exports.
106
+
107
+ - **The stale concurrency caveat is gone.** Six documents warned that bundled span stacks attribute concurrent children to the wrong parent; the loggers have used the runner-threaded `parent_span_id` for a while, and the roadmap already claimed the fixed behavior. The synchronous-write caveat on `filesystem_logger` is real and stays.
108
+
109
+ - **Standard Schema is documented as such.** The reference printed `schema?: z.ZodType<t>` and said "a zod schema" in four places, while the contract is any Standard Schema; an ArkType or Valibot user reading it would conclude the headline feature did not exist.
110
+
111
+ - **A viewer regression test that never ran.** Its path to the built bundle carried an extra `..` from the old workspace layout, so it resolved above the repository root and skipped silently.
112
+
113
+ ### Internal
114
+
115
+ - `markdownlint` and `cspell` no longer ignore `docs/**`. That gap is how the stray tag and the stale claims survived every release; the twelve lint errors and forty-eight spelling flags it surfaced are fixed.
116
+ - The build's bundle invariants walk the root entry's static closure instead of grepping `dist/index.js`, so hoisting the engine into a shared chunk, which the testing subpath's value import now causes, no longer quietly stops the lazy `ai` seam from being checked. `fascicle/ui` is out of scope by design, since it imports `ai` on purpose.
117
+ - Getting-started gained a run scaffold (`"type": "module"`, Node 24, `tsx`), the keyless stub-engine path is advertised where a newcomer will see it, and the examples index marks which examples need a key.
118
+
3
119
  ## v0.12.0 — 2026-08-18
4
120
 
5
121
  ### Added
@@ -18,7 +134,7 @@
18
134
 
19
135
  - **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.
20
136
 
21
- - **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.
137
+ - **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.
22
138
 
23
139
  ### Changed
24
140
 
@@ -47,9 +163,9 @@
47
163
 
48
164
  ### Changed
49
165
 
50
- - **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.
166
+ - **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.
51
167
 
52
- - **`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.
168
+ - **`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.
53
169
 
54
170
  ### Internal
55
171
 
@@ -69,23 +185,23 @@
69
185
 
70
186
  ### Added
71
187
 
72
- - **`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.
188
+ - **`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.
73
189
 
74
190
  - **`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`.
75
191
 
76
192
  ### Changed
77
193
 
78
- - **`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.
194
+ - **`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.
79
195
 
80
196
  - **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.
81
197
 
82
- - **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.
198
+ - **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.
83
199
 
84
- - **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.
200
+ - **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.
85
201
 
86
202
  - **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`.
87
203
 
88
- - **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.
204
+ - **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.
89
205
 
90
206
  - **`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`.
91
207
 
@@ -104,7 +220,7 @@
104
220
  ### Internal
105
221
 
106
222
  - **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.
107
- - **`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`.
223
+ - **`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`.
108
224
  - **The check runner (checkride) is upgraded from 0.6.0 to 0.12.1.**
109
225
 
110
226
  ## v0.10.1 — 2026-08-07
@@ -131,7 +247,7 @@
131
247
 
132
248
  ### Internal
133
249
 
134
- - **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.
250
+ - **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.
135
251
 
136
252
  ## v0.9.11 — 2026-08-05
137
253
 
@@ -167,11 +283,11 @@ work is in the docs surface, the example apps, and the check suite.
167
283
  ### Fixed
168
284
 
169
285
  - **`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.
170
- - **`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.
286
+ - **`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.
171
287
 
172
288
  ### Internal
173
289
 
174
- - **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.
290
+ - **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.
175
291
  - **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.
176
292
  - 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.
177
293
  - **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.
@@ -182,7 +298,7 @@ work is in the docs surface, the example apps, and the check suite.
182
298
 
183
299
  ### Added
184
300
 
185
- - **`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.
301
+ - **`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.
186
302
  - 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).
187
303
 
188
304
  ### Changed
@@ -194,12 +310,12 @@ work is in the docs surface, the example apps, and the check suite.
194
310
  ### Added
195
311
 
196
312
  - **`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.
197
- - 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.
313
+ - 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.
198
314
  - 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.
199
315
 
200
316
  ### Changed
201
317
 
202
- - 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.
318
+ - 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.
203
319
  - 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`.
204
320
 
205
321
  ### Internal
@@ -210,8 +326,8 @@ work is in the docs surface, the example apps, and the check suite.
210
326
 
211
327
  ### Added
212
328
 
213
- - `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.
214
- - 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.
329
+ - `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.
330
+ - 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.
215
331
 
216
332
  ## v0.9.5 — 2026-07-12
217
333
 
@@ -265,7 +381,7 @@ work is in the docs surface, the example apps, and the check suite.
265
381
  ### Changed
266
382
 
267
383
  - **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.
268
- - 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.
384
+ - 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.
269
385
 
270
386
  ### Fixed
271
387
 
@@ -274,8 +390,8 @@ work is in the docs surface, the example apps, and the check suite.
274
390
 
275
391
  ### Internal
276
392
 
277
- - 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`).
278
- - 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`.
393
+ - 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`).
394
+ - 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`.
279
395
  - `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.
280
396
  - 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.
281
397
 
@@ -333,7 +449,7 @@ work is in the docs surface, the example apps, and the check suite.
333
449
 
334
450
  ### Added
335
451
 
336
- - 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.
452
+ - 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.
337
453
  - Live GitHub star count on the marketing site's nav button.
338
454
 
339
455
  ### Internal
@@ -447,7 +563,7 @@ work is in the docs surface, the example apps, and the check suite.
447
563
 
448
564
  ### Changed
449
565
 
450
- - **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.
566
+ - **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.
451
567
  - 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.
452
568
  - 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.)
453
569
  - 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.
@@ -496,17 +612,17 @@ work is in the docs surface, the example apps, and the check suite.
496
612
  - `examples/swebench`: `claude_cli` provider option, selectable via `SWEBENCH_PROVIDER`.
497
613
 
498
614
  ### Changed
499
- - **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`).
615
+ - **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`).
500
616
  - **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`.
501
617
 
502
618
  ### Fixed
503
- - 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.
619
+ - 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.
504
620
 
505
621
  ## v0.4.3 — 2026-05-10
506
622
 
507
623
  ### Added
508
624
  - `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.
509
- - `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.
625
+ - `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.
510
626
 
511
627
  ### Internal
512
628
  - `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.
@@ -535,16 +651,16 @@ work is in the docs surface, the example apps, and the check suite.
535
651
  ## v0.4.1 — 2026-05-09
536
652
 
537
653
  ### Added
538
- - `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.
654
+ - `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.
539
655
 
540
656
  ### Fixed
541
657
  - `@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.
542
- - `@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.
658
+ - `@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.
543
659
 
544
660
  ## v0.4.0 — 2026-05-07
545
661
 
546
662
  ### Fixed
547
- - `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.
663
+ - `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.
548
664
  - `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.
549
665
  - `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.
550
666
 
@@ -574,7 +690,7 @@ work is in the docs surface, the example apps, and the check suite.
574
690
  - `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.
575
691
  - `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.
576
692
  - `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.
577
- - `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.
693
+ - `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.
578
694
  - `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.
579
695
  - 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.
580
696
  - `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.
@@ -591,7 +707,7 @@ work is in the docs surface, the example apps, and the check suite.
591
707
  ## v0.3.5 — 2026-04-30
592
708
 
593
709
  ### Added
594
- - `@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`.
710
+ - `@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`.
595
711
  - `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`.
596
712
 
597
713
  ### Internal
@@ -623,7 +739,7 @@ work is in the docs surface, the example apps, and the check suite.
623
739
  ## v0.3.1 — 2026-04-29
624
740
 
625
741
  ### Internal
626
- - 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.
742
+ - 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.
627
743
 
628
744
  ## v0.3.0 — 2026-04-29
629
745
 
@@ -634,7 +750,7 @@ work is in the docs surface, the example apps, and the check suite.
634
750
  - `amplify` self-improvement loop example with a demo helper providing chart, measure, and reset utilities.
635
751
  - `learn` example with smoke test.
636
752
  - `EffortLevel` extended with `xhigh` and `max`, and reasoning support added to the `claude_cli` adapter.
637
- - `spec/plans/ideas.md` capturing possible directions to build on fascicle.
753
+ - `spec/plans/ideas.md` capturing possible directions to build on Fascicle.
638
754
 
639
755
  ### Changed
640
756
 
package/README.md CHANGED
@@ -12,7 +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
+
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`.
16
18
 
17
19
  ## A 60-second tour
18
20
 
@@ -35,12 +37,14 @@ Add a model call:
35
37
  import { create_engine, model_step, run, sequence, step } from 'fascicle';
36
38
 
37
39
  const engine = create_engine({
38
- providers: { anthropic: { api_key: process.env.ANTHROPIC_API_KEY! } },
40
+ providers: {
41
+ anthropic: { api_key: process.env.ANTHROPIC_API_KEY!, transport: 'native' },
42
+ },
39
43
  });
40
44
 
41
45
  const flow = sequence([
42
46
  step('brief', (topic: string) => `Write a 2-sentence brief on: ${topic}`),
43
- model_step({ engine, model: 'sonnet', system: 'No preamble.' }),
47
+ model_step({ engine, model: 'claude-sonnet-4-6', system: 'No preamble.' }),
44
48
  ]);
45
49
 
46
50
  try {
@@ -50,6 +54,8 @@ try {
50
54
  }
51
55
  ```
52
56
 
57
+ `transport: 'native'` keeps the zero-peer promise above: raw HTTP against the Messages API, nothing to install beyond `fascicle`. Drop it to use the default `ai_sdk` transport, which needs `pnpm add ai @ai-sdk/anthropic`.
58
+
53
59
  `model_step` returns the model's answer (a `string`, or the schema-validated value when `schema` is set), keeping flows at the `step, step, model_step, step` cadence. Underneath sits `model_call`, the only sanctioned bridge between composition and the engine: same config, but it returns the full `GenerateResult` envelope (usage, cost, tool calls, finish reason), with an optional `project` to map a slice of it at the source. Both thread `ctx.abort`, `ctx.trajectory`, and streaming chunks for you.
54
60
 
55
61
  ## What's in the box
@@ -74,7 +80,7 @@ Plus `run`, `run.stream`, and `describe`. And inside any step body, `ctx.call(st
74
80
 
75
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.
76
82
 
77
- 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).
78
84
 
79
85
  **Adapters injected per run.** Trajectory loggers and checkpoint stores ship under the `fascicle/adapters` subpath:
80
86
 
@@ -87,7 +93,7 @@ await run(flow, input, {
87
93
  });
88
94
  ```
89
95
 
90
- `filesystem_logger` writes synchronously and the bundled span stacks aren't async-context-aware — 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. 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.
91
97
 
92
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.
93
99
 
@@ -101,7 +107,7 @@ const engine = make_stub_engine([
101
107
  ]);
102
108
  ```
103
109
 
104
- **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>`:
105
111
 
106
112
  <!-- snippet: check -->
107
113
  ```typescript
@@ -177,7 +183,7 @@ Or embed it programmatically:
177
183
 
178
184
  <!-- snippet: check -->
179
185
  ```typescript
180
- import { start_viewer } from 'fascicle';
186
+ import { start_viewer } from 'fascicle/viewer';
181
187
 
182
188
  const handle = await start_viewer({ port: 4242 });
183
189
  // later
@@ -186,9 +192,9 @@ await handle.close();
186
192
 
187
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.
188
194
 
189
- ## Building an app on fascicle
195
+ ## Building an app on Fascicle
190
196
 
191
- **[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.
192
198
 
193
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).
194
200
 
@@ -198,19 +204,23 @@ The canonical worked example is [examples/pr-improve/](./examples/pr-improve/),
198
204
  - [docs/getting-started.md](./docs/getting-started.md) — install and run your first flow
199
205
  - [docs/concepts.md](./docs/concepts.md) — step-as-value, trajectories, cancellation
200
206
  - [docs/composition.md](./docs/composition.md) — full composition surface: the 22 primitives, run/stream, checkpointing
201
- - [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
202
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
203
209
  - [docs/api-reference.md](./docs/api-reference.md) — the public surface at a glance
204
210
  - [docs/configuration.md](./docs/configuration.md) — engine config, defaults, pricing, retries
205
211
  - [docs/providers.md](./docs/providers.md) — per-provider adapter notes
206
212
  - [docs/cli.md](./docs/cli.md) — the `claude_cli` subprocess adapter
207
213
  - [docs/cookbook.md](./docs/cookbook.md) — retries, fan-out, judges, HITL, tool loops
214
+ - [docs/deliberation-as-composition.md](./docs/deliberation-as-composition.md) — how ensembles, tournaments, consensus, and adversarial loops decompose into the primitives
215
+ - [docs/testing.md](./docs/testing.md) — testing flows with stub, script, and capture engines
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
208
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`
209
- - [docs/writing-a-harness.md](./docs/writing-a-harness.md) — building a runner around fascicle
210
- - [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
211
220
  - [docs/troubleshooting.md](./docs/troubleshooting.md) — first-run errors and what they mean
212
- - [docs/comparison.md](./docs/comparison.md) — how fascicle compares to LangChain, Mastra, and others
213
- - [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
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
214
224
  - [examples/](./examples/) — runnable reference flows; start with [examples/newsroom.ts](./examples/newsroom.ts), the vocabulary tour
215
225
  - [docs/viewer.md](./docs/viewer.md) — viewer details and transport options
216
226
 
@@ -220,7 +230,7 @@ Fascicle is early and not accepting outside pull requests yet. Bug reports and f
220
230
 
221
231
  ## Development
222
232
 
223
- This repo is a **single package**. The code is organized as deep modules under `src/` — `src/core`, `src/engine`, `src/composites`, `src/adapters`, `src/viewer`, `src/agents` — 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 5 apps under `examples/*/` are separate workspace members that consume the library via `fascicle: workspace:*`.
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 (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:*`.
224
234
 
225
235
  ```bash
226
236
  pnpm install