fascicle 0.12.1 → 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 (47) hide show
  1. package/CHANGELOG.md +79 -33
  2. package/README.md +13 -13
  3. package/dist/{adapters-hmnJOOgf.js → adapters-CutexJd3.js} +12 -12
  4. package/dist/adapters-CutexJd3.js.map +1 -0
  5. package/dist/adapters.d.ts +10 -10
  6. package/dist/adapters.js +1 -1
  7. package/dist/agents.d.ts +13 -3
  8. package/dist/agents.js +12 -5
  9. package/dist/agents.js.map +1 -1
  10. package/dist/{core-DDRhHu5P.js → core-DdJEhyQc.js} +122 -488
  11. package/dist/core-DdJEhyQc.js.map +1 -0
  12. package/dist/{engine-b4ZH8esY.js → engine-J4lIxpw5.js} +40 -357
  13. package/dist/engine-J4lIxpw5.js.map +1 -0
  14. package/dist/index.d.ts +85 -25
  15. package/dist/index.js +402 -48
  16. package/dist/index.js.map +1 -1
  17. package/dist/{invoke-CyKNhvBw.js → invoke-CH_eJZeS.js} +8 -8
  18. package/dist/{invoke-CyKNhvBw.js.map → invoke-CH_eJZeS.js.map} +1 -1
  19. package/dist/leading_system-BUCT-PwD.js +330 -0
  20. package/dist/leading_system-BUCT-PwD.js.map +1 -0
  21. package/dist/mcp.d.ts +5 -5
  22. package/dist/mcp.js +10 -9
  23. package/dist/mcp.js.map +1 -1
  24. package/dist/otel.d.ts +1 -1
  25. package/dist/otel.js +4 -4
  26. package/dist/otel.js.map +1 -1
  27. package/dist/stdio.d.ts +2 -2
  28. package/dist/stdio.js +2 -2
  29. package/dist/testing.d.ts +1 -1
  30. package/dist/testing.js +3 -2
  31. package/dist/testing.js.map +1 -1
  32. package/dist/{trajectory-cSLNlHzh.d.ts → trajectory-ByoOQZ6T.d.ts} +10 -10
  33. package/dist/trajectory-D1eq9eue.js +81 -0
  34. package/dist/trajectory-D1eq9eue.js.map +1 -0
  35. package/dist/{types-BCtKsxrX.d.ts → types-BK0UW28o.d.ts} +3 -3
  36. package/dist/{types-BqUY6nRX.d.ts → types-DBpU27sQ.d.ts} +7 -2
  37. package/dist/{types-CXBB4aIM.d.ts → types-DU6cvoA4.d.ts} +3 -3
  38. package/dist/ui.d.ts +1 -1
  39. package/dist/ui.js +1 -1
  40. package/dist/ui.js.map +1 -1
  41. package/dist/viewer.d.ts +8 -8
  42. package/dist/viewer.js +16 -15
  43. package/dist/viewer.js.map +1 -1
  44. package/package.json +5 -4
  45. package/dist/adapters-hmnJOOgf.js.map +0 -1
  46. package/dist/core-DDRhHu5P.js.map +0 -1
  47. package/dist/engine-b4ZH8esY.js.map +0 -1
package/CHANGELOG.md CHANGED
@@ -1,5 +1,51 @@
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
+
3
49
  ## v0.12.1 — 2026-08-18
4
50
 
5
51
  ### Added
@@ -22,7 +68,7 @@
22
68
 
23
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]`.
24
70
 
25
- - **A typed error path.** Every fascicle error class declares `path`, and `error_path(err)` reads it off any thrown value, including a foreign error the runner tagged on its way out. The documented diagnostic previously required a cast.
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.
26
72
 
27
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.
28
74
 
@@ -88,7 +134,7 @@
88
134
 
89
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.
90
136
 
91
- - **A one-file style pair in the examples.** `examples/release_notes.ts` and `examples/release_notes_direct.ts` build the same release-notes flow two ways — composed through `chain` and arms, and written straight through as one function — so the cost and the benefit of composing are readable side by side rather than asserted. `docs/blueprint.md` is rebuilt around `chain` and points at the pair.
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.
92
138
 
93
139
  ### Changed
94
140
 
@@ -117,9 +163,9 @@
117
163
 
118
164
  ### Changed
119
165
 
120
- - **A tool's JSON Schema no longer requires the fields that carry a default.** Provider payloads were emitted through Standard JSON Schema's *output* direction, which describes a value that has already been parsed: defaults are filled in by then, so `z.object({ city: z.string(), units: z.string().default('celsius') })` reached the model as `required: ["city","units"]`. That asked the model to supply a value the schema itself supplies, and made a defaulted field indistinguishable from a mandatory one. Emission now uses the *input* direction, which describes what the model should produce, so the same tool arrives as `required: ["city"]`. The input direction on its own also drops `additionalProperties: false` — the guard that stops a model inventing keys, and a prerequisite of several providers' strict and constrained-decode modes — so it is composed with a pass that closes every object node the vendor left open. This is the same pairing `@ai-sdk/provider-utils` applies to every `kind: 'ai_sdk'` provider (all seven fascicle configures by default), so the native adapters and `claude_cli` now send what the AI SDK path was already sending rather than a second, stricter shape for the same tool. Two restraints keep the closing pass from asserting more than the vendor did: an existing `additionalProperties` is never overwritten, so `z.looseObject`, a `z.record`'s value schema, and a server that published `true` all stay open (the AI SDK overwrites these); and a node is closed only if it declares `properties`, so a bare `{ type: 'object' }` — how a freeform payload is advertised — is left alone instead of being narrowed to "no keys permitted". One capability comes with it: `.output()` throws on a schema carrying a transform (`Transforms cannot be represented in JSON Schema`), so a tool whose schema contained one could not reach a native provider at all; the input direction emits it. **Breaking** on the wire for any tool or structured-output schema with a `.default()` or `.catch()` field: that field moves out of `required`, at every depth, including inside arrays and unions. Schemas without one are byte-identical to before, key order included. A knock-on for MCP: v0.10.3 made an inbound server's advertised schema reach the provider verbatim, and closing objects narrows that — a server that declares `properties` but says nothing about `additionalProperties` now has `additionalProperties: false` added on the native transports. The AI SDK path already did this to those same schemas, so the effect is that MCP tools now behave the same across all transports rather than differing by the one in use.
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.
121
167
 
122
- - **`loop` no longer wraps its output in a result envelope.** It returned `Step<i, LoopResult<o>>` — `{ value, converged, rounds }` — so anything that wanted the projected value had to strip `.value` first, and every one of the six in-repo call sites did: `adversarial` and `consensus` each carried a whole `pipe` for it, `improve` had an `improve_unwrap` step, the researcher agent wrapped its loop in a second `step` that called `inner.run` by hand (skipping the loop's own span) purely to return `result.value`, and both example apps hopped through `.value` at the read site. The envelope was a second projection channel layered over the one `loop` already had: `finish` is where the final state becomes the output, and it was already handed a piece of loop metadata (`round: number`) that no call site used. It now receives all of it — `finish: (state, outcome: LoopOutcome) => o`, with `LoopOutcome` being `{ converged, rounds }` — and `loop` returns `Step<i, o>`: exactly what `finish` projects, nothing around it. Non-convergence is still data rather than error; it arrives as an argument instead of a wrapper, which is why this shape was chosen over an `unwrap: true` flag (that would have needed two return types on one function, and would have discarded `converged` silently — the datum the whole convention rests on). Nothing is lost by dropping the envelope, because `finish` and the `loop({...})` call site always have the same author: the old shape is `finish: (state, outcome) => ({ value: state, ...outcome })`, opt-in in one line. Trajectories are unaffected: a traced composer's span records `{ id }` only, so `converged` and `rounds` were never in the trace to begin with. **Breaking:** `LoopResult` is gone from the published surface, replaced by `LoopOutcome`; a `loop` step's output type is now `o`; and a `finish` that declared a second parameter now receives the outcome object where the round count used to be. `docs/composition.md`, `docs/api-reference.md`, and `docs/deliberation-as-composition.md` state the new shape. In `examples/pr-improve` the `LOOP_RESULT` scope key becomes `FINAL_STATE`, since what the loop stashes is now the carry-state itself — whose own `round` field counts the same rounds the envelope reported.
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.
123
169
 
124
170
  ### Internal
125
171
 
@@ -139,23 +185,23 @@
139
185
 
140
186
  ### Added
141
187
 
142
- - **`ai` is now an optional peer dependency.** It was the last mandatory peer on a package whose own `dependencies` block is empty, so `pnpm add fascicle` forced an install of the AI SDK core even for a `transport: 'native'`-only or `claude_cli`-only setup that never imports it. `ai` is loaded lazily from the one `ai_sdk` turn seam (`src/engine/generate.ts`), same as every `@ai-sdk/*` provider package, so it drops to `peerDependenciesMeta: { ai: { optional: true } }` alongside them; a missing `ai` reports through the same `load_optional_peer` message step 7 named it in. `docs/providers.md` and `README.md` now show `ai` alongside each `ai_sdk`-kind provider's install snippet, since the official `@ai-sdk/*` packages only peer-depend on `zod`, not `ai` — installing just `@ai-sdk/anthropic` no longer pulls `ai` in transitively now that fascicle's own peer is optional.
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.
143
189
 
144
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`.
145
191
 
146
192
  ### Changed
147
193
 
148
- - **`zod` is now an optional peer dependency, and fascicle has zero mandatory peers.** It was the last one: `ai` went optional earlier in this release, and the Standard Schema migration removed every internal zod import from `src/` except the type-only one in `src/mcp/serve.ts` (`McpServer.registerTool` accepts nothing else). `zod` drops to `peerDependenciesMeta: { zod: { optional: true } }` alongside every other peer, so `pnpm add fascicle` alone builds and runs a flow against `transport: 'native'` or `claude_cli` — no AI SDK, no schema library. Schemas accept any Standard Schema implementation (zod, ArkType, Valibot, …); installing zod remains necessary only if that is the vendor you choose. The `no-core-npm-dep-except-zod` and `no-engine-npm-dep-except-ai-zod` ast-grep rules, which permitted an npm dependency neither zone still uses, are replaced by `no-core-npm-dep` and `no-engine-npm-dep`: core and engine (outside `providers/`) now depend on no npm package at all, matching the `#schema`/`#policy` bottom-of-DAG zones that already carry the vendor-specific code. `README.md`, `docs/getting-started.md`, `VALUES.md`, and `SECURITY.md` state the zero-mandatory-peers posture directly.
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.
149
195
 
150
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.
151
197
 
152
- - **Every schema fascicle validates now runs through Standard Schema, so validation failures read the same whichever library produced them.** Tool inputs, structured-output parsing, `suspend` resume data, and both `run_stdio` IO checks called zod's `safeParse` directly and reported whatever zod handed back. They now go through the vendor-neutral `~standard.validate` interface, so an ArkType or Valibot schema validates on the same path a zod one does. Two things consumers can see change shape. The message fed back to a model on a rejected tool call (and the schema repair prompt, and `schema_validation_error.message`) was zod's own multi-line JSON dump of its issue objects; it is now one line of `path: message` clauses with dotted paths — `city: Invalid input: expected string, received number; opts.deep: Invalid input: expected boolean, received string`. And the `cause` on a `run_stdio` `validate_input` / `validate_output` failure now carries `{ message, path }` issues instead of zod's issue objects, so the `code` and `expected` fields are gone from that JSON. Nothing that was validated before validates differently: only the report changed.
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.
153
199
 
154
- - **Schema failures are now reported vendor-neutrally end to end, closing out the zod-shaped naming and reporting left over from the Standard Schema migration.** `schema_validation_error` (thrown by `generate` and the `claude_cli` adapter after repair attempts are exhausted) carried a field named `.zod_error`; it is renamed `.schema_issues` and now holds the vendor-neutral `{ message, path? }` issue list directly rather than an `Error` wrapping a pre-formatted string. The engine's `schema_validation_failed` trajectory event's `zod_issues` field is renamed `schema_issues` (same one-line formatted string as before). `suspend`'s `resume_validation_error.issues` — called out above as unchanged — now also carries the vendor-neutral issue list instead of a hand-rolled reproduction of zod's `{ formErrors, fieldErrors }` shape. The internal `format_zod_error` helper is gone; formatting goes through `format_schema_issues` everywhere. **Breaking:** code reading `schema_validation_error.zod_error`, `resume_validation_error.issues.formErrors` / `.fieldErrors`, or a trajectory consumer reading `schema_validation_failed.zod_issues` needs to move to the renamed fields and shapes.
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.
155
201
 
156
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`.
157
203
 
158
- - **The `zod` peer dependency is pinned to exactly `4.4.3`, up from `^4.0.0`.** fascicle is moving to emit provider JSON Schema through Standard JSON Schema (`~standard.jsonSchema`) rather than `z.toJSONSchema`, and that interface does not exist before zod 4.2.0: on 4.1.12 `~standard.jsonSchema` is `undefined`, so the old `^4.0.0` range named a floor that cannot work. The pin is exact rather than a range so that the one version fascicle is tested against is the one version it promises; 4.2.0 and 4.4.3 emit byte-identical draft-2020-12 schemas, so this is a choice about which version is guaranteed, not about behaviour. **Breaking:** an install that resolves zod to any other version, including a later patch such as 4.4.4, now reports a peer dependency conflict, and a project whose other packages peer-depend on a zod range excluding 4.4.3 cannot satisfy both at once. zod is an optional peer as of this release, which lifts the requirement for anyone who never installs it, but a consumer using zod schemas with fascicle still has to be on 4.4.3.
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.
159
205
 
160
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`.
161
207
 
@@ -174,7 +220,7 @@
174
220
  ### Internal
175
221
 
176
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.
177
- - **`docs/comparison.md` places NVIDIA's Switchyard.** A wire-level routing proxy is a different layer, not competition: aligned with fascicle on keeping routing policy outside the model surface (its `libsy` library hands every model call back to the caller, the same separation as adapters passed in per run and verbatim model resolution), different on where routing belongs (rewriting traffic for clients you cannot modify versus explicit composition when you own the call site), and usable today as one more OpenAI-compatible gateway behind the compat recipe in `docs/providers.md`.
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`.
178
224
  - **The check runner (checkride) is upgraded from 0.6.0 to 0.12.1.**
179
225
 
180
226
  ## v0.10.1 — 2026-08-07
@@ -201,7 +247,7 @@
201
247
 
202
248
  ### Internal
203
249
 
204
- - **The Bedrock guardrail docs show how to read the trace the change above made readable.** `docs/providers.md` gains a worked read of `provider_reported.bedrock.trace` beside the existing guardrail recipe, `docs/troubleshooting.md` gains an entry for the symptom that actually gets reported ("the guardrail seems ignored, the output came back unchanged"), and the adapter docstring carries the same claim at the source. The entry separates policy from wiring: a PII action of `NONE` detects without rewriting, so unchanged output is the configured behaviour rather than a dropped `guardrailConfig`, and the way to test the wiring instead is a deliberately invalid `guardrailIdentifier`: AWS rejects the call only if the config reached the Converse command, so a call that succeeds is the failure signal.
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.
205
251
 
206
252
  ## v0.9.11 — 2026-08-05
207
253
 
@@ -237,11 +283,11 @@ work is in the docs surface, the example apps, and the check suite.
237
283
  ### Fixed
238
284
 
239
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.
240
- - **`examples/pr-improve` could not run on its own default provider.** It defaulted every role to `'sonnet'`/`'opus'` and claimed in comments that the engine expands those per provider. It does not — `model` is passed to the provider verbatim — so the documented default path (`FASCICLE_PROVIDER=anthropic`) sent a literal `"sonnet"` and got a not-found error. There is now one per-provider model table, resolved once and threaded as data, which also removes a second copy of that table and makes the `FASCICLE_MODEL_*` overrides reach the flow; they were previously parsed and discarded.
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.
241
287
 
242
288
  ### Internal
243
289
 
244
- - **The check suite is now [checkride](https://www.npmjs.com/package/checkride) 0.6.0**, replacing the hand-rolled orchestrator. `scripts/check.mjs`, `check-links.mjs`, `check-doc-snippets.mjs`, and `check-publish.mjs` are deleted (~960 lines) in favour of built-in slots; `scripts/check-deps.mjs` stays as the one custom check, since the core/engine dependency invariant is fascicle-specific. The `pnpm check` / `check:all` / `check:json` / `check:bail` contract is unchanged and `pnpm check --changed` is new.
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.
245
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.
246
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.
247
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.
@@ -252,7 +298,7 @@ work is in the docs surface, the example apps, and the check suite.
252
298
 
253
299
  ### Added
254
300
 
255
- - **`define_agent` call-shaping config.** `DefineAgentConfig` accepts `model` and `schema_repair_attempts`, closing the gap where the blueprint's "models are threaded as data" rule could not be followed on the `fascicle/agents` surface (and where schema repair — set on every model call observed in production consumers — required dropping to a stage factory). Precedence: `config.model` > frontmatter `model` > engine default; the blueprint's stage-factory section now states the same rule.
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.
256
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).
257
303
 
258
304
  ### Changed
@@ -264,12 +310,12 @@ work is in the docs surface, the example apps, and the check suite.
264
310
  ### Added
265
311
 
266
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.
267
- - A dedicated architecture page on the site (`site/blueprint.html`): the agent blueprint's one rule, adoption tiers, module contracts, anti-patterns, and ast-grep enforcement story, linked from both existing pages. `AGENTS.md` and the README now route agents and humans building *on* fascicle to `docs/blueprint.md` first, and a new `examples/README.md` indexes the example apps around it.
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.
268
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.
269
315
 
270
316
  ### Changed
271
317
 
272
- - Documentation synced with the implementation across `docs/` and the site. The composition surface is documented as 21 primitives (adding `ensemble_step`, `improve`, and `learn` to every list and to the site's interactive tour); site code samples now show the real config-object APIs (`branch` / `map` / `ensemble` / `tournament` / `consensus`, `adversarial`'s required `accept`, `suspend`'s required `on`, `retry`'s `backoff_ms`); engine docs corrected for `claude_cli` reasoning-effort forwarding (`CLAUDE_CODE_EFFORT_LEVEL`), the `'timeout'` member of `DEFAULT_RETRY.retry_on`, the real missing-peer error message, `inherit_env` semantics, the full `EngineConfig` shape, and the complete error and Engine-method lists.
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.
273
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`.
274
320
 
275
321
  ### Internal
@@ -280,8 +326,8 @@ work is in the docs surface, the example apps, and the check suite.
280
326
 
281
327
  ### Added
282
328
 
283
- - `docs/blueprint.md`: a standard app architecture for building on fascicle — one composition layer, three adoption tiers, markdown prompts, normalized module shapes, stub-engine testing, and field-observed anti-patterns distilled from the example apps and production consumers.
284
- - Three ast-grep boundary rules wired into `examples/pr-improve` (runnable via `check:rules`): `create_engine` confined to `engine.ts`, no imperative loops in `flow.ts`, and fascicle value imports confined to the files allowed to know about it.
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.
285
331
 
286
332
  ## v0.9.5 — 2026-07-12
287
333
 
@@ -335,7 +381,7 @@ work is in the docs surface, the example apps, and the check suite.
335
381
  ### Changed
336
382
 
337
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.
338
- - Usage and cost accounting is verified against v7's nested token-detail shape (`inputTokenDetails`/`outputTokenDetails`, cache-inclusive `inputTokens`, reasoning-inclusive `outputTokens`) with concrete-value tests per provider. On `@ai-sdk/anthropic` v4, cache read and write tokens now fold into `inputTokens` upstream, which makes fascicle's cost subtraction formula exact instead of skewed for cache-heavy Anthropic calls.
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.
339
385
 
340
386
  ### Fixed
341
387
 
@@ -344,8 +390,8 @@ work is in the docs surface, the example apps, and the check suite.
344
390
 
345
391
  ### Internal
346
392
 
347
- - Releases are now published from CI with npm Trusted Publishing (OIDC) and a signed provenance attestation, gated by a required-reviewer GitHub Environment (`.github/workflows/publish.yaml`). No long-lived npm token exists anywhere; verify a release with `npm audit signatures`. This makes v0.9.0 the first provenance-attested fascicle publish (see `research/provenance-publish-spec.md`).
348
- - Agent-layer boundary ADR: fascicle stays on the single-turn seam (`generateText`/`streamText`) and declines the v7 agent layer (`ToolLoopAgent`, `WorkflowAgent`, `HarnessAgent`, `toolApproval`, `@ai-sdk/otel`), recorded in `research/explorations/2026-07-ai-sdk-agent-layer-boundary.md` and linked from `docs/providers.md`.
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`.
349
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.
350
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.
351
397
 
@@ -403,7 +449,7 @@ work is in the docs surface, the example apps, and the check suite.
403
449
 
404
450
  ### Added
405
451
 
406
- - Native constrained decoding for schema-constrained `model_call` on local providers (Ollama and LM Studio), exposed as a new `structured_output` provider capability: the schema now constrains the provider's decode (e.g. Ollama's `format`) instead of prompting for JSON and scraping it, so local-model structured output no longer fails validation on the first call. The prompt-based path remains the fallback, and hosted providers are unchanged.
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.
407
453
  - Live GitHub star count on the marketing site's nav button.
408
454
 
409
455
  ### Internal
@@ -517,7 +563,7 @@ work is in the docs surface, the example apps, and the check suite.
517
563
 
518
564
  ### Changed
519
565
 
520
- - **Breaking: model resolution is now a verbatim pass-through.** `model` is an opaque string sent to the provider unchanged; `provider` selects the transport. There is one canonical input shape — separate `provider` + `model` params — and no interpretation in between.
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.
521
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.
522
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.)
523
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.
@@ -566,17 +612,17 @@ work is in the docs surface, the example apps, and the check suite.
566
612
  - `examples/swebench`: `claude_cli` provider option, selectable via `SWEBENCH_PROVIDER`.
567
613
 
568
614
  ### Changed
569
- - **Breaking.** `create_engine` no longer ships default aliases — the alias table starts empty and is reserved for your own named pins. The built-in `cli-*`, `or:*`, `gemini-pro`/`gemini-flash`, and `gpt-4o*` aliases are gone; use `{ model, provider }` pairs (e.g. `{ model: 'sonnet', provider: 'claude_cli' }`) or the colon form (`openrouter:meta-llama/llama-3.3-70b-instruct`).
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`).
570
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`.
571
617
 
572
618
  ### Fixed
573
- - A family with no entry for the chosen provider (e.g. `opus` on `openai`) now throws the descriptive `model_family_unavailable_error` instead of the generic not-found path.
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.
574
620
 
575
621
  ## v0.4.3 — 2026-05-10
576
622
 
577
623
  ### Added
578
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.
579
- - `examples/pr-improve` Phase C, PR B: builder dispatches by provider. `make_builder_call` now takes `worktree_root` and `provider` explicit params; under `claude_cli` it keeps the schema-only path that delegates to the CLI's built-in Read/Write/Edit, and under API providers (`anthropic`, `openrouter`) it returns a `model_call` configured with the worktree-scoped tools from `make_builder_tools(worktree_root)`. The `Step<string, GenerateResult<Handoff>>` contract is unchanged; `flow.ts` ripples in one place via a new `FlowEnv = { worktree_root, provider }` arg to `build_flow`. The portability proof — same end-to-end result under `--provider claude_cli` and `--provider anthropic` — is now live.
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.
580
626
 
581
627
  ### Internal
582
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.
@@ -605,16 +651,16 @@ work is in the docs surface, the example apps, and the check suite.
605
651
  ## v0.4.1 — 2026-05-09
606
652
 
607
653
  ### Added
608
- - `examples/pr-improve`: an automated PR-improvement pipeline composed as a four-stage fascicle flow — reviewer (sonnet) → pragmatist (opus, default-reject) → builder (sonnet) → build-reviewer (opus) — inside a bounded `loop` with `guard`-driven convergence. Routes every model call through the engine, so the same flow runs against `anthropic`, `openrouter`, or a local `claude_cli` subprocess by changing one env var. Includes `--pr` mode for posting review suggestions back to a GitHub PR via safe-spawn `gh`/`git` wrappers, and a `bin/pr-improve` entrypoint.
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.
609
655
 
610
656
  ### Fixed
611
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.
612
- - `@repo/engine` `claude_cli` provider: schema-repair attempt count is now configurable (was: hard-coded), giving callers control over the retry-vs-fail-fast tradeoff.
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.
613
659
 
614
660
  ## v0.4.0 — 2026-05-07
615
661
 
616
662
  ### Fixed
617
- - `claude_cli` adapter: `build_env` now seeds the standard process-env keys (`PATH`, `HOME`, `SHELL`, `USER`, `LOGNAME`, `LANG`, `TMPDIR`) under every `auth_mode` (was: only inherited under `oauth`). Sandbox-enabled runs under `auto`/`api_key` previously spawned with an empty `PATH` and failed with `ENOENT` looking up `greywall`/`bwrap`. Set `inherit_env: false` to opt out of the standard-key seeding.
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.
618
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.
619
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.
620
666
 
@@ -644,7 +690,7 @@ work is in the docs surface, the example apps, and the check suite.
644
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.
645
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.
646
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.
647
- - `tee_logger` adapter in `@repo/observability`: fan one `TrajectoryLogger` contract out to N sinks. First sink's `start_span` id is canonical; per-sink ids are translated back on `end_span`; sinks that throw don't derail the others.
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.
648
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.
649
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.
650
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.
@@ -661,7 +707,7 @@ work is in the docs surface, the example apps, and the check suite.
661
707
  ## v0.3.5 — 2026-04-30
662
708
 
663
709
  ### Added
664
- - `@repo/viewer` package and `fascicle-viewer` CLI: minimal in-repo dev dashboard for visualizing a fascicle run as it executes. Single static HTML page (vanilla JS, no build step), an SSE-fed span tree with active/error/emit highlighting, and a click-to-expand event log. Two transports feed one in-process broadcaster: file-tail (`fascicle-viewer .trajectory.jsonl`) for the primary case and HTTP push (`fascicle-viewer --listen` plus the new `http_logger`) for low-latency or remote attach. Localhost-only by default. Programmatic embed via `start_viewer({...})`. See `packages/viewer/README.md`.
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`.
665
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`.
666
712
 
667
713
  ### Internal
@@ -693,7 +739,7 @@ work is in the docs surface, the example apps, and the check suite.
693
739
  ## v0.3.1 — 2026-04-29
694
740
 
695
741
  ### Internal
696
- - Colocated unit tests under `__tests__/` subfolders (e.g. `packages/core/src/branch.ts` ↔ `packages/core/src/__tests__/branch.test.ts`); cross-cutting tests under `packages/<name>/test/` are unchanged.
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.
697
743
 
698
744
  ## v0.3.0 — 2026-04-29
699
745
 
@@ -704,7 +750,7 @@ work is in the docs surface, the example apps, and the check suite.
704
750
  - `amplify` self-improvement loop example with a demo helper providing chart, measure, and reset utilities.
705
751
  - `learn` example with smoke test.
706
752
  - `EffortLevel` extended with `xhigh` and `max`, and reasoning support added to the `claude_cli` adapter.
707
- - `spec/plans/ideas.md` capturing possible directions to build on fascicle.
753
+ - `spec/plans/ideas.md` capturing possible directions to build on Fascicle.
708
754
 
709
755
  ### Changed
710
756
 
package/README.md CHANGED
@@ -12,7 +12,7 @@ No framework lifecycle. No ambient state. No decorators. Adapters are passed in
12
12
  pnpm add fascicle
13
13
  ```
14
14
 
15
- fascicle is ESM-only and requires Node >= 24. `ai`, `zod`, and every provider SDK are optional peers — install only the ones you use. `pnpm add fascicle` alone builds and runs a flow against `transport: 'native'` or `claude_cli`, with no AI SDK package and no schema library installed at all; schemas accept any [Standard Schema](https://standardschema.dev) — zod, ArkType, Valibot, whichever you already use. See [docs/providers.md](./docs/providers.md).
15
+ Fascicle is ESM-only and requires Node >= 24. `ai`, `zod`, and every provider SDK are optional peers — install only the ones you use. `pnpm add fascicle` alone builds and runs a flow against `transport: 'native'` or `claude_cli`, with no AI SDK package and no schema library installed at all; schemas accept any [Standard Schema](https://standardschema.dev) — zod, ArkType, Valibot, whichever you already use. See [docs/providers.md](./docs/providers.md).
16
16
 
17
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`.
18
18
 
@@ -80,7 +80,7 @@ Plus `run`, `run.stream`, and `describe`. And inside any step body, `ctx.call(st
80
80
 
81
81
  **AI engine.** `create_engine(config)` returns one `generate` surface across eight providers. Two axes: `model` is an opaque id sent to the provider verbatim (`claude-opus-4-8`, `gpt-4o`, `us.anthropic.claude-sonnet-4-20250514-v1:0`), and `provider` names the transport (`anthropic`, `bedrock`, `openrouter`, `claude_cli`, …) — swap `provider` to move a call between transports. Reasoning effort (`'none'` through `'max'`) is translated per provider. Cost estimation uses a pricing table with per-engine overrides.
82
82
 
83
- The engine core is SDK-agnostic: providers plug in behind a neutral single-turn seam, as one of three kinds. Most built-ins wrap Vercel's AI SDK (`ai_sdk`); five providers can instead run `transport: 'native'` (raw HTTP, no AI SDK in the path, no peer to install) — `anthropic` on the Messages API, `openai`/`openrouter`/`lmstudio` on a shared OpenAI Chat Completions core, and `ollama` on its own `/api/chat` endpoint; and `claude_cli` delegates to an external agent. All inherit the same tool loop, retry, cost, and trajectory, and `custom_providers` registers your own adapter of any kind without touching fascicle. See [docs/providers.md](./docs/providers.md).
83
+ The engine core is SDK-agnostic: providers plug in behind a neutral single-turn seam, as one of three kinds. Most built-ins wrap Vercel's AI SDK (`ai_sdk`). Five providers can instead run `transport: 'native'` (raw HTTP, no AI SDK in the path, no peer to install) — `anthropic` on the Messages API, `openai`/`openrouter`/`lmstudio` on a shared OpenAI Chat Completions core, and `ollama` on its own `/api/chat` endpoint. The third kind is `claude_cli`, which delegates to an external agent. All inherit the same tool loop, retry, cost, and trajectory, and `custom_providers` registers your own adapter of any kind without touching Fascicle. See [docs/providers.md](./docs/providers.md).
84
84
 
85
85
  **Adapters injected per run.** Trajectory loggers and checkpoint stores ship under the `fascicle/adapters` subpath:
86
86
 
@@ -93,7 +93,7 @@ await run(flow, input, {
93
93
  });
94
94
  ```
95
95
 
96
- `filesystem_logger` writes synchronously (each event blocks the event loop briefly), which is fine for dev tools and short-lived runs; see [docs/concepts.md](./docs/concepts.md#adapter-limits) before wiring it into a long-running server. Span parentage is threaded through the runner, so span trees stay correct under `parallel`/`map` concurrency. The `TrajectoryLogger` and `CheckpointStore` contracts (exported from `fascicle`) are tiny — roll your own to push events to Honeycomb, S3, etc.
96
+ `filesystem_logger` writes synchronously (each event blocks the event loop briefly), which is fine for dev tools and short-lived runs; see [docs/concepts.md](./docs/concepts.md#adapter-limits) before wiring it into a long-running server. Span parentage is threaded through the runner, so span trees stay correct under `parallel`/`map` concurrency. The `TrajectoryLogger` and `CheckpointStore` contracts (exported from `fascicle`) are tiny — roll your own to push events to Honeycomb, S3, and so on.
97
97
 
98
98
  `run.stream(flow, input)` returns `{ events, result }` for incremental observation, and `run.until_suspended(flow, input)` drives human-in-the-loop flows: a `suspend` gate resolves to a typed outcome with a `resume` closure instead of throwing.
99
99
 
@@ -107,7 +107,7 @@ const engine = make_stub_engine([
107
107
  ]);
108
108
  ```
109
109
 
110
- **Markdown-defined agents.** When an agent is just a prompt plus an output schema, `define_agent` (the `fascicle/agents` subpath) folds a markdown file — frontmatter `name` / `model` / `temperature`, body as the prompt — and a zod schema into a `Step<i, o>`:
110
+ **Markdown-defined agents.** When an agent is just a prompt plus an output schema, `define_agent` (the `fascicle/agents` subpath) folds a markdown file (frontmatter `name` / `model` / `temperature`, with the body as the prompt) and a zod schema into a `Step<i, o>`:
111
111
 
112
112
  <!-- snippet: check -->
113
113
  ```typescript
@@ -192,9 +192,9 @@ await handle.close();
192
192
 
193
193
  For zero-latency streaming from inside a long-running flow, pair it with `http_logger` from `fascicle/adapters`. See [docs/viewer.md](./docs/viewer.md) for the full transport story.
194
194
 
195
- ## Building an app on fascicle
195
+ ## Building an app on Fascicle
196
196
 
197
- **[docs/blueprint.md](./docs/blueprint.md) is the recommended architecture for apps built on fascicle** — distilled from the reference apps and production consumers. One composition layer (`flow.ts`) that holds the whole topology, `create_engine` confined to one file, prompts as markdown with frontmatter, zod schemas as the stage contracts, stub-engine testing, and [ast-grep rules](./examples/pr-improve/rules/) that turn each boundary into a build failure. If you are a coding agent scaffolding a new fascicle app, follow the blueprint and its checklist.
197
+ **[docs/blueprint.md](./docs/blueprint.md) is the recommended architecture for apps built on Fascicle** — distilled from the reference apps and production consumers. One composition layer (`flow.ts`) that holds the whole topology, `create_engine` confined to one file, prompts as markdown with frontmatter, zod schemas as the stage contracts, stub-engine testing, and [ast-grep rules](./examples/pr-improve/rules/) that turn each boundary into a build failure. If you are a coding agent scaffolding a new Fascicle app, follow the blueprint and its checklist.
198
198
 
199
199
  The canonical worked example is [examples/pr-improve/](./examples/pr-improve/), with its design rationale in [examples/pr-improve/docs/architecture.md](./examples/pr-improve/docs/architecture.md).
200
200
 
@@ -204,7 +204,7 @@ The canonical worked example is [examples/pr-improve/](./examples/pr-improve/),
204
204
  - [docs/getting-started.md](./docs/getting-started.md) — install and run your first flow
205
205
  - [docs/concepts.md](./docs/concepts.md) — step-as-value, trajectories, cancellation
206
206
  - [docs/composition.md](./docs/composition.md) — full composition surface: the 22 primitives, run/stream, checkpointing
207
- - [docs/leaf-arm-spine.md](./docs/leaf-arm-spine.md) — the three-layer shape of a fascicle flow and how to choose the right primitive at each layer
207
+ - [docs/leaf-arm-spine.md](./docs/leaf-arm-spine.md) — the three-layer shape of a Fascicle flow and how to choose the right primitive at each layer
208
208
  - [docs/advanced-composition.md](./docs/advanced-composition.md) — the primitives to reach for last (`scope`/`stash`/`use`, `ensemble`, `tournament`, `improve`/`learn`) and when they earn their keep
209
209
  - [docs/api-reference.md](./docs/api-reference.md) — the public surface at a glance
210
210
  - [docs/configuration.md](./docs/configuration.md) — engine config, defaults, pricing, retries
@@ -215,12 +215,12 @@ The canonical worked example is [examples/pr-improve/](./examples/pr-improve/),
215
215
  - [docs/testing.md](./docs/testing.md) — testing flows with stub, script, and capture engines
216
216
  - [docs/regression-testing-model-behavior.md](./docs/regression-testing-model-behavior.md) — regression-testing model behavior with mutation-tested judges and a committed score baseline
217
217
  - [docs/human-in-the-loop.md](./docs/human-in-the-loop.md) — suspend/resume approval over HTTP and streaming to a `useChat` UI via `fascicle/ui`
218
- - [docs/writing-a-harness.md](./docs/writing-a-harness.md) — building a runner around fascicle
219
- - [docs/embedding-under-a-harness.md](./docs/embedding-under-a-harness.md) — running a fascicle agent as somebody's child process
218
+ - [docs/writing-a-harness.md](./docs/writing-a-harness.md) — building a runner around Fascicle
219
+ - [docs/embedding-under-a-harness.md](./docs/embedding-under-a-harness.md) — running a Fascicle agent as somebody's child process
220
220
  - [docs/troubleshooting.md](./docs/troubleshooting.md) — first-run errors and what they mean
221
- - [docs/comparison.md](./docs/comparison.md) — how fascicle compares to LangChain, Mastra, and others
222
- - [docs/adoption-decision.md](./docs/adoption-decision.md) weighs whether to adopt fascicle: the honest case, the risks, and when to reach for something else
223
- - [docs/roadmap.md](./docs/roadmap.md) — what has shipped, what is being considered, and what fascicle deliberately will not do
221
+ - [docs/comparison.md](./docs/comparison.md) — how Fascicle compares to LangChain, Mastra, and others
222
+ - [docs/adoption-decision.md](./docs/adoption-decision.md) weighs whether to adopt Fascicle: the honest case, the risks, and when to reach for something else
223
+ - [docs/roadmap.md](./docs/roadmap.md) — what has shipped, what is being considered, and what Fascicle deliberately will not do
224
224
  - [examples/](./examples/) — runnable reference flows; start with [examples/newsroom.ts](./examples/newsroom.ts), the vocabulary tour
225
225
  - [docs/viewer.md](./docs/viewer.md) — viewer details and transport options
226
226
 
@@ -230,7 +230,7 @@ Fascicle is early and not accepting outside pull requests yet. Bug reports and f
230
230
 
231
231
  ## Development
232
232
 
233
- This repo is a **single package**. The code is organized as deep modules under `src/` (`core`, `engine`, `composites`, `agents`, `adapters`, `mcp`, `stdio`, `ui`, `otel`, `policy`, `schema`, `testing`, `viewer`), each reachable only through its barrel via the `#<module>` import alias. The umbrella surface at the `src/` root is what publishes to npm as `fascicle`. Architectural boundaries (e.g. core cannot import adapters; engine imports core type-only; no `process.env` outside the audited exceptions) are enforced by the ast-grep rules in `rules/` and a directory-level boundary DAG in `fallow.toml`. The 7 apps under `examples/*/` are separate workspace members that consume the library via `fascicle: workspace:*`.
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:*`.
234
234
 
235
235
  ```bash
236
236
  pnpm install
@@ -6,7 +6,7 @@ import { appendFileSync, mkdirSync } from "node:fs";
6
6
  /**
7
7
  * Shared span/record core for trajectory loggers.
8
8
  *
9
- * Every fascicle trajectory logger emits the same wire format (one JSON object
9
+ * Every Fascicle trajectory logger emits the same wire format (one JSON object
10
10
  * per event) and differs only in where each event goes: `line_logger` writes a
11
11
  * line, `http_logger` POSTs NDJSON. This module holds the span bookkeeping they
12
12
  * share, parameterized by a single `emit` sink.
@@ -81,8 +81,8 @@ function line_logger(write_line) {
81
81
  * Create a `TrajectoryLogger` that appends one JSON object per line to
82
82
  * `output_path`, creating the parent directory if needed.
83
83
  */
84
- function filesystem_logger(options) {
85
- const { output_path } = options;
84
+ function filesystem_logger(config) {
85
+ const { output_path } = config;
86
86
  mkdirSync(dirname(output_path), { recursive: true });
87
87
  return line_logger((event) => {
88
88
  appendFileSync(output_path, `${JSON.stringify(event)}\n`);
@@ -102,15 +102,15 @@ const default_fetch = async (url, init) => {
102
102
  };
103
103
  /**
104
104
  * Create a `TrajectoryLogger` that POSTs each event as NDJSON to
105
- * `options.url`.
105
+ * `config.url`.
106
106
  *
107
107
  * Never throws: a transport failure is dropped and reported through the
108
108
  * optional `on_error` callback, so a dev viewer being unreachable never
109
109
  * blocks the flow.
110
110
  */
111
- function http_logger(options) {
112
- const { url, on_error } = options;
113
- const send = options.fetch ?? default_fetch;
111
+ function http_logger(config) {
112
+ const { url, on_error } = config;
113
+ const send = config.fetch ?? default_fetch;
114
114
  const post = (event) => {
115
115
  const body = `${JSON.stringify(event)}\n`;
116
116
  send(url, {
@@ -207,7 +207,7 @@ function tee_logger(...loggers) {
207
207
  * Satisfies `CheckpointStore` from `core`. Each key is stored as
208
208
  * a JSON file under the configured root directory. Writes are all-or-nothing:
209
209
  * values are written to a temporary sibling file and then atomically renamed
210
- * into place, so an interrupted write never leaves a partially-written file
210
+ * into place, so an interrupted write never leaves a partially written file
211
211
  * at the target key. On `get`, a missing file, a partial temp file that was
212
212
  * never atomically renamed, or a JSON parse failure each read as a cache
213
213
  * miss (returning `null`) rather than an error.
@@ -226,10 +226,10 @@ function safe_filename(key) {
226
226
  return `${key.replace(/[^a-zA-Z0-9._-]/g, "_").slice(0, 64)}.${hash}.json`;
227
227
  }
228
228
  /**
229
- * Create a `CheckpointStore` backed by JSON files under `options.root_dir`.
229
+ * Create a `CheckpointStore` backed by JSON files under `config.root_dir`.
230
230
  */
231
- function filesystem_store(options) {
232
- const { root_dir } = options;
231
+ function filesystem_store(config) {
232
+ const { root_dir } = config;
233
233
  const ensure_root = async () => {
234
234
  await mkdir(root_dir, { recursive: true });
235
235
  };
@@ -267,4 +267,4 @@ function filesystem_store(options) {
267
267
  //#endregion
268
268
  export { http_logger as a, noop_logger as i, tee_logger as n, filesystem_logger as o, stderr_logger as r, filesystem_store as t };
269
269
 
270
- //# sourceMappingURL=adapters-hmnJOOgf.js.map
270
+ //# sourceMappingURL=adapters-CutexJd3.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"adapters-CutexJd3.js","names":[],"sources":["../src/adapters/trajectory_recorder.ts","../src/adapters/line_logger.ts","../src/adapters/filesystem_logger.ts","../src/adapters/http_logger.ts","../src/adapters/noop_logger.ts","../src/adapters/stderr_logger.ts","../src/adapters/tee_logger.ts","../src/adapters/filesystem_store.ts"],"sourcesContent":["/**\n * Shared span/record core for trajectory loggers.\n *\n * Every Fascicle trajectory logger emits the same wire format (one JSON object\n * per event) and differs only in where each event goes: `line_logger` writes a\n * line, `http_logger` POSTs NDJSON. This module holds the span bookkeeping they\n * share, parameterized by a single `emit` sink.\n *\n * `start_span` and `end_span` each emit one event; `record` emits the event as\n * written. When the caller supplies `parent_span_id` in the span meta (the\n * runner threads the true structural parent through `RunContext`), that value is\n * used verbatim, so span trees are correct even for concurrent children under\n * `parallel`/`map`. Only when no parent is supplied does the recorder fall back\n * to an in-memory stack of still-open spans, which is best-effort under\n * concurrency.\n */\n\nimport { randomUUID } from 'node:crypto'\nimport type { TrajectoryLogger } from '#core'\n\n/**\n * Build a `TrajectoryLogger` whose events are handed, one at a time, to `emit`.\n */\nexport function trajectory_recorder(\n emit: (event: Record<string, unknown>) => void,\n): TrajectoryLogger {\n const stack: string[] = []\n\n const start_span: TrajectoryLogger['start_span'] = (name, meta) => {\n const span_id = `${name}:${randomUUID().slice(0, 8)}`\n const event: Record<string, unknown> = { kind: 'span_start', span_id, name, ...meta }\n // Prefer the caller-threaded structural parent; fall back to the open-span\n // stack only when none was supplied (best-effort under concurrency).\n if (event['parent_span_id'] === undefined && stack.length > 0) {\n event['parent_span_id'] = stack[stack.length - 1]\n }\n emit(event)\n stack.push(span_id)\n return span_id\n }\n\n const end_span: TrajectoryLogger['end_span'] = (id, meta) => {\n emit({ kind: 'span_end', span_id: id, ...meta })\n const idx = stack.lastIndexOf(id)\n if (idx !== -1) stack.splice(idx, 1)\n }\n\n const record: TrajectoryLogger['record'] = (event) => {\n emit({ ...event })\n }\n\n return { record, start_span, end_span }\n}\n","/**\n * Line-oriented trajectory logger core.\n *\n * `filesystem_logger` and `stderr_logger` emit the same wire format (one JSON\n * object per line) and differ only in where the line goes. Both build on this:\n * `line_logger` adapts the shared span/record core (`trajectory_recorder`) to a\n * `write_line` sink, so the span bookkeeping and `parent_span_id` handling that\n * keep span trees correct under `parallel`/`map` live in exactly one place.\n */\n\nimport type { TrajectoryLogger } from '#core'\nimport { trajectory_recorder } from './trajectory_recorder.js'\n\n/**\n * Create a `TrajectoryLogger` that writes one JSON object per line via\n * `write_line`.\n */\nexport function line_logger(write_line: (event: Record<string, unknown>) => void): TrajectoryLogger {\n return trajectory_recorder(write_line)\n}\n","/**\n * Filesystem JSONL trajectory logger.\n *\n * Appends one JSON object per line to a configured output file. Span\n * bookkeeping (including the `parent_span_id` handling that keeps span trees\n * correct for concurrent children under `parallel`/`map`) lives in\n * `line_logger`. Two concurrent `run(...)` calls that pass distinct logger\n * instances (constructed with distinct `output_path`s) share nothing.\n *\n * Paths are accepted at construction; the logger never reads `process.env`.\n */\n\nimport { appendFileSync, mkdirSync } from 'node:fs'\nimport { dirname } from 'node:path'\nimport type { TrajectoryLogger } from '#core'\nimport { line_logger } from './line_logger.js'\n\nexport type FilesystemLoggerConfig = {\n readonly output_path: string\n}\n\n/**\n * Create a `TrajectoryLogger` that appends one JSON object per line to\n * `output_path`, creating the parent directory if needed.\n */\nexport function filesystem_logger(config: FilesystemLoggerConfig): TrajectoryLogger {\n const { output_path } = config\n mkdirSync(dirname(output_path), { recursive: true })\n\n return line_logger((event) => {\n appendFileSync(output_path, `${JSON.stringify(event)}\\n`)\n })\n}\n","/**\n * HTTP push trajectory logger.\n *\n * Conforms to `TrajectoryLogger`. POSTs each event as a single line of\n * newline-delimited JSON to a configured URL. Pairs naturally with the\n * Fascicle viewer's `/api/ingest` endpoint, but is a generic adapter: the\n * receiver can be anything that accepts NDJSON over HTTP.\n *\n * Failure policy: drop on transport error and invoke the optional `on_error`\n * callback. Never throws, never blocks the user's flow on a dev tool being\n * up. The flow always wins; the viewer is best-effort.\n *\n * Span bookkeeping (including the `parent_span_id` handling that mirrors\n * `filesystem_logger` so the wire format is identical) lives in the shared\n * `trajectory_recorder`; this adapter only supplies the emit sink.\n */\n\nimport type { TrajectoryLogger } from '#core'\nimport { trajectory_recorder } from './trajectory_recorder.js'\n\nexport type HttpLoggerFetch = (\n url: string,\n init: { method: 'POST'; headers: Record<string, string>; body: string },\n) => Promise<{ ok: boolean; status: number }>\n\nexport type HttpLoggerConfig = {\n readonly url: string\n readonly fetch?: HttpLoggerFetch\n readonly on_error?: (err: unknown) => void\n}\n\n/**\n * Default `HttpLoggerFetch`, backed by the global `fetch`.\n */\nconst default_fetch: HttpLoggerFetch = async (url, init) => {\n const res = await fetch(url, init)\n return { ok: res.ok, status: res.status }\n}\n\n/**\n * Create a `TrajectoryLogger` that POSTs each event as NDJSON to\n * `config.url`.\n *\n * Never throws: a transport failure is dropped and reported through the\n * optional `on_error` callback, so a dev viewer being unreachable never\n * blocks the flow.\n */\nexport function http_logger(config: HttpLoggerConfig): TrajectoryLogger {\n const { url, on_error } = config\n const send = config.fetch ?? default_fetch\n\n const post = (event: Record<string, unknown>): void => {\n const body = `${JSON.stringify(event)}\\n`\n void send(url, {\n method: 'POST',\n headers: { 'content-type': 'application/x-ndjson' },\n body,\n })\n .then((res) => {\n if (!res.ok && on_error) on_error(new Error(`http_logger: POST ${url} -> ${res.status}`))\n })\n .catch((err: unknown) => {\n if (on_error) on_error(err)\n })\n }\n\n return trajectory_recorder(post)\n}\n","/**\n * No-op trajectory logger.\n *\n * Satisfies `TrajectoryLogger` from `core` without emitting any\n * output. Used as the default when no logger is supplied to `run(...)` and as\n * a cheap fallback in tests that do not care about trajectory output.\n */\n\nimport { randomUUID } from 'node:crypto'\nimport type { TrajectoryLogger } from '#core'\n\n/**\n * Create a `TrajectoryLogger` whose methods do nothing.\n */\nexport function noop_logger(): TrajectoryLogger {\n return {\n record: () => {},\n start_span: (name) => `${name}:${randomUUID().slice(0, 8)}`,\n end_span: () => {},\n }\n}\n","/**\n * Stderr JSONL trajectory logger.\n *\n * Writes one JSON object per line to stderr (or an injected stream), leaving\n * stdout untouched. This is the blessed console logger for agents that run as\n * somebody's child process: under the stdio agent contract, stdout carries the\n * result envelope and belongs to the parent, so trajectory must go elsewhere.\n * The wire format is identical to `filesystem_logger`, so captured stderr is a\n * valid trajectory JSONL file (`2>events.jsonl`) the viewer parses unchanged.\n *\n * Writes never throw: a broken pipe or closed stream drops the event rather\n * than failing the flow.\n */\n\nimport type { TrajectoryLogger } from '#core'\nimport { line_logger } from './line_logger.js'\n\nexport type StderrLoggerOptions = {\n readonly stream?: { write(chunk: string): unknown }\n}\n\n/**\n * Create a `TrajectoryLogger` that writes one JSON object per line to\n * stderr, or to `options.stream` when supplied.\n */\nexport function stderr_logger(options: StderrLoggerOptions = {}): TrajectoryLogger {\n const stream = options.stream ?? process.stderr\n return line_logger((event) => {\n try {\n stream.write(`${JSON.stringify(event)}\\n`)\n } catch {\n // Never throw from a logger; the flow always wins.\n }\n })\n}\n","/**\n * tee_logger: fan one TrajectoryLogger contract out to many sinks.\n *\n * Each sink receives every record/start_span/end_span call. Sinks are called\n * in registration order and exceptions in one sink do not prevent the others\n * from receiving the event.\n *\n * The first sink's `start_span` return value is treated as canonical and\n * returned to the caller; the tee remembers each sink's per-sink id so that\n * `end_span(canonical_id, ...)` translates back to the right id for each sink.\n * Within any one sink the wire format stays internally consistent; only the\n * across-sink ids may differ.\n */\n\nimport type { TrajectoryLogger } from '#core'\n\n/**\n * Create a `TrajectoryLogger` that fans every call out to `loggers`.\n */\nexport function tee_logger(...loggers: ReadonlyArray<TrajectoryLogger>): TrajectoryLogger {\n if (loggers.length === 0) {\n throw new Error('tee_logger: at least one logger required')\n }\n\n const id_map = new Map<string, ReadonlyArray<string>>()\n\n const safe_each = (fn: (l: TrajectoryLogger, idx: number) => void): void => {\n for (let i = 0; i < loggers.length; i += 1) {\n const l = loggers[i]\n if (l === undefined) continue\n try {\n fn(l, i)\n } catch {\n // best-effort fan-out: a misbehaving sink must not derail the others\n }\n }\n }\n\n return {\n record: (event) => {\n safe_each((l) => l.record(event))\n },\n start_span: (name, meta) => {\n const ids: string[] = []\n safe_each((l) => {\n ids.push(l.start_span(name, meta))\n })\n const canonical = ids[0] ?? `${name}:tee`\n if (loggers.length > 1) id_map.set(canonical, ids)\n return canonical\n },\n end_span: (id, meta) => {\n const ids = id_map.get(id)\n if (ids === undefined) {\n safe_each((l) => l.end_span(id, meta))\n return\n }\n id_map.delete(id)\n safe_each((l, idx) => l.end_span(ids[idx] ?? id, meta))\n },\n }\n}\n","/**\n * Filesystem-backed checkpoint store.\n *\n * Satisfies `CheckpointStore` from `core`. Each key is stored as\n * a JSON file under the configured root directory. Writes are all-or-nothing:\n * values are written to a temporary sibling file and then atomically renamed\n * into place, so an interrupted write never leaves a partially written file\n * at the target key. On `get`, a missing file, a partial temp file that was\n * never atomically renamed, or a JSON parse failure each read as a cache\n * miss (returning `null`) rather than an error.\n *\n * Paths are accepted at construction; the store never reads `process.env`.\n */\n\nimport { createHash, randomUUID } from 'node:crypto'\nimport { mkdir, readFile, rename, rm, writeFile } from 'node:fs/promises'\nimport { join } from 'node:path'\nimport type { CheckpointStore } from '#core'\n\nexport type FilesystemStoreConfig = {\n readonly root_dir: string\n}\n\n/**\n * Turn a checkpoint key into a filesystem-safe filename.\n *\n * Slugs the key down to `[a-zA-Z0-9._-]` and appends a short hash of the\n * full key, so two keys that slug to the same string still land on distinct\n * files.\n */\nfunction safe_filename(key: string): string {\n const hash = createHash('sha256').update(key).digest('hex').slice(0, 12)\n const slug = key.replace(/[^a-zA-Z0-9._-]/g, '_').slice(0, 64)\n return `${slug}.${hash}.json`\n}\n\n/**\n * Create a `CheckpointStore` backed by JSON files under `config.root_dir`.\n */\nexport function filesystem_store(config: FilesystemStoreConfig): CheckpointStore {\n const { root_dir } = config\n\n const ensure_root = async (): Promise<void> => {\n await mkdir(root_dir, { recursive: true })\n }\n\n const path_for = (key: string): string => join(root_dir, safe_filename(key))\n\n const get = async (key: string): Promise<unknown> => {\n const path = path_for(key)\n let raw: string\n try {\n raw = await readFile(path, 'utf8')\n } catch {\n return null\n }\n try {\n return JSON.parse(raw) as unknown\n } catch {\n return null\n }\n }\n\n const set = async (key: string, value: unknown): Promise<void> => {\n await ensure_root()\n const target = path_for(key)\n const tmp = `${target}.${randomUUID().slice(0, 8)}.tmp`\n await writeFile(tmp, JSON.stringify(value), 'utf8')\n await rename(tmp, target)\n }\n\n const delete_key = async (key: string): Promise<void> => {\n const target = path_for(key)\n await rm(target, { force: true })\n }\n\n return { get, set, delete: delete_key }\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;AAuBA,SAAgB,oBACd,MACkB;CAClB,MAAM,QAAkB,CAAC;CAEzB,MAAM,cAA8C,MAAM,SAAS;EACjE,MAAM,UAAU,GAAG,KAAK,GAAG,WAAW,CAAC,CAAC,MAAM,GAAG,CAAC;EAClD,MAAM,QAAiC;GAAE,MAAM;GAAc;GAAS;GAAM,GAAG;EAAK;EAGpF,IAAI,MAAM,sBAAsB,KAAA,KAAa,MAAM,SAAS,GAC1D,MAAM,oBAAoB,MAAM,MAAM,SAAS;EAEjD,KAAK,KAAK;EACV,MAAM,KAAK,OAAO;EAClB,OAAO;CACT;CAEA,MAAM,YAA0C,IAAI,SAAS;EAC3D,KAAK;GAAE,MAAM;GAAY,SAAS;GAAI,GAAG;EAAK,CAAC;EAC/C,MAAM,MAAM,MAAM,YAAY,EAAE;EAChC,IAAI,QAAQ,IAAI,MAAM,OAAO,KAAK,CAAC;CACrC;CAEA,MAAM,UAAsC,UAAU;EACpD,KAAK,EAAE,GAAG,MAAM,CAAC;CACnB;CAEA,OAAO;EAAE;EAAQ;EAAY;CAAS;AACxC;;;;;;;ACnCA,SAAgB,YAAY,YAAwE;CAClG,OAAO,oBAAoB,UAAU;AACvC;;;;;;;;;;;;;;;;;;ACMA,SAAgB,kBAAkB,QAAkD;CAClF,MAAM,EAAE,gBAAgB;CACxB,UAAU,QAAQ,WAAW,GAAG,EAAE,WAAW,KAAK,CAAC;CAEnD,OAAO,aAAa,UAAU;EAC5B,eAAe,aAAa,GAAG,KAAK,UAAU,KAAK,EAAE,GAAG;CAC1D,CAAC;AACH;;;;;;ACEA,MAAM,gBAAiC,OAAO,KAAK,SAAS;CAC1D,MAAM,MAAM,MAAM,MAAM,KAAK,IAAI;CACjC,OAAO;EAAE,IAAI,IAAI;EAAI,QAAQ,IAAI;CAAO;AAC1C;;;;;;;;;AAUA,SAAgB,YAAY,QAA4C;CACtE,MAAM,EAAE,KAAK,aAAa;CAC1B,MAAM,OAAO,OAAO,SAAS;CAE7B,MAAM,QAAQ,UAAyC;EACrD,MAAM,OAAO,GAAG,KAAK,UAAU,KAAK,EAAE;EACtC,KAAU,KAAK;GACb,QAAQ;GACR,SAAS,EAAE,gBAAgB,uBAAuB;GAClD;EACF,CAAC,CAAC,CACC,MAAM,QAAQ;GACb,IAAI,CAAC,IAAI,MAAM,UAAU,yBAAS,IAAI,MAAM,qBAAqB,IAAI,MAAM,IAAI,QAAQ,CAAC;EAC1F,CAAC,CAAC,CACD,OAAO,QAAiB;GACvB,IAAI,UAAU,SAAS,GAAG;EAC5B,CAAC;CACL;CAEA,OAAO,oBAAoB,IAAI;AACjC;;;;;;;;;;;;;ACrDA,SAAgB,cAAgC;CAC9C,OAAO;EACL,cAAc,CAAC;EACf,aAAa,SAAS,GAAG,KAAK,GAAG,WAAW,CAAC,CAAC,MAAM,GAAG,CAAC;EACxD,gBAAgB,CAAC;CACnB;AACF;;;;;;;ACKA,SAAgB,cAAc,UAA+B,CAAC,GAAqB;CACjF,MAAM,SAAS,QAAQ,UAAU,QAAQ;CACzC,OAAO,aAAa,UAAU;EAC5B,IAAI;GACF,OAAO,MAAM,GAAG,KAAK,UAAU,KAAK,EAAE,GAAG;EAC3C,QAAQ,CAER;CACF,CAAC;AACH;;;;;;ACfA,SAAgB,WAAW,GAAG,SAA4D;CACxF,IAAI,QAAQ,WAAW,GACrB,MAAM,IAAI,MAAM,0CAA0C;CAG5D,MAAM,yBAAS,IAAI,IAAmC;CAEtD,MAAM,aAAa,OAAyD;EAC1E,KAAK,IAAI,IAAI,GAAG,IAAI,QAAQ,QAAQ,KAAK,GAAG;GAC1C,MAAM,IAAI,QAAQ;GAClB,IAAI,MAAM,KAAA,GAAW;GACrB,IAAI;IACF,GAAG,GAAG,CAAC;GACT,QAAQ,CAER;EACF;CACF;CAEA,OAAO;EACL,SAAS,UAAU;GACjB,WAAW,MAAM,EAAE,OAAO,KAAK,CAAC;EAClC;EACA,aAAa,MAAM,SAAS;GAC1B,MAAM,MAAgB,CAAC;GACvB,WAAW,MAAM;IACf,IAAI,KAAK,EAAE,WAAW,MAAM,IAAI,CAAC;GACnC,CAAC;GACD,MAAM,YAAY,IAAI,MAAM,GAAG,KAAK;GACpC,IAAI,QAAQ,SAAS,GAAG,OAAO,IAAI,WAAW,GAAG;GACjD,OAAO;EACT;EACA,WAAW,IAAI,SAAS;GACtB,MAAM,MAAM,OAAO,IAAI,EAAE;GACzB,IAAI,QAAQ,KAAA,GAAW;IACrB,WAAW,MAAM,EAAE,SAAS,IAAI,IAAI,CAAC;IACrC;GACF;GACA,OAAO,OAAO,EAAE;GAChB,WAAW,GAAG,QAAQ,EAAE,SAAS,IAAI,QAAQ,IAAI,IAAI,CAAC;EACxD;CACF;AACF;;;;;;;;;;;;;;;;;;;;;;;AC/BA,SAAS,cAAc,KAAqB;CAC1C,MAAM,OAAO,WAAW,QAAQ,CAAC,CAAC,OAAO,GAAG,CAAC,CAAC,OAAO,KAAK,CAAC,CAAC,MAAM,GAAG,EAAE;CAEvE,OAAO,GADM,IAAI,QAAQ,oBAAoB,GAAG,CAAC,CAAC,MAAM,GAAG,EAC9C,EAAE,GAAG,KAAK;AACzB;;;;AAKA,SAAgB,iBAAiB,QAAgD;CAC/E,MAAM,EAAE,aAAa;CAErB,MAAM,cAAc,YAA2B;EAC7C,MAAM,MAAM,UAAU,EAAE,WAAW,KAAK,CAAC;CAC3C;CAEA,MAAM,YAAY,QAAwB,KAAK,UAAU,cAAc,GAAG,CAAC;CAE3E,MAAM,MAAM,OAAO,QAAkC;EACnD,MAAM,OAAO,SAAS,GAAG;EACzB,IAAI;EACJ,IAAI;GACF,MAAM,MAAM,SAAS,MAAM,MAAM;EACnC,QAAQ;GACN,OAAO;EACT;EACA,IAAI;GACF,OAAO,KAAK,MAAM,GAAG;EACvB,QAAQ;GACN,OAAO;EACT;CACF;CAEA,MAAM,MAAM,OAAO,KAAa,UAAkC;EAChE,MAAM,YAAY;EAClB,MAAM,SAAS,SAAS,GAAG;EAC3B,MAAM,MAAM,GAAG,OAAO,GAAG,WAAW,CAAC,CAAC,MAAM,GAAG,CAAC,EAAE;EAClD,MAAM,UAAU,KAAK,KAAK,UAAU,KAAK,GAAG,MAAM;EAClD,MAAM,OAAO,KAAK,MAAM;CAC1B;CAEA,MAAM,aAAa,OAAO,QAA+B;EAEvD,MAAM,GADS,SAAS,GACV,GAAG,EAAE,OAAO,KAAK,CAAC;CAClC;CAEA,OAAO;EAAE;EAAK;EAAK,QAAQ;CAAW;AACxC"}