Expand description
Front end for the AWL workflow language (rev-2 surface).
The .awl document is the source of truth; the canonical workflow model
is its lossless parse. The lexer is hand-written so the parser can rely
on exact token spans, indentation tokens, and AWL’s doc-line data tokens
(//!, ///); the parser and canonical printer are one property:
parse ∘ print = id, print ∘ parse ∘ print = print.
Modules§
- builtins
- The single authority for names owned by AWL or reserved by its backend.
- command
- The command-declaration surface: just-recipe syntax, tokenized once into whole argv elements, with no shell anywhere.
- doc
- Documentation for free from a document’s own prose.
- guide
- The language’s glossary: one sentence per word, and where to read more.
- semantic
- Read-only semantic queries produced by the AWL checker.
Structs§
- Action
Decl - One
action name(params…) -> Typerequirement inside a worker block. - Action
Implementation - One action the document implements itself: the queue it is declared on, the action name, and the declarative body a runtime must execute in place of an out-of-band worker.
- Action
Requirement - One effective action requirement: the task queue (worker name), the
action, and one effective node requirement — the call-site
nodeoverride where a call pins one, the action declaration’snodeotherwise. An action whose call sites pin distinct nodes yields one row per distinct requirement. - After
Ref - One name in a step’s
afterdependency list. - Answer
Stmt - An
answer <query>[(<value>)]statement: register what the named query reports from here on. - Arg
- Named argument inside a call, record construction, or route payload.
- ArmDecl
- One
on <signal>arming declaration of a workloop header: the loop wakes when the named declared signal arrives (R2.4, one construct family withevery). - Binding
- A
-> nameresult binding. - Cadence
Decl - The
every <duration>cadence declaration of a workloop header. - Call
- An action or child call with arguments:
name(arg: expr, …). - Call
Stmt - A call statement:
name(args…) [-> binding]with an optional indented call-site config override line. - Carry
Decl - One
carry <name>: <Type> = <default>declaration: a typed value threaded iteration→iteration. The first generation seeds it from the declared default;route start(<name>: <expr>)rebinds it at the iteration boundary, and a carry not named in the route’s payload crosses unchanged. - Check
Error - A typechecker diagnostic with a source-correct span.
- Child
Decl - A
child name(params…) -> Typeworkflow delegation declaration. - Collect
Stmt - A
collect <binding>[?] -> <name>statement: closes the nearest open per-item region, gathering each instance’s<binding>into<name>. The strict form types[T](any instance failing terminally fails the run); the tolerant?form types[T?], slot per item, in item order. - Combinator
Call - One combinator invocation in a pipe chain.
- Command
Error - A malformed reference or quote in a declared command.
- Command
Reference - One parameter reference found in a declared command.
- Comment
- One
//source comment, normalized to its text: the marker and one leading space are stripped by the lexer; the printer re-renders the comment as// {text}. - Compiled
Harness - One worker document’s complete launch declaration.
- Compiled
Worker Action - One action’s executable body.
- Compiled
Worker Document - Everything a worker process needs to serve the queue a worker document declares.
- Compiled
Workflow - Everything the compile pipeline produces for one workflow document.
- Config
Line - An indented config line:
advisory, node <name>, timeout <duration>, retry …, fallback q1, q2. - Config
Value - A named config value (the
nodeselector). - Confirms
Decl - The
confirms <route>clause of an invariant block. - Const
Decl - One document-level
const name = <value>declaration. The value is restricted to compile-time forms — literals (including raw strings andjson { … }bodies),schema of Type, list literals of these,+concatenations of these, and references to other consts — and is folded before lowering. - Contract
Bundle - Every contract-committed schema of one document, derived in one pass from one schema source.
- Detached
Decl - A
detached <name>(<params…>)declaration: the start contract of a workflow this document mayhatch(R13.1). Mirrorschild— the contract is known at check time — except the lifecycle is NOT tied: a hatched workflow outlives the iteration and owes the hatching document nothing, which is why the declaration carries no result type. A declared result would be a contract nothing can ever consume. - Distribute
Stmt - A
distribute <var> in <collection>/sequence <var> in <collection>statement: opens a per-item region. Everything downstream runs once per item, with<var>bound, until acollectstep merges the track. - DocLine
- One
///doc line attached to a declaration (type, field, action, step) or one//!narration line at the top of the document. Doc lines are data, not trivia: they flow into derived JSON Schemadescriptions and console narration. The text is verbatim after the marker (leading space preserved) so printing round-trips the line byte-for-byte. - Document
- Parsed representation of a complete rev-2 document, of either family.
- Duration
Literal - Duration literal made from an integer magnitude and a unit suffix.
- Emit
Error - An error produced while lowering a parsed AWL document to Gleam.
- Emitted
Artifact - Complete product of emission: source plus every package entry it implements.
- Enum
Variant - One bare variant of a payload-less enum.
- Fallback
Spec - An ordered
fallback q1, q2, …chain on an action config line. - Field
Decl - One field inside a shorthand record type.
- Fork
Stmt - A
fork … joinstatement. - Harness
Decl - The
harnesssection declared inside oneworkerblock. - Harness
Integer - A whole-number value (
concurrency 4). - Harness
Setting - One setting line inside the section, with the trivia that surrounds it.
- Harness
Text - A quoted string value (
command "/usr/local/bin/claude-code-acp"). - Harness
Word - A bare word value (
kind acp). - Hatch
Key - The
key <expr>clause of a hatch statement. - Hatch
Stmt - A
hatch name(args…) key <expr>statement: start a NEW top-level detached workflow that outlives the iteration and owes this document nothing (workloop design brief R13.1). The target is a declareddetachedcontract; unlikespawn, the started run is not a child — no lifecycle tie, no awaitable handle. - Input
Decl - One
input name: Typedeclaration in the workflow header. - Invariant
Decl - One
invariant <name>: type <Type>declaration with its indented block: the header’s primary object (R2.1). The type is the invariant’s current-state record — what a tile, a query, or another workflow reads. - Join
Line - The
joinline closing a fork block. - LexError
- A lexer diagnostic with a source span.
- Loop
Stmt - A
loop <name> = <seed> [counting <name>]statement. - Loop
Tail - The
untilormaxtail line of a loop. - MaxVisits
- A
max <bound> visitsstep attribute: the ceiling on how many times the step may run in one workflow execution. Inside the step’s outcome guards the builtinvisits(anInt, 1-based) reads the current visit count. - OnFailure
- An
on failurecompensation block. - Outcome
Clause - One
outcome name: <guard>, route <target>clause of a step. - Outcome
Decl - One
outcome name: type T, route success|failureheader declaration. - Param
Decl - One typed parameter of an action or child declaration.
- Parse
Error - A lexical or syntactic error encountered while parsing an AWL source document.
- Pipe
Stmt - A pipe-chain statement.
- Query
Decl - One
query name: Typedeclaration in the workflow header: a question an operator may ask a RUNNING instance of this workflow, answered from live in-memory state without appending an event. - Report
Decl - One
report <name>: type <Type>declaration: a standing tile value the iteration re-registers (R7.2 — a dashboard tile, a CLI query, and another workflow’s read are the same question through different doors). A report is registered with the sameanswerstatement a query is; it enters the same table. - Retention
Decl - The
retention <duration>declaration (R8.1): prior generations are retention-bounded on a DECLARED window. Absence is a check error — the estate rule, measured: retention that is not declared is retention that does not happen (census F6). - Retire
Decl - The
retireblock (R2.5, C11): the declared way a workloop stops that is not failure — named at the point of stopping and recorded as an event. REQUIRED on every workloop (Waffles’ O3 ruling): the document carries its whole lifecycle or it does not carry its meaning; the operator CLI retire verb stays the out-of-band override that RECORDS, never the contract. - Route
Stmt - A
route <target>statement line. - Route
Target - A route destination: a step, a sibling/parent target, or a workflow outcome with an optional payload.
- Scanned
Command - What scanning a declared command found.
- Send
Decl - One
send name: Typedeclaration in the workflow header: a signal this workflow SENDS to another workflow. - Send
Stmt - A
send <signal>[(<payload>)] to <expr>statement: deliver a declared outbound signal to the workflow the address expression names. - Signal
Decl - One
signal name: Typedeclaration in the workflow header. - Sleep
Stmt - A
sleep <duration>statement. - Span
- A byte and display-position range in the source document.
- Spawn
Stmt - A
spawn name(args…)statement. A binding parses (so the checker can refuse it with a targeted diagnostic) but is a check error. - Step
- A
stepdeclaration: dependencies, body statements, and outcome clauses. - Subflow
Decl - A
subflow name(params…)declaration: a named flow container with the same anatomy as a workflow — typed inputs (the parameters), exactly one success outcome, and its own steps. Used, it is one step; it compiles inline and captures nothing from the enclosing flow (parameters only). - Subflow
Outcome - The one
outcome name: type Tdeclaration of a subflow. Unlike a workflow outcome it carries noroute success|failuredirection: the invocation site binds the payload and the enclosing flow routes on. - Synthesized
Workflow Entry - One synthesized workflow entry implemented by the emitted Gleam module.
- Token
- One lexical token with its source span.
- Type
Decl - A
typedeclaration through any of the three doors, or an enum. - Utf16
Position - A zero-based position in a document, measured the way editors measure:
linecounts\n-separated lines,charactercounts UTF-16 code units from the start of that line. - Utf16
Range - A half-open range between two
Utf16Positions (startinclusive,endexclusive), the shape LSP ranges and editor decorations share. - Wait
Stmt - A
wait <signal> [timeout D] -> namestatement. - Worker
Decl - A
workerblock: the task queue and the actions required on it. - Workflow
Timeout Decl - One
timeout <duration>declaration in the workflow header.
Enums§
- Action
Body - The declarative implementation of an action, written under its declaration.
- Binary
Op - Binary operator supported by expressions.
- Combinator
Kind - The fixed combinator vocabulary (deterministic, VM-executed).
- Command
Capture - What a
runs commandbody’s result is. - Compile
Error - A compile failure at any pipeline stage, carrying the existing diagnostics losslessly.
- Compiled
Action Body - A compiled declarative action body: what a runtime needs to execute the action with no source document in hand.
- Compiled
Harness Kind - The per-kind half of a launch: what is true of an ACP agent and not of a Norn one, and the reverse.
- Compiled
Worker Body - The two forms an action’s executable body takes.
- CwdSource
- Where a launch takes each attempt’s working directory from.
- Delivery
Verb - Delivery order of a per-item region.
- DocSite
- One position in the grammar where a
///doc line can be written, with the language’s verdict on it. - DocVerdict
- Whether a
///doc line attaches at a given site. - Document
Family - Which family a
.awldocument belongs to. - Duration
Unit - A duration unit suffix.
- Expr
- Expression tree used in guards, arguments, seeds, bounds, and pipes.
- Fork
Header - The header form of a
forkblock. - Guard
- Guard of an outcome clause.
- Harness
Config Error - A
harnesssection that passed the checker and could still not be turned into a launch. - Harness
Path Form - Which of the two accepted forms a harness path setting is written in.
- Harness
Path Refusal - Why a harness path setting is neither accepted form.
- Harness
Permission - How an agent worker answers an ACP permission request.
- Keyword
- AWL keyword tokens.
- Lead
- One unit of leading trivia before a printable item, in source order.
- PipeEnd
- How a pipe chain terminates.
- Pipe
Stage - One stage of a pipe chain.
- Predicate
Kind - Postfix
is …predicate kind. - Quantifier
- Boolean collection predicate selected by a collection pipeline.
- Retry
Spec - Retry policy on an action config line.
- Route
Direction - Engine terminal status a workflow outcome maps to.
- Route
Payload - The payload an outcome route carries.
- RunCapture
- What a
runbody’s result is, and therefore what the action’s declared return type has to be. - Schema
Error - Failure to derive a JSON Schema from an AWL contract.
- Schema
Sources - Where the bytes of a
schema("path")import come from. - Statement
- One statement in a step, fork, loop, or
on failurebody. - Token
Kind - AWL rev-2 token kinds.
- Tolerance
Decl - One declared tolerance form of an invariant (R2.3): the engine alarms when tolerance is exceeded — never before, always then. Tolerance has NO default; an invariant without one is a check error.
- Type
Body - Body of a
typedeclaration. - TypeRef
- Type expression used by declarations, fields, and parameters.
Constants§
- ALLOWS_
WORD - The word naming one path pattern a wall admits, positionally.
- ANSWER_
WORD - The word that opens an
answerstatement, positionally. - ARTIFACT_
WORD - The word that opens an
artifactdeclaration, positionally. - CAPTURES_
WORD - The word naming the typed result a recipe step captures, positionally.
- COMMAND_
WORD - The word a
runs command <name>action body references a command declaration with, positionally. (A command DECLARATION opens with no word at all: it is a bare just-recipe header,name params:.) - CONFIRMS_
WORD - The word that names an invariant’s confirming route, positionally. The
corpus carries
confirmsas a record field, an action parameter, and acollectbinding (release_ceremony.awl), so reserving it would break documents that exist. - DERIVES_
WORD - The word naming a re-derive parameter’s source address, positionally.
- DIGEST_
WORD - The word naming a declared artifact’s content digest, positionally.
- EXCLUDES_
WORD - The word naming bytes that must not appear — a wall’s negative vocabulary, an artifact’s unfilled-slot sentinel — positionally.
- EXPECTING_
WORD - The word naming a fired specimen’s known answer, positionally.
- EXPORT_
WORD - The word that opens a document’s
export NAME := "…"environment binding, positionally — just’s own file-level export, absorbed with its spelling. - EXTRACT_
WORD - The word naming what a derivation takes out of its source, positionally.
- FIRES_
WORD - The word naming the declared artifact a recipe step fires, positionally.
- FOR_
WORD - The connective of the tolerance duration form, positionally: it stands in
exactly one grammar position (
unconfirmed for <duration>), and reserving a word that common for one slot would be occupancy the corpus never demanded. - HARNESS_
ARGS_ FIELD - The field word for the extra arguments passed to the launched agent.
- HARNESS_
BINARY_ FIELD - The field word for the Norn binary location.
- HARNESS_
COMMAND_ FIELD - The field word for the ACP agent executable.
- HARNESS_
CONCURRENCY_ FIELD - The field word for the maximum activities served at once.
- HARNESS_
CWD_ FIELD - The field word for the agent’s working directory.
- HARNESS_
ENV_ PASS_ FIELD - The field word for the environment pass-through allow-list.
- HARNESS_
EXIT_ GRACE_ FIELD - The field word for the ACP shutdown grace.
- HARNESS_
FIELDS - Every field word the section admits, in canonical print order.
- HARNESS_
KIND_ ACP - The
acpharness kind, askindspells it. - HARNESS_
KIND_ FIELD - The field word for the harness kind selector.
- HARNESS_
KIND_ NORN - The
nornharness kind, askindspells it. - HARNESS_
PERMISSION_ ALLOW_ ONCE - The
permissionpolicy that approves one request, once. - HARNESS_
PERMISSION_ DENY - The
permissionpolicy that refuses every gated action. - HARNESS_
PERMISSION_ FIELD - The field word for the ACP permission policy.
- HARNESS_
RECONNECT_ INITIAL_ BACKOFF_ FIELD - The field word for the delay before the first reconnect attempt.
- HARNESS_
RECONNECT_ MAX_ ATTEMPTS_ FIELD - The field word for the cumulative session-drop budget.
- HARNESS_
RECONNECT_ MAX_ BACKOFF_ FIELD - The field word for the reconnect backoff cap.
- HARNESS_
WORD - The word that opens the section.
- IN_WORD
- The word that separates a per-item region’s binding from its collection, positionally.
- JSON_
CAPTURE_ WORD - The word selecting
RunCapture::Jsonafterrun. - KEY_
WORD - The word carrying a hatch statement’s mandatory dedupe identity,
positionally. The corpus binds
keyas an input and an action parameter (input key: String,refresh(key: key, …)), so reserving it would break documents that exist. - PARAMETER_
WORD - The word declaring one of a recipe’s typed parameters, positionally.
- POSITIONAL_
WORDS - Every word AWL reads as an opener WITHOUT reserving it.
- QUERY_
WORD - The word that opens a
querydeclaration, positionally. - RECIPE_
WORD - The word that opens a
recipedeclaration, positionally. - REPORT_
WORD - The word that opens a workloop’s
reportheader declaration, positionally. The corpus bindsreportas a result name in 35 documents (fetch(url: url) -> report), so reserving it would break documents that exist. - REQUIRES_
WORD - The word naming one at-fire precondition of a recipe step, positionally.
- RESTORES_
WORD - The word naming the path a restore artifact must restore byte-exactly, positionally.
- RETIRE_
ARITY - Arity of
RETIRE_ENTRY. One argument: the loop’s current carry. - RETIRE_
ENTRY - The exported module entry a compiled
retireblock lands on:retire/1. - RUNS_
WORD - The word naming the declared command a recipe step runs, positionally.
- RUN_
WORD - The word that opens a declarative action body, positionally.
- SEND_
WORD - The word that opens a signal
send, positionally. - SET_
WORD - The word that opens the document’s
set working-directory := "…"line, positionally — just’s own file-level setting, absorbed with its spelling. - START_
WORD - The word naming a workloop’s iteration terminal after
route, positionally.startis an ordinary English noun authors plausibly bind (and C10’s teaching refusals —route startin a workflow,step startin a workloop — need the parse to succeed so the checker can name the family), so it is never reserved. - TEXT_
CAPTURE_ WORD - The word selecting
RunCapture::Textafterrun. - TO_WORD
- The word that names a
send’s target workflow, positionally. - UNCONFIRMED_
WORD - The word opening a tolerance’s duration form (
tolerance unconfirmed for <duration>), positionally. The corpus carriesunconfirmedas an outcome-arm name and a route target today (ship_release_combined.awl), so reserving it would break documents that exist. - WALL_
WORD - The word that opens a
walldeclaration, positionally. - WORKSPACE_
ROOT_ PLACEHOLDER - The literal a harness path setting carries where the box’s workspace root belongs.
Traits§
- Spanned
- Provides the source span covered by a parsed syntax node.
Functions§
- action_
requirements - Derive the effective action requirements of a parsed document: for each
declared action, the distinct effective node requirements across its call
sites (a call-site
nodeoverride wins over the action declaration’s), in declaration order then call-site source order. An action with no call sites carries its declared requirement. - byte_
offset_ at_ utf16 - Converts a zero-based UTF-16 position to a byte offset in
source. - check
- Typecheck a parsed document with no document directory: schema imports
(
type X = schema("file")) cannot resolve and are reported as errors. Prefercheck_inwhen the document’s directory is known. - check_
in - Typecheck a parsed document, resolving schema imports relative to
root(the directory containing the.awlfile). - compile
- Compile
.awlsource to aCompiledWorkflow, resolving schema imports relative toschema_root(the document’s directory) exactly as the CLI’s emit path does. - compile_
harness - The launch
workerdeclares, when it declares one. - compile_
worker_ document - Compile a
workerdocument: parse → typecheck → contract derivation. - contract_
bundle - Derive every contract-committed schema of
documentfromsources. - doc_
paragraphs - Join doc lines into documentation prose that KEEPS its paragraphs.
- doc_
text - Join doc lines into description prose: the single leading space the marker convention leaves on each line is stripped, and lines join with one space so multi-line docs read as one paragraph.
- emit
- Emit a complete Gleam workflow module for a parsed AWL document, with
schema imports unresolvable (no document directory). Prefer
emit_inwhen the.awlfile’s directory is known. - emit_
artifact - Emit source together with every synthesized same-package workflow entry.
- emit_
artifact_ in - Emit a structured artifact while resolving schema imports relative to
root. - emit_in
- Emit a complete Gleam workflow module, resolving schema imports relative
to
root(the document’s directory). - expr_
text - Renders one expression in canonical printed form — the same text the canonical printer emits for it. Consumers (projection labels, tooling) use this instead of re-deriving expression surface syntax.
- harness_
path_ form - Which accepted form
valueis written in, or why it is neither. - lex
- Lex an AWL rev-2 source document into tokens.
- parse
- Parse a complete rev-2 AWL document of either family.
- Render a parsed document in the canonical rev-2 format.
- scan_
command - Scan a declared command for its parameter references, its program word, and its canonical spelling.
- schema_
for_ outcomes - Derive the workflow’s outcome envelope, with schema imports unresolvable
(no document directory). Prefer
schema_for_outcomes_inwhen the.awlfile’s directory is known. - schema_
for_ outcomes_ in - Derive the workflow’s outcome envelope — the
{ "outcome": name, "payload": … }object the emitted codec produces — resolving schema imports relative toroot(the document’s directory). A single-outcome workflow pinsoutcomewithconst; multiple outcomes becomeoneOfarms pairing each outcome name with its payload schema. - schema_
for_ params_ in - Derive an object schema over callable parameters, resolving schema imports
relative to
root. - schema_
for_ queries - Derive the workflow’s read-only surface: one object whose properties are
the declared query names and whose values are their answer schemas, with
schema imports unresolvable (no document directory). Prefer
schema_for_queries_inwhen the.awlfile’s directory is known. - schema_
for_ queries_ in - Derive the workflow’s read-only surface — every declared query name paired
with the schema of the answer an operator receives — resolving schema
imports relative to
root(the document’s directory). - schema_
for_ type - Derive the JSON Schema for a named declared type, with schema imports
unresolvable (no document directory). Prefer
schema_for_type_inwhen the.awlfile’s directory is known. - schema_
for_ type_ in - Derive the JSON Schema for a named declared type, resolving schema
imports relative to
root(the document’s directory). - schema_
for_ type_ ref_ in - Derive one callable result or signal payload schema, resolving schema
imports relative to
root. - schema_
for_ workflow - Derive the workflow’s start contract: one object schema over its inputs,
?-typed inputs omitted fromrequired, narration as the description. - schema_
for_ workflow_ in - Derive the workflow’s start contract, resolving schema imports relative
to
root(the document’s directory). - utf16_
position_ at - Converts a byte offset in
sourceto a zero-based UTF-16 position. - utf16_
range_ for_ span - Converts an AWL byte span to a UTF-16 range against the live document text.