4.1.1 Prerequisites🔗ℹ

• An ashlar 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-ashlar 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-ashlar my-ashlar (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 ashlar’s final DAG is still available after run-ashlar 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-ashlar my-ashlar (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-ashlar my-ashlar (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 ashlar.

• 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 ashlar, 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 ashlars that recover from the error events you see here.

4.2.1 Prerequisites🔗ℹ

• A working Stone ashlar — 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 ashlar 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 an ashlar in the how-to section — using a live receiver to watch events during development.

4.3.1 Prerequisites🔗ℹ

• An ashlar: 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-ashlar on a ashlar-meta value:

(require stone/validate)

(define result (validate-ashlar ashlar))

(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-ashlar 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 an ashlar file, loads it via dynamic-require, and runs validate-ashlar on the binding named ashlar:

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

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

(provide ashlar)

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

(define ashlar

(~> 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 ashlar)

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

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

(enumerate-paths ashlar)

; => '((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 ’ashlar’". The CLI calls dynamic-require on the file and looks for a binding named exactly ashlar. Rename your exported topology to ashlar, or add a thin alias (define ashlar my-real-topology) alongside the export.

• Validator passes but the ashlar 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 an ashlar.

• '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 an ashlar — inspecting runtime failures the validator can’t catch.

4.4.1 Prerequisites🔗ℹ

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

• A basic understanding of typed nodes and DAG queries. See The DAG as Ashlar 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 an ashlar.

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 ashlar 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-ashlar 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 ashlar 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 ashlar. 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 Ashlar State — typed nodes and queries.

• Handle failures in an ashlar — recovery patterns.

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

4.5.1 Prerequisites🔗ℹ

• An ashlar 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 (except-in stone context context?)

stone/llm-ashlar stone/context-struct)

(define propose-config

(make-agent-ashlar caller

#:produces 'project-config

#:max-turns 1

#:middleware '()

#:response-format project-config-schema

#:context (context

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

(user 'requirement))

#: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 an ashlar 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-ashlar 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-ashlar 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"))))

#:context (context (system "Review the implementation…"))))

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 ashlar. If you don’t have one, work through Getting Started first.

• Basic understanding of the threshold (make-threshold, threshold-subscribe, threshold-answer!) — see Ask Human.

4.7.2 1. Add an ask-human ashlar🔗ℹ

make-ask-human takes four keyword arguments and no channel: 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.

(require stone stone/threshold stone/record)

(define ask-approve

(make-ask-human

#: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, poses the question through (current-threshold), blocks until a supervisor resolves it, and produces a typed 'human-response node carrying the answer (readable with (node-text node) or (node-get node 'human-response)). A cancelled ask produces a halt node instead — 'declined on a supervisor’s decline, 'user-quit on an unattended quit.

4.7.3 2. Run under a record and wire a supervisor🔗ℹ

An ask-human ashlar solicits through (current-threshold), which is bound only under a durable run. So run it with run-ashlar #:record (or under the TUI, Use the TUI) — a bare (run-ashlar ashlar dag) binds no threshold.

A supervisor is a thread that threshold-subscribes to the run’s crossing feed, watches for an 'ask crossing, and answers it. Attach first so decisions block for the supervisor instead of auto-resolving from the unattended policy:

(require racket/list stone stone/threshold stone/record)

(define th (make-threshold))

(threshold-attach! th)

(define sub (threshold-subscribe th))

(define r   (open-record "session.jsonl" #:threshold th))

(define (start-stdin-supervisor! th sub)

(thread

(lambda ()

(let loop ()

(define c (sync sub))

(when (eq? (crossing-kind c) 'ask)

(define p        (crossing-payload c))

(define id       (hash-ref p 'id))

(define question (hash-ref p 'question))

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

(display "> ")

(flush-output)

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

(cond

[(eof-object? answer) (threshold-cancel! th id 'user-quit)]

[else (threshold-answer! th id answer)]))

(loop)))))

(start-stdin-supervisor! th sub)

(define final-dag (run-ashlar my-ashlar #:record r))

The supervisor subscribes to one feed and sees every crossing the run surfaces — asks, tool-call gates, and token/turn observations. It routes each 'ask back by its 'id; nothing knows what ashlars exist.

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 'human-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 an 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 'human-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. Decline a pending question🔗ℹ

A supervisor can decline a pending question with threshold-cancel! on the ask’s id. The default kind is 'declined, which the ashlar turns into a 'declined halt while the rest of the run keeps going (a ~> sequence short-circuits on the halt):

(threshold-cancel! th id)              ; declined

(threshold-cancel! th id 'user-quit)   ; quit the session

When a decline and a quit should route differently, ashlar-match automatically sends a halt head to the branch keyed by its halt kind ('declined / 'user-quit) — add those keys alongside your normal answer branches.

4.7.8 7. Test with a scripted supervisor🔗ℹ

For unit tests, drive the threshold directly from a scripted thread. Attach, subscribe, and answer the asks as they cross. Start the supervisor before run-ashlar so the first question has a resolver waiting:

(require rackunit)

(test-case "ashlar handles rejection then approval"

(define th (make-threshold))

(threshold-attach! th)

(define sub (threshold-subscribe th))

(define r   (open-record (make-temporary-file "sess-~a.jsonl")

#:threshold th))

(thread

(lambda ()

(define (answer-next text)

(let loop ()

(define c (sync sub))

(if (eq? (crossing-kind c) 'ask)

(threshold-answer! th (hash-ref (crossing-payload c) 'id) text)

(loop))))

(answer-next "no")

(answer-next "yes")))

(define final-dag (run-ashlar my-ashlar #:record r))

(check-true (approved? (dag-latest-head final-dag))))

4.7.9 Troubleshooting🔗ℹ

• Ask hangs forever. The run has no supervisor and the threshold is still attended (threshold-attach!ed) — nobody answers. Either answer from a supervisor thread, or leave the threshold unattended so the ask auto-resolves to a 'user-quit halt from policy.

• Ask never blocks; you get a 'user-quit halt immediately. The threshold is unattended. Call threshold-attach! before running so a supervisor can answer.

• Ask errors under a bare run. (current-threshold) is #f outside run-ashlar #:record / the TUI. Run under a record.

• Tests block on human input. The scripted supervisor thread wasn’t started before run-ashlar, or it isn’t filtering for 'ask crossings (the feed also carries gates and observations).

4.7.10 See also🔗ℹ

• Ask Human — why human interaction is an ashlar.

• Run a durable, resumable session — records, journals, and resume.

• Edge Primitives — the body-fold pattern.

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

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

4.8.1 Record, journal, context — three distinct things🔗ℹ

The durability model rests on keeping three ideas separate:

• The record — what is stored: the DAG plus its durable journal (and the threshold a supervisor observes through). open-record gives you one.

• The journal — the record’s on-disk form: an append-only JSONL log. The DAG is the single source of truth; the journal is its crash-recovery projection. Reconstructing the DAG from the journal is exactly what a resume does.

• The context — what one run sends to the model: bounded, computed fresh each run by projecting the record’s DAG through an agent’s #:context lenses. The record is never the context; the context is a projection of the record. A long session accumulates an unbounded record but sends a bounded context each turn.

Keeping these apart is why a session can run for hours: the record grows, the context stays small (and an agent’s #:compaction ashlar summarizes when a projection would overflow — see stone/llm-ashlar).

4.8.2 1. Open a record🔗ℹ

open-record is the single entry point for both a fresh run and a resume. path is the journal file — the identity of the session on disk.

(require stone stone/record stone/threshold)

(define th (make-threshold))

(define r  (open-record "session.jsonl" #:threshold th))

• Fresh (no file at path) — an empty DAG plus a new journal opened for append.

• Resume (the file exists) — the DAG is rebuilt by replaying the journal, and the same file is reopened for append so new facts extend the log.

The #:threshold defaults to #f; pass a real one for an interactive or supervised run (a batch test may pass one to observe or answer decisions).

4.8.3 2. Run durably🔗ℹ

Pass the record to run-ashlar with #:record. It runs one forward pass, journaling each atomic completion and binding the record’s threshold as (current-threshold):

(define final-dag (run-ashlar ashlar #:record r))

dag and #:record are mutually exclusive — the record supplies the DAG. For an interactive topology, attach a supervisor to the threshold first (see Add human interaction to an ashlar).

4.8.4 3. Resume after a crash🔗ℹ

Resuming is not a special mode — it is the same open-record + run-ashlar over the same path. If the first run crashed (or was quit) partway, the journal holds the completed steps; the second run replays them and continues live from the crash point:

; First run — crashes after some steps are journaled.

(define r1 (open-record "session.jsonl" #:threshold (make-threshold)))

(run-ashlar ashlar #:record r1)   ; ... crash ...

; Later: same path. Completed leaves replay; the rest runs live.

(define r2 (open-record "session.jsonl" #:threshold (make-threshold)))

(run-ashlar ashlar #:record r2)

What replays, precisely:

• Only atomic (leaf) ashlars replay; composites (~>, ashlar-loop, …) always re-walk their children, so a loop’s remaining iterations resume correctly.

• Leaves replay by position in the deterministic walk: the first N leaves (N = the count of recorded atomic completions) skip their bodies — no LLM call, no side effect, no re-journal — and the rest run live. Answered decisions replay their recorded answers; a decision that was posed but never answered is re-posed.

• Topology guard. The journal records a hash of the topology shape — including the context structures. Replaying against edited code fails loudly with topology changed since this session rather than replaying into a mismatched walk.

4.8.5 4. Session loop: run until a terminal halt🔗ℹ

An interactive session doesn’t do one pass — it loops, taking user turns until the user quits. #:loop #t (which requires #:record) folds the topology over the record unbounded until the terminal head is a session-terminal halt — a 'user-quit or 'input-ended halt node (make-ask-human produces the former on an unattended or quit cancel):

(run-ashlar ashlar #:record r #:loop #t)

This is exactly what run-tui runs on its background thread. Only put a topology with a terminal-halt path into #:loop; with none, it never returns.

4.8.6 5. Sessions on the command line🔗ℹ

raco stone manages records for you as sessions under .stone/sessions/<id>.jsonl:

Resuming replays the journal as TUI scrollback (display and crash recovery are the same journal read) and continues the run. See Command-line interface and Use the TUI.

4.8.7 See also🔗ℹ

• Ask Human — the threshold a supervised run answers through.

• Use the TUI — the packaged interactive supervisor.

• Command-line interface — raco stone and its session flags.

• stone/llm-ashlar — #:context / #:compaction, the projection of a record into a bounded context.

4.9.1 Prerequisites🔗ℹ

• A working ashlar. 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.9.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.9.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.9.4 3. Check for failure at the top level🔗ℹ

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

(define-values (result final-dag)

(run-ashlar my-ashlar (make-dag)))

(cond

[(failure-node? result)

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

(node-get result 'kind)

(node-get result 'reason)))

(exit 1)]

[else

(displayln "Ashlar 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.9.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.9.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.9.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))