4.1.1 Prerequisites🔗ℹ

• A pipeline that runs. If you don’t have one, work through Getting Started first.

• A jq install (or equivalent) for filtering JSON on the command line.

4.1.2 1. Enable a receiver🔗ℹ

Stone’s observability is a single logger, stone-logger. To see anything, subscribe a receiver and drain it from a thread. The pattern below writes each event to trace.jsonl as JSON:

(require racket/logging stone/logging json)

(define trace-out (open-output-file "trace.jsonl" #:exists 'append))

(define receiver  (make-log-receiver stone-logger 'info))

; stone-event builds hashes with symbol keys and arbitrary

; Racket values; write-json only accepts a narrow subset,

; so coerce everything on the way out.

(define (->json-safe v)

(cond

[(or (string? v) (boolean? v) (exact-integer? v)) v]

[(and (real? v) (rational? v)) (exact->inexact v)]

[(symbol? v) (symbol->string v)]

[(keyword? v) (keyword->string v)]

[(path? v) (path->string v)]

[(null? v) '()]

[(hash? v)

(for/hash ([(k val) (in-hash v)])

(values (if (symbol? k) k (string->symbol (format "~a" k)))

(->json-safe val)))]

[(list? v) (map ->json-safe v)]

[(vector? v) (map ->json-safe (vector->list v))]

[(void? v) 'null]

[else (format "~v" v)]))

(define logger-thread

(thread

(lambda ()

(let loop ()

(define evt (sync receiver))

(with-handlers ([exn:fail? (lambda (_) (void))])

(write-json

(hash 'level   (->json-safe (vector-ref evt 0))

'message (->json-safe (vector-ref evt 1))

'data    (->json-safe (vector-ref evt 2))

'topic   (->json-safe (vector-ref evt 3)))

trace-out)

(newline trace-out)

(flush-output trace-out))

(loop)))))

The ->json-safe helper isn’t optional. stone-event emits Racket hashes keyed by symbols and holding arbitrary values (DAG nodes, message lists, paths); write-json will raise on anything outside its accepted subset.

4.1.3 2. Parameterize a trace id🔗ℹ

Wrap run-pipeline in a parameterize so every event carries the same trace id:

(define tid (generate-id "run-"))

(define sid (generate-id "span-"))

(parameterize ([current-trace-id tid]

[current-span-id sid])

(run-pipeline my-pipeline (make-dag)))

Every event in this run will carry the same 'trace-id, making it easy to isolate a single run in a shared log file. Span ids are re-allocated per ashlar invocation by the framework wrapper.

4.1.4 3. Read the stream🔗ℹ

With the trace file written, common debugging questions become jq queries. Each line is one event; the structured payload is under 'data.

ashlar-name is hyphenated, so it must be quoted in jq paths. Same goes for trace-id, span-id, parent-span-id.

4.1.5 4. Enable debug-level events when you need them🔗ℹ

'ashlar-start, 'ashlar-end, and 'middleware-run are emitted at debug level. A receiver subscribed at 'info won’t see them. When you need "did this ashlar actually run?", subscribe at debug:

(define receiver (make-log-receiver stone-logger 'debug))

Debug is noisy. Use it, get the answer, turn it back down.

4.1.6 5. Follow a specific trace-id🔗ℹ

When you’re tailing a shared log file and one run misbehaved, filter by trace id:

generate-id returns "<prefix><ms>-<random>", so the prefix you chose ("run-", "tdd-", whatever) is the fastest way to scope a query.

4.1.7 6. Read failure events🔗ℹ

When any ashlar creates a failure node, stone/logging auto-emits an 'error-level event. No user code needs to opt in:

The 'event field of an error event is the failure kind (e.g. 'llm-parse-failed, 'loop-exhausted). The 'reason field is the message. For a given failure, the triple (span-id, event, reason) usually tells you which ashlar failed and why in one line.

4.1.8 7. Check the DAG after a run🔗ℹ

The pipeline’s final DAG is still available after run-pipeline returns. When logs say "something failed" but you want to see what actually landed in the DAG, inspect it directly:

(define-values (result final-dag)

(parameterize ([current-trace-id tid] [current-span-id sid])

(run-pipeline my-pipeline (make-dag))))

(for ([(id n) (in-hash (dag-nodes final-dag))])

(displayln (list (node-type n) (node-content n))))

Useful when an ashlar produced a partial result before failing downstream — the partial result is still in final-dag, and no amount of log-scanning will show you its content the way dag-nodes will.

4.1.9 8. Test-time interception🔗ℹ

For unit tests, use with-intercepted-logging to capture events in-process without writing to a file:

(require racket/logging stone/logging)

(define events (box '()))

(with-intercepted-logging

(lambda (v) (set-box! events (cons v (unbox events))))

(lambda () (run-pipeline my-pipeline (make-dag)))

#:logger stone-logger

'info 'stone)

The #:logger stone-logger keyword is mandatory. Because stone-logger is defined with #:parent #f, its events never reach the root logger, and a call that omits the keyword attaches to the root logger — it captures nothing and the test passes for the wrong reason.

4.1.10 Troubleshooting🔗ℹ

• Trace file is empty. Either no receiver is subscribed, or the receiver thread hasn’t drained before process exit. Kill or join the logger thread before closing the output port.

• Events have ashlar-name: false. The ashlar was created without #:name or #:produces. The framework should auto-generate a name; if you see false the framework may be out of date relative to the pipeline.

• with-intercepted-logging captures nothing. You forgot #:logger stone-logger.

• Duplicate events from the same ashlar. A ashlar-meta can be composed into multiple positions in a pipeline, and each invocation emits its own events with distinct span-ids — the events aren’t duplicates, they’re separate runs of the same ashlar.

4.1.11 See also🔗ℹ

• Observability — the conceptual model.

• Trace a run — the minimal setup for writing a trace file.

• Handle failures (below) — writing pipelines that recover from the error events you see here.

4.2.1 Prerequisites🔗ℹ

• A working Stone pipeline — if you don’t have one yet, follow Getting Started first.

4.2.2 Steps🔗ℹ

4.2.3 Reading the trace🔗ℹ

Once you have a trace.jsonl, the raco stone trace subcommands cover the canonical investigation flow:

• Start with tally. raco stone trace tally trace.jsonl prints total event count and per-event-type counts. Use it as a first-pass health check — unexpected counts (e.g. lots of 'sse-trip-raised or 'hypothesis-mismatch) point at where to look next.

• Then walk lifecycle. raco stone trace lifecycle trace.jsonl prints the ashlar-by-ashlar story of the run: starts, ends, tool dispatches, api-calls. One line per event, in chronological order. Use it to find the moment something went wrong.

• Then dump payload. raco stone trace payload trace.jsonl –ashlar <name> –turn <n> shows what the agent actually sent on a specific turn — system prompt, every message, every tool call. This is what you read when the lifecycle view tells you a turn went sideways and you want to know why. –last picks the most recent matching payload.

"api-call-payload" events are only emitted at the 'debug log level. If payload returns No api-call-payload found, re-run your pipeline with 'debug level on the log receiver (or STONE_LOG_LEVEL=debug in environments that honor it) so the full message contents land in the trace.

For programmatic access to the trace from Racket code (custom inspection tools, ad-hoc scripts), see stone/trace.

4.2.4 Troubleshooting🔗ℹ

• Empty trace file. The receiver is probably attached to the wrong logger. stone-logger has #:parent #f so it doesn’t propagate to the root logger — a receiver on (current-logger) sees nothing. Use stone-logger explicitly.

• Missing events. Raise the level on the receiver. 'info misses 'ashlar-start/'ashlar-end; switch to 'debug.

• Trailing events lost. The background thread may still be draining when your program exits. If you care about every event, call flush-output on trace-out and sleep for a few tens of milliseconds before exit, or drain the receiver with sync/timeout in a tight loop.

4.2.5 See also🔗ℹ

• Observability — the full design of Stone’s logging: correlation parameters, event vocabulary, failure auto-logging.

• Debug a pipeline in the how-to section — using a live receiver to watch events during development.

4.3.1 Prerequisites🔗ℹ

• A pipeline: a module that builds and exports a ashlar-meta value (see Getting Started).

• Stone installed and visible to Racket.

4.3.2 1. Validate from the REPL or a script🔗ℹ

Call validate-pipeline on a ashlar-meta value:

(require stone/validate)

(define result (validate-pipeline pipeline))

(if (validation-ok? result)

(displayln "valid")

(for ([err (validation-errors result)])

(displayln (format "[~a] ~a: ~a"

(validation-error-type err)

(or (validation-error-ashlar-name err) "?")

(validation-error-message err)))))

validate-pipeline returns a validation-result struct. validation-errors pulls the error list out of it; validation-ok? is true when the list contains no hard errors. Each validation-error has four fields: type, ashlar-name, queried-type, and message. The type field is a symbol ('missing-producer, 'maybe-unavailable, 'invalid-lens, or 'fanout-not-reduced) that tells you which class of problem the validator hit.

4.3.3 2. Validate from the command line🔗ℹ

Stone provides a validate subcommand on raco stone. It takes a path to a pipeline file, loads it via dynamic-require, and runs validate-pipeline on the binding named pipeline:

The pipeline file must be a Racket module that provides a binding named exactly pipeline, bound to a ashlar-meta? value:

(require stone stone/llm-ashlar stone/llm-client)

(provide pipeline)

(define caller (make-openai-caller #:url "http://localhost:8000"))

(define pipeline

(~> ashlar-an ashlar-b))

On success the CLI prints one line and exits 0:

When the topology has hard errors, you get a header and one line per error formatted as [<type>] <ashlar-name>: <message>, and the CLI exits 1:

Warnings ('maybe-unavailable) print in a separate Warnings (N): block and don’t change the exit code.

4.3.4 3. Interpret common errors🔗ℹ

4.3.5 4. Integrate validation into your workflow🔗ℹ

4.3.6 5. Enumerate ashlars in a topology🔗ℹ

enumerate-ashlars returns a flat list of every ashlar’s name. Use it for inventories, tables of contents, topology diagrams, or counts:

(enumerate-ashlars pipeline)

; => '(ashlar-an ashlar-b ashlar-c ...)

enumerate-paths returns the distinct execution paths through the topology, each a list of ashlar names:

(enumerate-paths pipeline)

; => '((ashlar-an ashlar-b ashlar-c)

;  (ashlar-an ashlar-b ashlar-d))

Sequences concatenate along a single path. Matches and parallels fork. Loops collapse to a single representative path — one iteration of the body.

4.3.7 Troubleshooting🔗ℹ

• "does not export ’pipeline’". The CLI calls dynamic-require on the file and looks for a binding named exactly pipeline. Rename your exported topology to pipeline, or add a thin alias (define pipeline my-real-topology) alongside the export.

• Validator passes but the pipeline fails at runtime. Static validation only catches structural mismatches. LLM responses that don’t match the schema, network failures, tool errors, and bad healer output still happen at runtime — see Debug a pipeline.

• 'maybe-unavailable in output that should be fine. Check whether your ashlar-match branches all produce the same types. If they do but the validator still warns, restructure the match or accept the warning as a known soft signal.

4.3.8 See also🔗ℹ

• Validation — the full design.

• Edge Primitives — the composition vocabulary being validated.

• Debug a pipeline — inspecting runtime failures the validator can’t catch.

4.4.1 Prerequisites🔗ℹ

• A working Stone pipeline. If you don’t have one, work through Getting Started first.

• A basic understanding of typed nodes and DAG queries. See The DAG as Pipeline State if those terms are new.

4.4.2 1. The shape of a custom ashlar🔗ℹ

A custom ashlar is make-ashlar applied to a function that takes a DAG and returns a node. The function reads whatever it needs from the DAG, does its work, and hands back one node.

(require stone)

(define my-ashlar

(make-ashlar

(lambda (dag)

(typed-node dag 'my-type

(hasheq 'result "something")))

#:produces 'my-type

#:name 'my-ashlar))

typed-node is a convenience over make-typed-node that defaults the parents to (dag-heads dag) — the DAG frontier the ashlar was just handed. That’s what you want 99% of the time. Reach for the full make-typed-node form when you need to attach custom meta or point at parents other than the current heads.

make-ashlar takes the function as its first positional argument and then keyword metadata. #:produces declares the node type the ashlar will emit; #:name is the symbol used in logs, validator output, and error messages.

4.4.3 2. Reading from the DAG🔗ℹ

Use dag-nearest-ancestor to pull the node of a type on the current execution lineage and dag-query-all to pull every node of a type. node-get and node-text are the shape-safe readers:

(define extract-config-name

(make-ashlar

(lambda (dag)

(define cfg  (dag-nearest-ancestor dag 'project-config))

(define name (node-get cfg 'language "unknown"))

(typed-node dag 'config-name

(hasheq 'name name)))

#:produces 'config-name

#:queries '(project-config)

#:name 'extract-config-name))

node-get returns the default when the node is #f (nothing upstream), when the content isn’t a hash, or when the key is missing. For nested paths, node-get* ((node-get* cfg 'deployment 'region)); for plain text output, node-text.

Declare every type you read in #:queries. The validator uses the list to check that some upstream ashlar actually produces each type.

4.4.4 3. Producing a typed node🔗ℹ

Two constructors. typed-node is the ergonomic form — takes the DAG and defaults parents to the current heads:

(typed-node

dag

'my-type

(hasheq 'key "value"))

make-typed-node is the full form — use it when you need custom meta or different parents:

(make-typed-node

(dag-heads dag)

'my-type

(hasheq 'key "value")

(hasheq 'tag "extra"))

Use hasheq rather than hash for content. Symbol keys are faster to look up, match the convention every other ashlar follows, and keep node-content reads on one discipline.

4.4.5 4. Handling failure🔗ℹ

When an ashlar can’t complete its job, return a failure node instead of a typed one. make-failure-node builds it:

(define check-file-exists

(make-ashlar

(lambda (dag)

(define cfg  (dag-nearest-ancestor dag 'config))

(define path (node-get cfg 'file-path))

(cond

[(and path (file-exists? path))

(typed-node dag 'file-ok

(hasheq 'path path))]

[else

(make-failure-node (dag-heads dag) 'file-missing

(format "required file not found: ~a" path))]))

#:produces 'file-ok

#:queries '(config)

#:name 'check-file-exists))

A failure node stops ~> immediately and exits an ashlar-loop. stone/logging auto-emits an 'error-level event with the failure kind and reason — see Observability. For recovery patterns see Handle failures in a pipeline.

4.4.6 5. Side effects are fine🔗ℹ

A custom ashlar can write files, call subprocesses, or hit external APIs. The framework doesn’t try to make ashlars pure. Just make sure the returned node describes the result of the side effect so downstream ashlars can find it:

(define (make-write-file project-root)

(make-ashlar

(lambda (dag)

(define spec     (dag-nearest-ancestor dag 'file-spec))

(define content  (node-get spec 'body))

(define rel-path (node-get spec 'path))

(define abs-path (build-path project-root rel-path))

(display-to-file content abs-path #:exists 'replace)

(typed-node dag 'file-written

(hasheq 'path (path->string abs-path))))

#:produces 'file-written

#:queries '(file-spec)

#:name 'write-file))

Parameterize factories like this one by accepting construction-time configuration — here, project-root — and returning the ashlar. The ashlar’s function closes over the config.

4.4.7 6. Choosing the right constructor🔗ℹ

• make-ashlar — deterministic work, side effects, any (DAG -> node) logic. This guide.

• make-agent-ashlar — an LLM ashlar with optional middleware, tools, and multi-turn loops. Use for any work that involves an LLM call, whether it’s a single prompt-and-response or a multi-turn agent.

If your work fits make-agent-ashlar, use it — it handles retries, schema parsing, lifecycle events, and conversation attachment for you. Reach for make-ashlar only when the work doesn’t involve an LLM call.

4.4.8 7. Declaring metadata correctly🔗ℹ

A checklist:

• #:produces type — the symbol of the node type you will emit. Required for downstream validation.

• #:queries '(type1 type2 ...) — every type the function reads. The validator checks these against upstream producers before the pipeline runs.

• #:name 'ashlar-name — a symbol used in logs and error messages. Defaults to #:produces when omitted. Set it explicitly for readable traces.

4.4.9 Troubleshooting🔗ℹ

• Ashlar compiles but validate-pipeline reports 'missing-producer. You queried a type that nothing upstream produces. Fix the query name, add a producer, or restructure the topology.

• Ashlar runs but downstream ashlars can’t find its output. Check #:produces. If the declared type doesn’t match what downstream ashlars query for, the emitted node is invisible to them.

• Side effect fires but the pipeline claims failure. You returned a failure node after doing the side effect. Either check preconditions before the side effect and fail early, or return a success node that describes what the side effect did.

• Ashlar function crashes with an unhandled exception. The framework doesn’t catch exceptions — they propagate up and abort the pipeline. Wrap risky calls in with-handlers and return a failure node from the handler.

4.4.10 See also🔗ℹ

• Ashlars — the conceptual model.

• The DAG as Pipeline State — typed nodes and queries.

• Handle failures in a pipeline — recovery patterns.

• Validate a topology — catching broken couplings before the pipeline runs.

4.5.1 Prerequisites🔗ℹ

• A pipeline with a classifier ashlar that emits a typed node (for example, 'classification) and one or more intermediate ashlars between the classifier and the routing decision.

• Comfort building ashlars with make-ashlar and composing with ~>. See Write a custom ashlar if either is new.

4.5.2 1. Use a procedure extractor, not a lens🔗ℹ

A lens? extractor is applied to the latest head’s content, which is whatever the immediately preceding ashlar produced — not your classifier’s output. To reach an earlier node, pass a procedure instead. The procedure receives the work DAG and is free to walk anywhere in it.

4.5.3 2. Walk to the classifier’s node🔗ℹ

Inside the extractor, call dag-nearest-ancestor with the classifier’s #:produces type. The walk follows the first-parent line back from the latest head until it finds a node of that type.

4.5.4 3. Project the routing key with node-get🔗ℹ

Pull the field you want to branch on out of the classifier’s node with node-get (or the accessor your classification uses). Return that value from the extractor — ashlar-match runs the branch whose val equals it.

(~> classify-request   ; produces 'classification {kind: ...}

gather-context     ; produces 'context; this is the head at match time

(ashlar-match

(lambda (d)

(node-get (dag-nearest-ancestor d 'classification) 'kind))

["support" support-flow]

["billing" billing-flow]))

4.5.5 Troubleshooting🔗ℹ

• The match returns a 'match-failed failure node. Confirm the type passed to dag-nearest-ancestor matches the classifier’s #:produces symbol exactly, and that the classifier actually ran before the match (its output must be reachable on the first-parent line from the current head).

• The extractor returns #f because the ancestor wasn’t found. dag-nearest-ancestor returns #f when no node of the requested type exists on the first-parent line, and node-get called on #f returns #f. Add an explicit #f branch, or guard the walk before projecting, rather than relying on the default 'match-failed error.

• The wrong branch fires after a loop or fan-out. dag-nearest-ancestor walks the first-parent line, so an intermediate composite that rewrote the head can shift which 'classification node it finds. If a loop or fan-out sits between the classifier and the match, sanity-check the walk by printing the ancestor’s content in the extractor.

4.5.6 See also🔗ℹ

• stone/edge — the full ashlar-match signature.

• Edge Primitives — why the extractor is shaped this way.

• stone/dag — dag-nearest-ancestor and node-get.

4.6.1 Prerequisites🔗ℹ

• A working LLM ashlar. If you don’t have one, work through Getting Started first.

• An LLM provider that supports JSON schema response format. Most OpenAI-compatible endpoints do, and Anthropic’s Messages API does through the caller shim.

If you’re running on vLLM and also need tools, the ashlar-pair pattern applies — a single agent can’t combine schema enforcement with tool calls on that provider. See The ashlar-pair pattern.

4.6.2 1. Define a schema🔗ℹ

Use make-json-schema (re-exported from stone):

(require stone)

(define project-config-schema

(make-json-schema "project_config"

(hasheq 'language       (hasheq 'type "string"

'description "Programming language")

'test_framework (hasheq 'type "string")

'impl_paths     (hasheq 'type "array"

'items (hasheq 'type "string"))

'test_paths     (hasheq 'type "array"

'items (hasheq 'type "string")))

'("language" "test_framework")))

Three arguments: a name (surfaced to the provider), a hasheq mapping field names to property specs (standard JSON Schema vocabulary), and a list of required field names.

make-json-schema wraps your properties in the full response-format envelope (type: "json_schema", strict: #t, additionalProperties: #f) and returns a hash you can pass straight to #:response-format.

4.6.3 2. Set #:response-format on the ashlar🔗ℹ

(require stone stone/llm-ashlar)

(define propose-config

(make-agent-ashlar caller

#:produces 'project-config

#:queries '(requirement)

#:max-turns 1

#:middleware '()

#:response-format project-config-schema

#:system (lambda (dag)

"You propose TDD project configs from a feature description. Return JSON matching the project_config schema.")

#:user (lambda (dag)

(node-get (dag-nearest-ancestor dag 'requirement) 'text ""))

#:name 'propose-config))

When the ashlar runs it forwards the response format to the caller, which forwards it to the API. On return, the ashlar parses the response text as JSON and produces a typed node whose content is the parsed hash. Your system prompt should still mention that JSON is expected; the schema constrains the shape, but telling the model what it’s looking at helps.

4.6.4 3. Read the structured output downstream🔗ℹ

(define use-config

(make-ashlar

(lambda (dag)

(define cfg       (dag-nearest-ancestor dag 'project-config))

(define language  (node-get cfg 'language))

(define framework (node-get cfg 'test_framework))

(typed-node dag 'setup-plan

(hasheq 'summary (format "~a project using ~a" language framework))))

#:produces 'setup-plan

#:queries '(project-config)

#:name 'use-config))

The parsed content is a Racket hash with symbol keys — JSON objects become hasheq values during parsing. Use (node-get cfg 'language) with a symbol, not a string.

4.6.5 4. Handle parse failures🔗ℹ

If the LLM’s response can’t be parsed as JSON, or is empty, the ashlar doesn’t raise. It produces a failure node instead. The failure node’s kind is 'llm-parse-failed.

This matters because downstream ashlars that expect a 'project-config won’t see one — a ~> sequence stops on the first failure. To recover, wrap the ashlar in a ashlar-loop:

(define discover-config

(ashlar-loop propose-config

#:until has-project-config?

#:max 3))

Where has-project-config? checks both the node type and the content shape:

(define (has-project-config? node)

(and (equal? (node-type node) 'project-config)

(hash? (node-content node))

(hash-has-key? (node-content node) 'language)))

The predicate short-circuits on failure nodes (whose type is 'failure, not 'project-config) and the loop retries.

4.6.6 5. Fold a human step into the body when retries aren’t enough🔗ℹ

If the LLM keeps failing to produce valid JSON, or the predicate keeps rejecting it, blind retries don’t help. Add a human-in-the- loop step as a sibling inside the body so it runs between iterations:

(define discover-config

(ashlar-loop

(~> propose-config

(ashlar-match (lens 'needs-help?)

[#t ask-for-config-details]

[#f noop]))

#:until has-project-config?

#:max 5))

The match runs the ask only when the proposal couldn’t satisfy the schema on its own. See Add human interaction to a pipeline for the ask-human wiring and Edge Primitives for the body-fold pattern.

4.6.7 6. Auto-derived schema metadata🔗ℹ

When you pass #:response-format, the ashlar-meta’s schema field is auto-populated from the JSON schema. This means validate-pipeline can check downstream lens accesses against the schema without you declaring #:schema separately.

A ashlar-match using (lens 'language) to branch on the config validates against the project_config schema’s language field. If you rename the field in the schema but forget to update the lens, validate-pipeline catches the mismatch before a single LLM call runs.

4.6.8 7. Dispatching to different node shapes with #:finalize🔗ℹ

When the parsed JSON needs to dispatch between different node types — a pass produces one kind of node, a reject produces a failure node with structured feedback — reach for #:finalize. The hook receives the parsed content and returns either a typed node or a make-failure-node:

(define verdict-schema

(make-json-schema "verdict"

(hasheq 'ok     (hasheq 'type "boolean")

'reason (hasheq 'type "string"))

'("ok" "reason")))

(define review-implementation

(make-agent-ashlar caller

#:produces 'review-passed

#:response-format verdict-schema

#:max-turns 1

#:middleware '()

#:finalize

(lambda (parsed)

(if (hash-ref parsed 'ok #f)

(make-typed-node '() 'review-passed parsed)

(make-failure-node '() 'review-rejected

(hash-ref parsed 'reason "no reason given"))))

#:system (lambda (dag) "Review the implementation…")

#:user (lambda (dag) "")))

Without #:finalize, the parsed content would always become a 'review-passed node — even when ok was #f. With it, the reject path produces a failure node that downstream ~> recognizes and propagates. See Agents and Tools for the full #:finalize contract including conversation injection behavior.

4.6.9 Troubleshooting🔗ℹ

• Stone produces 'llm-parse-failed. The LLM response was empty or not valid JSON. Check that your provider supports response_format: json_schema. Check that the system prompt clearly asks for JSON. Wrap in a ashlar-loop to retry.

• hash-ref fails downstream. The parsed content is a hash with symbol keys, not string keys.

• Schema works locally but fails against a different provider. Different providers have slightly different JSON-schema support. If switching, test end to end — the contract sits between your caller and the remote API.

• Agent ashlar never emits a final answer with tools attached. On vLLM, schema + tools usually fails — see The ashlar-pair pattern. On Anthropic, ensure #:decide halts once the tool phase is done.

4.6.10 See also🔗ℹ

• Ashlars — the single atomic unit.

• Validation — static lens checking.

• Agents and Tools — the full story on #:finalize, #:adversary, and #:heal-with.

• The ashlar-pair pattern — when schema + tools don’t combine and how to split them.

4.7.1 Prerequisites🔗ℹ

• A working pipeline. If you don’t have one, work through Getting Started first.

• Basic understanding of Racket channels (make-channel, channel-get, channel-put).

4.7.2 1. Add an ask-human ashlar🔗ℹ

make-ask-human takes a channel bundle plus four keyword arguments: a formatter that builds the question, a #:name, a #:produces symbol for the answer node, and an optional #:queries list of node types the formatter reads. Building the channel inside call-with-collected-ask-human-channels auto-registers it.

(require stone stone/tools)

(define approve-channels

(make-ask-human-channel 'ask-approve

(make-channel)    ; out

(make-channel)    ; in

(make-channel)))  ; cancel

(define ask-approve

(make-ask-human approve-channels

#:format-fn (lambda (dag)

(define proposal (dag-nearest-ancestor dag 'proposal))

(format "Approve proposal: ~a? (yes/no)"

(node-get proposal 'summary)))

#:name 'ask-approve

#:produces 'human-response

#:queries '(proposal)))

At run time the ashlar calls the formatter, pushes the resulting string onto the out channel, blocks on the in channel for an answer, and produces a typed node whose content is (hasheq 'response answer-string). Downstream ashlars and predicates read the answer with (node-get node 'response).

4.7.3 2. Wire a stdin frontend🔗ℹ

A frontend is a long-lived thread that receives the pipeline’s list of channels, syncs on all their out channels, prompts the user, and writes the answer back to the matching in channel. The pipeline builder hands the list over — the frontend doesn’t need to know what ashlars exist.

Build the pipeline inside call-with-collected-ask-human-channels:

(require racket/list stone stone/tools)

(define-values (my-pipeline channels)

(call-with-collected-ask-human-channels

(lambda ()

(define ch (make-ask-human-channel 'ask-approve

(make-channel)

(make-channel)

(make-channel)))

(define ask-approve (make-ask-human ch ...))

(~> propose verify ask-approve))))

Nested call-with-collected-ask-human-channels calls auto-bubble: channels built anywhere inside the outermost call land in its returned list regardless of nesting depth. Same-name collisions raise at construction time.

Start the frontend with the collected list:

(define (start-stdin-frontend! channels)

(thread

(lambda ()

(let loop ()

(define ask-evts

(map (lambda (ch)

(handle-evt (ask-human-channel-out ch)

(lambda (question)

(list question

(ask-human-channel-in ch)

(ask-human-channel-cancel ch)))))

channels))

(define result (apply sync ask-evts))

(define question (first result))

(define in-ch     (second result))

(define cancel-ch (third result))

(displayln (format "\n? ~a" question))

(display "> ")

(flush-output)

(define answer (read-line (current-input-port)))

(cond

[(eof-object? answer) (channel-put cancel-ch 'eof)]

[else (channel-put in-ch answer) (loop)])))))

(start-stdin-frontend! channels)

(define-values (result final-dag)

(run-pipeline my-pipeline (make-dag)))

The frontend syncs on all out channels simultaneously. When any one fires, the handle-evt wrapper tells the loop which in channel to reply on.

4.7.4 3. Use an approval loop pattern🔗ℹ

Approval loops ask the human to confirm a result. The ask-human ashlar lives inside the body because the iteration isn’t done until the human has weighed in:

(define approve-or-retry

(ashlar-loop (~> propose verify ask-approve)

#:until approved?

#:max 5))

Where propose drafts a change, verify runs static checks, ask-approve asks the human, and approved? inspects the response:

(define (approved? node)

(and (equal? (node-type node) 'human-response)

(regexp-match? #rx"(?i:^(y|yes|ok|approve))"

(node-get node 'response ""))))

On rejection the whole body runs again. This is the shape you want whenever the predicate can’t be satisfied without the human.

4.7.5 4. Use a learning loop pattern🔗ℹ

Learning loops ask the human only when the body couldn’t figure something out on its own. Fold a ashlar-match into the body so the ask only runs on the unhappy path:

(define discover-config

(ashlar-loop

(~> discover

(ashlar-match (lens 'needs-help?)

[#t ask-for-language]

[#f noop]))

#:until has-project-config?

#:max 5))

discover tries to produce a project config from whatever is already in the DAG and sets 'needs-help? based on whether required fields are present. The ashlar-match fires ask-for-language on missing fields or noop on a clean pass. Iteration N+1’s discover sees the answer landed by iteration N’s ask.

4.7.6 5. Branch on a human response🔗ℹ

For routing decisions, use ashlar-match with a lens extractor:

(define after-approval

(ashlar-match (lens 'response)

["yes" proceed-ashlar]

["no"  cancel-ashlar]))

Cases match exactly, so normalize the response upstream if you want to handle "y", "yes", "Y", and "ok" the same way — a small make-ashlar that rewrites the response into a canonical form, placed between the ask-human ashlar and the match, is the usual shape.

4.7.7 6. Cancel a pending question🔗ℹ

A frontend can cancel a pending question by putting anything on the cancel channel:

(channel-put (ask-human-channel-cancel ch) 'cancelled)

The ask-human ashlar’s sync unblocks on the cancel branch and produces a node with an empty response string. Downstream predicates that check for an affirmation return false; code that needs to distinguish "cancelled" from "said no" can compare the response to "".

4.7.8 7. Test with a scripted frontend🔗ℹ

For unit tests, skip the stdin frontend and feed answers directly into the channels from a scripted thread. Start the thread before run-pipeline so the first question has a consumer waiting:

(require rackunit)

(test-case "pipeline handles rejection then approval"

(define ch

(make-ask-human-channel 'test

(make-channel) (make-channel) (make-channel)))

(define ask (make-ask-human ch

#:format-fn (lambda (dag) "approve?")

#:name 'ask-approve

#:produces 'human-response))

(thread

(lambda ()

(channel-get (ask-human-channel-out ch))

(channel-put (ask-human-channel-in ch) "no")

(channel-get (ask-human-channel-out ch))

(channel-put (ask-human-channel-in ch) "yes")))

(define-values (result dag)

(run-pipeline my-pipeline (make-dag)))

(check-true (approved? result)))

4.7.9 Troubleshooting🔗ℹ

• Frontend hangs at startup. (apply sync '()) blocks forever. If the pipeline has no ask-human ashlars the collected channels list is '(); either skip starting the frontend when the list is empty, or guard the sync.

• Question is printed but no ashlar sees the answer. The frontend is writing to the wrong channel. ask-human-channel fields are (name out in cancel) in that order. The ashlar reads from in; the frontend must channel-put on in, not out.

• Tests block on human input. The scripted frontend thread wasn’t started before run-pipeline.

• Multiple ask-human ashlars in the same pipeline. Each ashlar gets its own channel and registers separately. The stdin frontend syncs on all of them at once — whichever fires first is routed to stdin and the others keep waiting.

4.7.10 See also🔗ℹ

• Ask Human — why human interaction is an ashlar.

• Edge Primitives — the body-fold pattern.

• Your First Orchestration — end-to-end tutorial.

• Use the TUI (below) — a ready-made frontend.

4.8.1 Prerequisites🔗ℹ

• A working pipeline. If you don’t have one, work through Getting Started first.

• Comfort building ashlars with make-ashlar. See Write a custom ashlar if that’s new.

4.8.2 1. Return a failure node from your ashlar🔗ℹ

When an ashlar can’t complete its job, build a failure node with make-failure-node instead of a typed one. The signature is (make-failure-node parents kind reason [meta]): kind is a symbol naming the class of failure, reason is a human-readable message, and the optional meta is a hash of extra context.

(require stone)

(define check-file-exists

(make-ashlar

(lambda (dag)

(define cfg  (dag-nearest-ancestor dag 'config))

(define path (node-get cfg 'file-path))

(cond

[(and path (file-exists? path))

(typed-node dag 'file-ok (hasheq 'path path))]

[else

(make-failure-node (dag-heads dag) 'file-missing

(format "required file not found: ~a" path))]))

#:produces 'file-ok

#:queries '(config)

#:name 'check-file-exists))

You don’t need to log the failure yourself. stone/logging installs a hook on failure-log-handler that make-failure-node fires on every call — every failure node becomes an 'error-level event in the trace automatically.

One subtlety: make-ashlar’s wrapper appends successful nodes to the DAG but leaves the DAG unchanged when the function returns a failure. The failure node is a value in flight — it propagates through the composition primitives but doesn’t land in the DAG itself.

4.8.3 2. Understand what propagates when🔗ℹ

Each composition primitive has its own rule:

• ~> (sequence) — stops at the first failure and returns it. Subsequent ashlars in the chain are skipped.

• ashlar-loop — a body failure exits immediately with that failure. A predicate never satisfied within #:max exits with a fresh 'loop-exhausted failure.

• ashlar-match — no head node or no matching branch produces its own 'match-failed failure. A branch that itself returns a failure propagates through unchanged.

• ashlar-map / ashlar-parallel — failing lanes are dropped from the DAG append step. The composite’s returned node is the last lane’s output; if that’s a failure, the composite reports it even though earlier successful lanes did land in the DAG. ashlar-map with an empty item list produces 'map-empty; ashlar-parallel with no lanes produces 'parallel-empty.

A failure at any depth propagates outward without exceptions. Every primitive above the failure gets a chance to recognize it, branch on it, or wrap it.

4.8.4 3. Check for failure at the top level🔗ℹ

run-pipeline always returns (values result dag). Check with failure-node? before trusting it:

(define-values (result final-dag)

(run-pipeline my-pipeline (make-dag)))

(cond

[(failure-node? result)

(displayln (format "Pipeline failed: ~a — ~a"

(node-get result 'kind)

(node-get result 'reason)))

(exit 1)]

[else

(displayln "Pipeline completed.")

(displayln (node-content result))])

The failure node’s content is a hasheq with 'kind (a symbol like 'llm-parse-failed) and 'reason (a string). The final-dag is the partial result — inspect it with dag-nodes if you need to see what landed before the failure.

4.8.5 4. Retry with ashlar-loop🔗ℹ

If an ashlar is flaky — an LLM reply that sometimes needs another pass, a predicate that needs more information — wrap it in a ashlar-loop:

(define retry-3x

(ashlar-loop propose-config

#:until has-required-fields?

#:max 3))

Critical: this retries only when the body succeeded but the predicate said no. If the body returns a failure, the loop exits with it immediately. For retrying on body failure, see section 6.

4.8.6 5. Recover by folding repair into the loop body🔗ℹ

When an ashlar needs external help between attempts — usually human input, sometimes a cleanup step — fold the repair work into the loop body as a sibling ashlar. A simple sequence runs the repair every pass; a ashlar-match inside the body runs it only when the try actually failed.

; Always run the repair step (safe when it's cheap and idempotent)

(define discover-config

(ashlar-loop (~> propose-config ask-for-missing-fields)

#:until has-required-fields?

#:max 5))

; Run the repair only when the body's output is incomplete

(define discover-config

(ashlar-loop

(~> propose-config

(ashlar-match (lens 'complete?)

[#t noop]

[#f ask-for-missing-fields]))

#:until has-required-fields?

#:max 5))

The match-inside-body shape is the one to reach for when the repair has costs you only want to pay when you have to — asking a human a needless question, hitting a paid API, or firing a side effect that makes no sense on the happy path.

Iteration N+1’s body sees every node iteration N produced, so propose-config on the next pass has strictly more information to work with.

For conversation-level healing — where an LLM ashlar’s draft is rejected and the model needs feedback folded into its next turn — see make-agent-ashlar’s #:adversary and #:heal-with pair in Agents and Tools.

4.8.7 6. Retry on body failure, not just predicate miss🔗ℹ

Sometimes you want to retry when the body itself fails — e.g., an LLM call that returned an unparseable response. ashlar-loop exits on body failure by default. The workaround is to reify the failure into data so the body always returns a typed node and the predicate inspects the content:

(define propose-with-retry

(make-ashlar

(lambda (dag)

(define-values (result dag) (propose-config dag))

(cond

[(failure-node? result)

(typed-node dag 'proposal-attempt

(hasheq 'ok #f

'reason (node-get result 'reason)))]

[else

(typed-node dag 'proposal-attempt

(hasheq 'ok #t

'result (node-content result)))]))

#:produces 'proposal-attempt

#:name 'propose-with-retry))

(define retry-loop

(ashlar-loop propose-with-retry

#:until (lambda (node) (node-get node 'ok))

#:max 5))

The wrapping ashlar catches the failure and turns it into a 'proposal-attempt node tagged ok: #f. The loop sees a successful body, runs the predicate, finds ok #f, and iterates. Use this when the failure is expected, recoverable by retry alone, and worth retrying a bounded number of times.

4.8.8 7. Read failure events from the trace🔗ℹ

Because make-failure-node auto-logs, every failure emits an 'error-level event. Filter the trace file:

Narrow by kind — the event field is the failure kind itself, not a generic 'failure:

Every failure event carries trace-id, span-id, and parent-span-id from the enclosing ashlar. See Debug a pipeline for the full vocabulary.

4.8.9 8. Fail fast vs recover🔗ℹ

Fail fast. Every ashlar returns a failure when it can’t do its work, nothing catches anything, and the top-level caller prints the kind and reason and exits non-zero. Good for simple pipelines, tests, and one-off scripts.

Recover. Risky ashlars are wrapped in ashlar-loop with retries, body-level repair, or reified-failure patterns. Good for production pipelines where LLM flakiness or missing context is expected.

Recovery is localized, not global. The usual shape is a fail-fast outer pipeline with recovery islands around the ashlars that need them.

4.8.10 Troubleshooting🔗ℹ

• Pipeline exits with "Pipeline failed" but I can’t find the originating ashlar. Filter the trace with jq ’select(.level == "error")’ — every failure event carries span-id, parent-span-id, and the enclosing ashlar’s name.

• Stone returned a failure but it isn’t in the final DAG. Expected. make-ashlar’s wrapper leaves the DAG unchanged on failure.

• ashlar-loop doesn’t retry when the body fails. Correct by design. For retrying on body failure, use the reified-failure pattern from section 6.

• ashlar-map reports success even though some lanes failed. ashlar-map filters failing lanes out of the appended DAG but returns the last lane’s output. If the last lane happened to succeed, the top-level result looks fine. Use dag-query-all on the final DAG to inspect what landed from each lane.

• 'match-failed with no obvious cause. Either the DAG had no head node or the extractor returned a value that matches no branch. ashlar-match has no default — add explicit branches for every value you expect.

4.8.11 See also🔗ℹ

• Ashlars — failure as a value.

• Edge Primitives — how each primitive propagates failures, and the body-fold pattern.

• Agents and Tools — the adversary + heal-with pattern for conversation-level healing.

• Debug a pipeline — reading the trace.

• Write a custom ashlar — the make-ashlar shape this guide builds on.

4.9.1 Prerequisites🔗ℹ

• Stone installed and a pipeline that needs an LLM call.

• Either an OpenAI-compatible endpoint (vLLM, ollama, OpenAI, Fireworks, Together, etc.) or an Anthropic API key.

4.9.2 1. OpenAI-compatible servers🔗ℹ