Skip to main content

Crate aion_awl

Crate aion_awl 

Source
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§

ActionDecl
One action name(params…) -> Type requirement inside a worker block.
ActionImplementation
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.
ActionRequirement
One effective action requirement: the task queue (worker name), the action, and one effective node requirement — the call-site node override where a call pins one, the action declaration’s node otherwise. An action whose call sites pin distinct nodes yields one row per distinct requirement.
AfterRef
One name in a step’s after dependency list.
AnswerStmt
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 with every).
Binding
A -> name result binding.
CadenceDecl
The every <duration> cadence declaration of a workloop header.
Call
An action or child call with arguments: name(arg: expr, …).
CallStmt
A call statement: name(args…) [-> binding] with an optional indented call-site config override line.
CarryDecl
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.
CheckError
A typechecker diagnostic with a source-correct span.
ChildDecl
A child name(params…) -> Type workflow delegation declaration.
CollectStmt
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.
CombinatorCall
One combinator invocation in a pipe chain.
CommandError
A malformed reference or quote in a declared command.
CommandReference
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}.
CompiledHarness
One worker document’s complete launch declaration.
CompiledWorkerAction
One action’s executable body.
CompiledWorkerDocument
Everything a worker process needs to serve the queue a worker document declares.
CompiledWorkflow
Everything the compile pipeline produces for one workflow document.
ConfigLine
An indented config line: advisory, node <name>, timeout <duration>, retry …, fallback q1, q2.
ConfigValue
A named config value (the node selector).
ConfirmsDecl
The confirms <route> clause of an invariant block.
ConstDecl
One document-level const name = <value> declaration. The value is restricted to compile-time forms — literals (including raw strings and json { … } bodies), schema of Type, list literals of these, + concatenations of these, and references to other consts — and is folded before lowering.
ContractBundle
Every contract-committed schema of one document, derived in one pass from one schema source.
DetachedDecl
A detached <name>(<params…>) declaration: the start contract of a workflow this document may hatch (R13.1). Mirrors child — 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.
DistributeStmt
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 a collect step 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 Schema descriptions 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.
DurationLiteral
Duration literal made from an integer magnitude and a unit suffix.
EmitError
An error produced while lowering a parsed AWL document to Gleam.
EmittedArtifact
Complete product of emission: source plus every package entry it implements.
EnumVariant
One bare variant of a payload-less enum.
FallbackSpec
An ordered fallback q1, q2, … chain on an action config line.
FieldDecl
One field inside a shorthand record type.
ForkStmt
A fork … join statement.
HarnessDecl
The harness section declared inside one worker block.
HarnessInteger
A whole-number value (concurrency 4).
HarnessSetting
One setting line inside the section, with the trivia that surrounds it.
HarnessText
A quoted string value (command "/usr/local/bin/claude-code-acp").
HarnessWord
A bare word value (kind acp).
HatchKey
The key <expr> clause of a hatch statement.
HatchStmt
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 declared detached contract; unlike spawn, the started run is not a child — no lifecycle tie, no awaitable handle.
InputDecl
One input name: Type declaration in the workflow header.
InvariantDecl
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.
JoinLine
The join line closing a fork block.
LexError
A lexer diagnostic with a source span.
LoopStmt
A loop <name> = <seed> [counting <name>] statement.
LoopTail
The until or max tail line of a loop.
MaxVisits
A max <bound> visits step attribute: the ceiling on how many times the step may run in one workflow execution. Inside the step’s outcome guards the builtin visits (an Int, 1-based) reads the current visit count.
OnFailure
An on failure compensation block.
OutcomeClause
One outcome name: <guard>, route <target> clause of a step.
OutcomeDecl
One outcome name: type T, route success|failure header declaration.
ParamDecl
One typed parameter of an action or child declaration.
ParseError
A lexical or syntactic error encountered while parsing an AWL source document.
PipeStmt
A pipe-chain statement.
QueryDecl
One query name: Type declaration 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.
ReportDecl
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 same answer statement a query is; it enters the same table.
RetentionDecl
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).
RetireDecl
The retire block (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.
RouteStmt
A route <target> statement line.
RouteTarget
A route destination: a step, a sibling/parent target, or a workflow outcome with an optional payload.
ScannedCommand
What scanning a declared command found.
SendDecl
One send name: Type declaration in the workflow header: a signal this workflow SENDS to another workflow.
SendStmt
A send <signal>[(<payload>)] to <expr> statement: deliver a declared outbound signal to the workflow the address expression names.
SignalDecl
One signal name: Type declaration in the workflow header.
SleepStmt
A sleep <duration> statement.
Span
A byte and display-position range in the source document.
SpawnStmt
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 step declaration: dependencies, body statements, and outcome clauses.
SubflowDecl
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).
SubflowOutcome
The one outcome name: type T declaration of a subflow. Unlike a workflow outcome it carries no route success|failure direction: the invocation site binds the payload and the enclosing flow routes on.
SynthesizedWorkflowEntry
One synthesized workflow entry implemented by the emitted Gleam module.
Token
One lexical token with its source span.
TypeDecl
A type declaration through any of the three doors, or an enum.
Utf16Position
A zero-based position in a document, measured the way editors measure: line counts \n-separated lines, character counts UTF-16 code units from the start of that line.
Utf16Range
A half-open range between two Utf16Positions (start inclusive, end exclusive), the shape LSP ranges and editor decorations share.
WaitStmt
A wait <signal> [timeout D] -> name statement.
WorkerDecl
A worker block: the task queue and the actions required on it.
WorkflowTimeoutDecl
One timeout <duration> declaration in the workflow header.

Enums§

ActionBody
The declarative implementation of an action, written under its declaration.
BinaryOp
Binary operator supported by expressions.
CombinatorKind
The fixed combinator vocabulary (deterministic, VM-executed).
CommandCapture
What a runs command body’s result is.
CompileError
A compile failure at any pipeline stage, carrying the existing diagnostics losslessly.
CompiledActionBody
A compiled declarative action body: what a runtime needs to execute the action with no source document in hand.
CompiledHarnessKind
The per-kind half of a launch: what is true of an ACP agent and not of a Norn one, and the reverse.
CompiledWorkerBody
The two forms an action’s executable body takes.
CwdSource
Where a launch takes each attempt’s working directory from.
DeliveryVerb
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.
DocumentFamily
Which family a .awl document belongs to.
DurationUnit
A duration unit suffix.
Expr
Expression tree used in guards, arguments, seeds, bounds, and pipes.
ForkHeader
The header form of a fork block.
Guard
Guard of an outcome clause.
HarnessConfigError
A harness section that passed the checker and could still not be turned into a launch.
HarnessPathForm
Which of the two accepted forms a harness path setting is written in.
HarnessPathRefusal
Why a harness path setting is neither accepted form.
HarnessPermission
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.
PipeStage
One stage of a pipe chain.
PredicateKind
Postfix is … predicate kind.
Quantifier
Boolean collection predicate selected by a collection pipeline.
RetrySpec
Retry policy on an action config line.
RouteDirection
Engine terminal status a workflow outcome maps to.
RoutePayload
The payload an outcome route carries.
RunCapture
What a run body’s result is, and therefore what the action’s declared return type has to be.
SchemaError
Failure to derive a JSON Schema from an AWL contract.
SchemaSources
Where the bytes of a schema("path") import come from.
Statement
One statement in a step, fork, loop, or on failure body.
TokenKind
AWL rev-2 token kinds.
ToleranceDecl
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.
TypeBody
Body of a type declaration.
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 answer statement, positionally.
ARTIFACT_WORD
The word that opens an artifact declaration, 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 confirms as a record field, an action parameter, and a collect binding (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 acp harness kind, as kind spells it.
HARNESS_KIND_FIELD
The field word for the harness kind selector.
HARNESS_KIND_NORN
The norn harness kind, as kind spells it.
HARNESS_PERMISSION_ALLOW_ONCE
The permission policy that approves one request, once.
HARNESS_PERMISSION_DENY
The permission policy 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::Json after run.
KEY_WORD
The word carrying a hatch statement’s mandatory dedupe identity, positionally. The corpus binds key as 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 query declaration, positionally.
RECIPE_WORD
The word that opens a recipe declaration, positionally.
REPORT_WORD
The word that opens a workloop’s report header declaration, positionally. The corpus binds report as 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 retire block 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. start is an ordinary English noun authors plausibly bind (and C10’s teaching refusals — route start in a workflow, step start in 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::Text after run.
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 carries unconfirmed as 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 wall declaration, 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 node override 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. Prefer check_in when the document’s directory is known.
check_in
Typecheck a parsed document, resolving schema imports relative to root (the directory containing the .awl file).
compile
Compile .awl source to a CompiledWorkflow, resolving schema imports relative to schema_root (the document’s directory) exactly as the CLI’s emit path does.
compile_harness
The launch worker declares, when it declares one.
compile_worker_document
Compile a worker document: parse → typecheck → contract derivation.
contract_bundle
Derive every contract-committed schema of document from sources.
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_in when the .awl file’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 value is 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.
print
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_in when the .awl file’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 to root (the document’s directory). A single-outcome workflow pins outcome with const; multiple outcomes become oneOf arms 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_in when the .awl file’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_in when the .awl file’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 from required, 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 source to 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.