The code language

The twelve axes

CXPath supports twelve axes. The default axis is `child`, so `name` ≡ `child::name`. The full set:

              [# Common axis idioms                                              #]
           //section//*                              [# all descendants       #]
           //code/ancestor::section                   [# enclosing sections    #]
           //user/following-sibling::user             [# later peer users      #]
           //tr/parent::table                         [# tables containing tr  #]
           //h2/preceding-sibling::*[1]               [# immediate prior sib   #]
           //user[= $_@role 'admin']                  [# only-if-admin filter  #]
           //user/attribute::email                    [# == //user/@email      #]
            

Axis-qualified steps apply to document-anchored paths. From a **binding**, the child / descendant / attribute steps work directly (`$u/name`, `$u//item`, `$u@email`); axis-qualified steps on a binding (`$u/ancestor::…`) are not yet supported — anchor the path at the document and filter instead. See bindings.

Predicates — positional, attribute, function, composite

A predicate is `[...]` after a step. The predicate body is **prefix CX code over the context node `$_`** — plus a small set of atomic shorthands. The admitted shapes:

• **Positional** — `INT` selects the Nth match (1-indexed). `//section[1]` is the first section. Negative positions are NOT supported; `[$_last]` selects the last, `[= $_position N]` the Nth.
• **Attribute test** — `[@name]` (attribute present) and `[@!name]` (attribute absent). Value comparisons are prefix forms: `[= $_@name V]`, `[!= …]`, `[< …]` etc.
• **Step-existence** — a bare child name: `[h2]` keeps elements that have an `h2` child.
• **Prefix expression** — any prefix CX form over `$_`: comparisons (`[= $_@id 42]`), boolean combinators (`[and …]` / `[or …]` / `[not …]`), and function calls (`[$strings:contains $_@email '@example.com']`).

              //user[1]                              [# first user                #]
           //user[= $_@id 42]                     [# attr equality             #]
           //user[@active]                        [# attr present              #]
           //user[$strings:contains $_@email '@example.com']
           //user[and [>= $_@age 18] [= $_@country 'US']]
           //section[h2]                          [# has an h2 child           #]
           //section[and [$count $_/h2] [$count $_/p]]
            

Predicates chain: `//user[= $_@active true][1]` is the first active user — the second predicate filters the result of the first. The order matters.

Comparison — one operator family

**One operator syntax: `= != < <= > >=`.** No keyword synonyms (`eq` / `ne` / `lt` / ...) — they are not in the grammar. Semantics are **value-comparison**: both sides must be single values; a multi-valued operand raises `CXER0103`; no type coercion.

This is the deliberate divergence from XPath 3.1's general-comparison default. In XPath, `//x = 1` is true if *any* `x` equals 1 — a common gotcha when the path silently returns multiple nodes. In CX, the path must return a single value, or the comparison raises. To express "any equals", filter the sequence itself: `[$exists //x[= $_ 1]]`.

              //user[= $_@age 42]              [# single attr → ok             #]
           //section[> [$count $_/p] 3]     [# both sides single → ok       #]
           //user[= $_@email 'ada@example.com']
           [# a multi-valued operand raises — filter the sequence
              instead of comparing it wholesale #]
           [$exists //user/tag[= $_ 'admin']]
            

Paths on bindings

A CXPath rooted at a binding navigates from that value instead of from the document root:

              [# $u/name — direct child · $u/* — all children ·
            $u//item — descendant · $u@active — attribute (shorthand) ·
            $u/@active — attribute (full axis form)                    #]
           [?let [= $u [user active=true region='EU'
                        [name 'Ada'] [item 1] [item 2]]]
             ($u/name, $u/*, $u//item, $u@active, $u/@active)]
            

The path operators that work on bindings are the same operators that work on the implicit document — one vocabulary. The leading `//` form is anchored at the **document root**, regardless of context; `$u//x` is anchored at `$u`. Use `//x` to escape upward when you already have a binding. Axis-qualified steps (`ancestor::` etc.) are document-path syntax and are not yet supported on a binding; map-key access on a map-valued binding uses `[$map:get $m 'key']`.

Where CXPath values are accepted

CXPath is a value kind. Every construct that takes "a selector" accepts a CXPath value:

              [?for [in $u //user[= $_@active true]] [yield [$render $u]]]
           [?if //admin [then [admin-panel]] [else ()]]
           [?match $n [case //prose [p $n]] [else ()]]
           [?let [= $cfg //meta/@config] [$render $cfg]]
           [?modify $doc //user/@status [set 'verified']]
           [$count //user[= $_@active true]]
            

The same path expression — `//user[= $_@active true]` — appears as a `[?for]` generator, as an `[?if]` condition, as a `[?match]` arm, as a `[?let]` initializer, as a `[?modify]` focus, and as a builtin argument. This is the unification CX ratifies: no separate "path syntax" per construct.

**Status note.** CXPath value-kind at non-`[?for]` positions is production-ready in V; full Tier-2 binding parity is tracked in [`spec/v0_8_0_status.md`](../../spec/v0_8_0_status.md) gate 26.4.

Deliberate divergences from XPath 3.1

CXPath is a working subset of XPath 3.1 + deliberate changes. The full alignment table is in [`spec/cxpath_alignment.md`](../../spec/cxpath_alignment.md); the headline differences:

• **One comparison family** (`= != < <= > >=`) — XPath's split into general (`=`) and value (`eq`) is gone; CX uses value-comparison semantics exclusively. Rationale: the general-comparison gotcha is XPath's most-reported source of subtle bugs.
• **Path is a value kind** — XPath paths are syntactic fragments inside XPath expressions only. In CX they are first-class values.
• **1-indexed positions** — adopted from XPath verbatim (`//x[1]` is the first), but CX explicitly rejects `[0]` (raises `CXER0100`); XPath silently yields the empty sequence.
• **No general-purpose `for` / `let` inside paths** — CX moves binding into the `[?for]` / `[?let]` directive surface; predicates take expressions but not binding clauses. Use the surrounding directive.
• **No paren-calls anywhere** — XPath's `count(//user)` spelling does not exist; every call is the head-dispatch form `[$count //user]`, in predicates too (`[> [$count $_/*] 0]`). `position()` / `last()` are the reserved predicate bindings `$_position` / `$_last`.

The full XPath 3.1 alignment table — what is adopted, what is deliberately not, what is on the XPath 4.0 watch list — is in [`spec/cxpath_alignment.md`](../../spec/cxpath_alignment.md).

Element-shape patterns

An element-shape pattern matches an element by name, attributes, and (recursively) body content. The pattern uses ordinary CX syntax with bind-holes where you want to capture values:

              [user email=$e]               [# bind email attribute             #]
           [user @active=true $u]        [# attr filter; bind whole user     #]
           [user @id=42 [name $n]]       [# bind name's body                 #]
           [post author=$a body=$b]      [# bind two attrs                   #]
            

**Binding semantics depend on context.** A pattern `[NAME $x]` **without** attribute predicates auto-unwraps the body — text body binds the string, scalar body binds the scalar, empty body binds the element itself, structured body binds the element. A pattern `[NAME @attr… $x]` **with** attribute predicates always binds `$x` to the matched element. The rationale is in [`spec/code.md`](../../spec/code.md) §5.2 rule 5: when you name attributes you are filtering "what kind of element", so the bind value is the element; when you don't, the bind value is the inner content.

Scalar literal patterns

Scalar literals are valid patterns. They match by value-equality:

              [?match $status
           [case 200    :ok]
           [case 404    :not-found]
           [case 500    :server-error]
           [case 'admin' :elevated]
           [case true   :enabled]
           [case null   :missing]
           [else        :unknown]]
            

Integers, floats, strings, bools, dates, datetimes, and `null` are all matchable as scalar literals. Float equality follows the EBV rules — `nan` is **never** equal to `nan` (per IEEE-754). Use `is-nan($x)` to test for NaN explicitly.

CXPath patterns

A CXPath value used as a pattern matches if the candidate value is in the path's result sequence:

              [doc [heading 'Title'] [prose 'Body.']]
           [?let [= $node [$first //heading]]
             [?match $node
               [case //heading [h2 [$text $node]]]
               [case //prose   [p  [$text $node]]]
               [else           $node]]]
            

In a `[?for]` body, the same CXPath as the generator selects directly:

              [users [user email='ada@ex.com' active=true]
                [user email='bob@ex.com' active=false]]
           [?for [in $u //user[= $_@active true]] [yield $u@email]]
            

CXPath patterns and element-shape patterns compose in the same arm list — `[?match]` can dispatch on a mix of both, with first-match-wins ordering (see match).

Wildcards — *, **, _

Three wildcard forms:

• **`*` — any single element.** `[* $x]` matches any element and binds it. `[section * $body]` matches any section and binds the body wildcard slot.
• **`**` — recursive descent.** `[**]` matches any element at this position or deeper. Wrapping an inner pattern — `[** [user $u]]` — matches a `user` anywhere in the body and binds it.
• **`_` — anything, no bind.** `_` matches any value (including non-elements) without binding it. The idiomatic catch-all in `[?match]`.

              [?let [= $node [section [h2 'T'] [code 'x = 1']]]
             [?match $node
               [case [section * $body] [matched-section]]
               [case [** [code $c]]    [highlighted $c]]
               [case _                 $node]]]
            

Named bindings — $name

`$name` (lowercase, leading `$`) is a binding hole. It appears in attribute-value position (`[user email=$e]`), in body position (`[user $u]`), and in a destructuring `[?for]` generator (`[?for [in [user $u] /users/user] …]`).

A bind hole always succeeds at its position; the bind value depends on what the surrounding pattern dictates (see pattern-element-shape). Naming collisions inside one arm raise `CXER0100` (PARSE_ERROR) — `[user @id=$x @name=$x]` would require the values be equal, which the current spec does not support; use a single bind and check with a `[when …]` clause.

Type-guard heads

A type guard `:TypeName` at **pattern-head position** narrows by schema-typed shape:

              [# Match only elements whose schema type is ServerConfig #]
           [?match $cfg
             [case [:ServerConfig $c] [$validate-server $c]]
             [case [:ClientConfig $c] [$validate-client $c]]
             [else [result status=err code='CXER0103' reason='unknown config']]]
            

Type-guard resolution is by the document's schema binding (see schema in the data section); with no schema in scope type guards are rejected at program load. Pair with schema binding (`[?cx schema='…']`) for type-driven dispatch.

[?for] — iteration

`[?for]` is the iteration / comprehension primitive. The expression in the `[in …]` clause is either a CXPath (yields a sequence to iterate), a pattern (matches the generator — the `[?find]` replacement), or any expression that evaluates to a sequence.

              [site
             [user id=1 email='ada@example.com'   age=36 active=true]
             [user id=2 email='grace@example.com' age=17 active=false]
             [post author=1 [title 'Notes']]
             [request 'r1'] [request 'r2']
             [logs [row 'a'] [row 'b']]]

           [# CXPath generator                                           #]
           [?for [in $u //user] [yield $u@email]]

           [# Pattern generator (the `[?find]` replacement)              #]
           [?for [user @active=true $u] [yield $u@email]]

           [# Filter with [where …]                                      #]
           [?for [in $u //user] [where [>= $u@age 18]] [yield $u@id]]

           [# Multiple generators (Cartesian, in declared order)         #]
           [?for [in $u //user]
                 [in $p //post[= $_@author $u@id]]
                 [yield [pair user=$u@id post=[$text $p/title]]]]

           [# Parallel evaluation                                        #]
           [?for [in $r //request] [par] [yield [got [$text $r]]]]

           [# Streaming over large input                                 #]
           [?for [in $row //logs/row] [stream] [yield [$text $row]]]
            

`[par]` and `[stream]` are evaluation-modifier clauses — same surface, different scheduler. `[par]` distributes iterations across worker threads (add `[ordered]` to preserve source order). `[stream]` couples the generator to a streaming input source so that the iteration runs in bounded memory regardless of input size. Full semantics in [`spec/code.md`](../../spec/code.md) §7.

**Multiple `[where …]` clauses** AND together; **multiple `[yield …]` clauses** concatenate (per the sequence-flat principle — yields never produce a list-of-lists).

[?match] — dispatch (single + multi-arm)

`[?match]` is pattern dispatch. CX supports two forms: **2-arg destructure** (single arm, asserts the value matches or raises) and **multi-arm** (first-match- wins across N arms). The multi-arm form is a recent addition.

**Single-arm form** — pattern-bind a value and assert the shape:

              [# Destructures $result as [ok V] or raises CXER0100 #]
           [?let [= $result [ok 42]]
             [?match $result [ok $v] [yield [rendered $v]]]]
            

**Multi-arm form** — first-match-wins across `[case …]` / `[when …]` / `[else …]` clauses. Arms may mix element-shape patterns, scalar literals, CXPath paths, wildcards, and predicate-only `[when …]` clauses:

              [?let [= $node [code 'x = 1']]
             [?match $node
               [case [prose $p]   [p $p]]
               [case [code $c]    [pre $c]]
               [case 'separator'  [hr]]
               [else              ()]]]

           [# SQL Searched-CASE — predicate-only mode (no scrutinee)     #]
           [?let [= $x 120] [= $y 10]
             [?match
               [when [> $x 100]   :big]
               [when [> $y 50]    :medium]
               [else              :small]]]

           [# Guards on case arms — [where …] filters even on a match    #]
           [?let [= $req [http-get '/admin']]
             [?match $req
               [case [http-get $u] [where [= $u '/admin']] [route $u]]
               [case [http-get $u]                         [status 403]]
               [else                                       [status 400]]]]
            

**Arm semantics:**

• **`[case PAT R]` — match against pattern `PAT`.** Arms evaluate top-to-bottom; the first one whose pattern matches "wins". Later arms are not tried, even if they would also have matched.
• **`[when PRED R]` — match iff predicate truthy.** No pattern; the predicate is evaluated with the scrutinee in scope as `$_` (and any earlier `[case …]` bindings still in scope only if the same arm).
• **`[else R]` — catch-all, always last.** Equivalent to `[case _ R]`. Multiple `[else …]` clauses raise `CXER0100`.
• **`[case PAT [where PRED] R]` — guard on a case arm.** The pattern must match AND the predicate must be truthy.
• **No implicit EBV in `[case …]`.** `[case …]` tests pattern equality / structural match; it does not apply EBV. `[when …]` uses EBV.

**No-match behavior differs by form.** The 2-arg form raises `CXER0100`; the multi-arm form yields `()` (the empty sequence) if no arm matches and no `[else …]` is present. An unreachable arm (covered by an earlier arm with no guard) raises a warning at parse time but does not fail compilation.

**Status.** Multi-arm `[?match]` is fully spec'd. V's evaluator carries the production-ready implementation; Tier-2 binding parity is per [`spec/v0_8_0_status.md`](../../spec/v0_8_0_status.md).

[?if] — boolean branch (with EBV)

`[?if cond [then E1] [else E2]]` is the explicit boolean branch. The condition is evaluated with the EBV (Effective Boolean Value) rule — see ebv below.

              [site [admin 'root'] [config debug=false]]
           [?if //admin [then [admin-panel]] [else [user-panel]]]
           [?let [= $age 36]
             [?if [>= $age 18] [then :adult] [else :minor]]]
           [?let [= $cfg [$first //config]]
             [?if $cfg@debug [then [debug-trace]] [else ()]]]
            

For multi-way conditionals prefer `[?match]` multi-arm (see match). `[?if]` stays separate from `[?match]` because they have different contracts — `[?if]` uses EBV (truthy/falsy with container rules), `[?match]` `[case …]` does **not** (it tests strictly by structural equality / pattern match).

**The `[else …]` clause is optional.** When omitted, an untrue condition yields `()` (the empty sequence). Many CX idioms exploit this — `[?if $n@hidden [then ()] [else [$render $n]]]` reads as "render unless hidden".

[?let] — binding

`[?let]` introduces a local binding. The bound name is in scope inside the body that follows.

              [meta host='api.example.com' port='8443']

           [# Multiple bindings — flat, sequential, each sees the prior #]
           [?let [= $meta [$first //meta]]
                 [= $base [$string $meta@host]]
                 [= $port [$string $meta@port]]
                 [= $url  [$concat 'https://' $base ':' $port]]
             [endpoint target=$url]]
            

`[?let]` is the only way to give an expression a name currently — there is no `def` inside a function body, no inline `where` (that is a `[?for]` filter). To name a value that is used multiple times, `[?let]` is idiomatic.

[?modify] — pure-functional updates

`[?modify]` is the update directive. It takes a document (or sub-tree), a CXPath focus, and one or more action slots; it returns a **new** document with the action applied at every focus match. The original is unchanged (pure-functional).

The **eleven action slots** are:

              [doc
             [user id=1 name='Ada' active=true]
             [user id=2 name='Bob' active=false banned=true]
             [section id='intro' [para 'Hi.']]
             [list [item 'a']]
             [h2 'T'] [code 'x'] [price 10.0] [para 'p'] [deprecated 'old']]

           [# Scalar attribute update                                    #]
           [?modify $doc //user[= $_@id 1]/@name [set 'Alice']]

           [# Delete matching nodes                                      #]
           [?modify $doc //user[= $_@active false] [delete]]

           [# Transform with [using …]                                   #]
           [?modify $doc //price [using [?fn ($p) [* $p 1.1]]]]

           [# Rename — keep attrs + body, change name                    #]
           [?modify $doc //para [rename p]]

           [# Set + delete attrs                                         #]
           [?modify $doc //user [set-attr verified true]]
           [?modify $doc //user [delete-attr legacy-id]]

           [# Append + prepend children                                  #]
           [?modify $doc //section[= $_@id 'intro'] [append [para 'Added.']]]
           [?modify $doc //list [prepend [item 'header item']]]

           [# Insert siblings                                            #]
           [?modify $doc //h2 [insert-before [hr]]]
           [?modify $doc //code [insert-after [aside 'note']]]

           [# Whole-node replace                                         #]
           [?modify $doc //deprecated [replace ()]]

           [# Multi-step pipeline composition (see [[pipe]])             #]
           [?pipe $doc
             [?modify //user/@status [set 'verified']]
             [?modify //user[= $_@banned true] [delete]]
             [?modify //user [set-attr last-audit '2026-05-22']]]
            

**Pure-functional — structural sharing.** `[?modify]` does not copy the whole tree. Only the spine from root to each matched node is copied; unchanged branches are shared with the original (immutable persistent data structure). For a 10 MB document with one matched node, the new heap cost is < 1 KB per matched node — and the original `$doc` value is still valid for read or hash.

**Multi-match.** The focus path selects a sequence; the action applies to every node in that sequence. Zero matches returns the original unchanged (not an error — the no-match-no-op invariant lets pipelines compose safely). All-matches-at-once means there is no ordering hazard between matches.

**Identity invariant.** `[?modify $doc //x [set v]]` where `//x` matches no nodes returns `$doc` unchanged — same canonical bytes, same SHA-256. `[?modify $doc //x [delete]]` where every `//x` is removed returns a value where `[$count //x]` is 0. Round-trip through ast-bin / data-bin / JSON preserves the post-modify shape exactly.

**Status.** `[?modify]` is fully spec'd. The V evaluator carries the production-ready implementation. Tier-2 binding parity is tracked in [`spec/v0_8_0_status.md`](../../spec/v0_8_0_status.md) gate 30.

Pipelines and composition

The `[?pipe]` directive threads the output of one expression into the input of the next. Pipelines compose `[?modify]`, `[?for]`, builtins, and user-defined functions into readable top-to-bottom data flow.

              [shop [user active=true age=30]
               [user active=true age=20]
               [user active=false age=40]]
           [?pipe //user[= $_@active true]
             [?fn ($us) [?for [in $u $us] [yield $u@age]]]
             [$reverse]
             [$nth _ 1]]
            

**Stages are bare transforms.** `[?pipe SRC STAGE …]` evaluates `SRC`, then supplies the value to each `STAGE` left-to-right. A stage is a transform — a bare name, a `$ref`, or a `[$call …]` — never wrapped in a keyword (there is no `[through]` clause). `[?pipe 5 add1 add1]` → `7`.

**Stage invocation (§8.9.1).** How the value is supplied depends on the stage shape: a **hole-form** stage carries a single partial-application hole `_` and the value fills it (`[$get _ '/users/42']` → `get(client, '/users/42')`); a **no-hole** stage receives the value **appended as its final positional argument** (`count` ≡ `[$count _]`). A pipe threads exactly one value, so a stage may carry **at most one** `_` (two or more → `cx-err:CXER0100`). A non-callable stage (a literal, map, or data element) is `cx-err:CXER0100` — it never silently passes the value through.

**Fan-out behavior.** When `SRC` evaluates to a sequence, a stage sees the whole sequence as a single value (the sequence-flat principle — no implicit per-item dispatch). For a per-item transform, thread a `[?fn]` lambda that runs the comprehension:

              [users [user name=ada] [user name=bob]]
           [?pipe //user
           [?fn ($us) [?for [in $u $us] [yield [decorated name=$u@name]]]]
           [$count]]
            

**`[tap f]` — observe without diverting (§8.9.2).** A `[tap f]` stage applies `f` to the current value for its **side effect**; the value passes through unchanged and `f`'s return is discarded. Inside a stage, `_` names the current value, so `[tap [$log:info 'seen' fields={v: _}]]` logs and flows on. A tap propagates an `[err]` only when its code is `CXER0001` (panic) or `CXER0260` (cancellation); every other error is discarded for the data flow (the error-hook still observes it).

**Railway short-circuit (§8.9.3).** The pipe is a single-channel failure railway: the first stage to yield `[err …]` skips every remaining stage — taps included — and that `[err]` is the result. An empty result is **not** a short-circuit; it flows to the next stage. There is no infix `|` and no `[through]` wrapper — both retired.

Sequence built-ins

Operate on a Sequence. Argument may be a CX program sequence, the implicit document, or a single non-sequence value (treated as a 1-element sequence).

Set combinators are **reserved operator heads**, not `[$…]` builtins: `[union A B]`, `[intersect A B]`, `[except A B]`. Slicing / windowing / ordering / grouping are directives and comprehension clauses: `[?take]`, `[?drop]`, `[?filter]`, `[?flatten]`, `[order-by …]`, `[group-by …]` (see for).

              [site [user active=true] [user active=false]
                 [tag 'a'] [tag 'b'] [tag 'a']]
           ([$count //user[= $_@active true]],
            [$distinct [?for [in $t //tag] [yield [$text $t]]]],
            [?take 3 [$range 1 100]],
            [union (1, 2) (2, 3)])
            

String built-ins

Operate on a String scalar. Non-string scalars are stringified by the canonical scalar printer; element arguments raise `CXER0100` unless documented otherwise.

The wider string toolkit — trim, split/join, replace, case-folding variants, padding — is the `cx-stdlib/strings` module (`[?lib 'cx-stdlib/strings']`, then `[$strings:trim …]`, `[$strings:split …]`, `[$strings:join …]`, `[$strings:replace …]`). Regular expressions are `cx-stdlib/re`. See the Standard-library pages.

              [?lib 'cx-stdlib/strings']
           ([$upper 'hello world'],
            [$contains 'ada@example.com' '@example.com'],
            [$strings:join ('a', 'b', 'c') ', '],
            [$strings:split 'a,b,c' ','],
            [$strings:replace 'foofoo' 'foo' 'bar'])
            

Numeric built-ins

Operate on numeric scalars. `sum`/`min`/`max`/`avg` operate on a sequence and skip non-numeric items; `floor`/`ceiling`/`round`/`abs` operate on a single value.

Type coercion is the single explicit `cast` operator — `[cast '42' :int]`, `[cast 3 :float]`, `[cast 42 :string]` — there is no `to-int` / `to-float` family. CX floats are **finite-only**: `NaN` and `±Inf` never arise (an operation that would produce one raises `CXER0101`), so there is nothing to test with an `is-nan`. Exponentiation is `[$math:pow]` in `cx-stdlib/math`.

              [orders [order amount=10] [order amount=32]]
           ([$sum [?for [in $o //order] [yield $o@amount]]],
            [$round 3.7],
            [$mod 17 5],
            [cast '42' :int])
            

Logical built-ins

Boolean combinators and EBV-aware tests. `and` / `or` short-circuit; `not` is total over any EBV-typed argument.

`and` / `or` / `not` are bare operator heads (`[and P Q]`, no `$` sigil); `eq` is the structural equality the `=` operator also uses. There is no `xor` / `if()` / `instance-of` builtin — branch with `[?if]`, and test types by schema validation or `[?match]` shape dispatch.

              [site [user verified=true active=true banned=false] [error 'e1']]
           [?let [= $u [$first //user]]
             ([and $u@verified $u@active [not $u@banned]],
              [$exists //error],
              [eq [a 1] [a 1]])]
            

Node-accessor built-ins

Operate on an Element node — read structural properties. Script-level equivalents of the Layer-1 binding methods (see layer-1).

Structural navigation is CXPath, not accessor calls: children are `$e/*`, the parent is `//x/parent::*` (document-anchored), attributes are `$e@name`. Inside a predicate the reserved bindings `$_position` and `$_last` replace XPath's `position()` / `last()` — there are no zero-arity accessor calls.

              [# name → 'section' · string → 'one' · [$_last] → the last
            section · [= $_position 1] → the first                    #]
           [doc [section 'one'] [section 'two']]
           ([$name [$first //section]],
            [$string [$first //section]],
            //section[$_last],
            //section[= $_position 1])
            

Error code registry (CXER0100–0299)

The CXER0100–0299 range is reserved for code-language errors. Errors are organized into subsystems by tens digits. The complete normative map is in [`spec/code.md`](../../spec/code.md) §9.5 — this subsection is the developer-facing summary.

**Pattern / parse — CXER010x:**

**Resilience — CXER014x / CXER015x:**

**Services — CXER016x:**

**Client — CXER018x:**

**Concurrency — CXER020x / CXER022x:**

**Async — CXER024x / CXER026x:**

**Visualization — CXER028x:**

The CXER0000–0099 range is reserved for data-language errors (parse, validate, canonicalize); see limits in the data section. CXER0300+ is reserved for future subsystems.

Services and clients

`[?http-service]` declares a named HTTP service with resource handlers. `[?http-client]` is its client side. Resources handle requests and return responses; the bodies are ordinary CX code.

**Service definition:**

              [?http-service on=http port=8080 name='users'
           read-timeout=30s
           write-timeout=30s
           max-body-bytes=10485760            [# 10 MiB                  #]
           max-connections=1000
           grace-period=30s

           [resource method=GET path='/users/:id'
             [?let [= $u //user[@id=$request/path-params/id]]
               [response status=200 [body $u]]]]

           [resource method=POST path='/users'
             consumes=application/cx
             [?let [= $body $request/body]
               [response status=201 [body [$create-user $body]]]]]]
            

**Resource parameters.** Each `[resource]` declares `method=METHOD path=PATH`, optional `produces=` / `consumes=` MIME attributes, optional `[auth …]` predicate-expression clause, and a body expression in positional position. PATH supports `:name` parameter binding — `/users/:id` exposes `$request/path-params/id` inside the body.

**Request and response shapes:**

              [request method='GET' path='/users/42'
             [path-params [id 42]]
             [query-params]
             [headers [header name='Accept' value='application/cx']]
             [body]]

           [response status=200
             [headers [header name='Content-Type' value='application/cx']]
             [body [user id=42]]]
            

**Lifecycle.** `[?http-service]` returns a handle. `[?service-handle name=N]` looks up an existing service. `[?stop $handle]` initiates graceful shutdown — drains in-flight requests for up to `grace-period=`, then force-closes; new requests during drain receive HTTP 503 (`CXER0166`). Process SIGTERM / SIGINT also triggers graceful shutdown.

**HTTP client.** `[?http-client target=URL …]` returns a client value; operations pipe through it:

              [?let [= $c [?http-client target='https://api.example.com'
                                    timeout=30s
                                    [resilience [?retry max=3]]]]
             [?pipe $c [$get _ '/users/42']]]
            

**Status.** Services are a stable surface; Tier-1 V binding ships the full implementation. Tier-2 bindings expose `[?http-client]` and `[?service-handle]` lookup but service-hosting may defer to the host's native HTTP framework. See bindings.

Workers and channels

`[?worker]` spawns a concurrent worker. `[?channel]` creates a FIFO message queue. `[?send]` and `[?receive]` move values across. `[?select]` is the multi-way receive.

              [?let [= $ch    [?channel name='jobs' buffer=8]]
              [= $sent1 [?send 1 to=$ch]]
              [= $sent2 [?send 2 to=$ch]]
           ([?receive from=$ch], [?receive from=$ch])]
            

              [?let [= $ch [?channel name='jobs' buffer=100]]
             ([?worker name='producer'
                [body [?for [in $i [$range 1 100]]
                        [yield [?send $i to=$ch]]]]],
              [?worker name='consumer'
                [body [?for [in $i [$range 1 100]]
                        [yield [$process [?receive from=$ch]]]]]])]
            

**Channel semantics.** `[?channel :buffer N]` has a bounded FIFO buffer. `:buffer 0` is synchronous (rendezvous — send blocks until receive). FIFO ordering is preserved per producer-consumer pair; with multiple producers, per-producer FIFO is preserved but there is no global cross-producer ordering.

**Send / receive variants.**

• `[?send V to=CH]` — block when buffer full; returns `[ok]` once buffered. Returns `CXER0200` (CHANNEL_CLOSED) if CH is closed.
• `[?try-send V to=CH timeout=DURATION]` — same but returns `CXER0201` (SEND_TIMEOUT) on buffer-full timeout.
• `[?receive from=CH]` — block when empty; returns next value. Returns `CXER0200` when CH is closed and drained.
• `[?try-receive from=CH timeout=DURATION]` — same but returns `CXER0202` (RECV_TIMEOUT) on empty-channel timeout.
• `[?close CH]` — mark closed. Subsequent `[?send]` fails immediately; subsequent `[?receive]` drains buffered values then returns CHANNEL_CLOSED. Double-close raises `CXER0203`.

**Worker observability.** Workers are handle-addressable:

              [?let [= $w [?worker name='sync-job' [body [$sync-database]]]]
             ([?wait-for worker=$w],                  [# block until done #]
              [?cancel worker=$w],                    [# cooperative      #]
              [?check-cancel])]                       [# polling point    #]
            

**Select — multi-way receive.** Evaluates all `[case …]` clauses concurrently; proceeds with the first ready. Uniform-random selection on simultaneous readiness:

              [?let [= $jobs   [?channel name='jobs' buffer=1]]
              [= $signal [?channel name='sig'  buffer=1]]
              [= $sent   [?send 42 to=$jobs]]
           [?select
             [case [from $jobs $job]   [handled $job]]
             [case [from $signal $sig] [signalled $sig]]
             [case [timeout 5s]        [heartbeat]]]]
            

**Shape.** `[?select]` clauses are clause-children: `[case [from CH $msg] HANDLER]` for a receive and `[case [timeout DURATION] HANDLER]` for a deadline. The spec/core/code.md §10.4.7 registry holds the authoritative shape. The v0.7.x `:case [:from CH $msg H]` [; version-literal-ok ] colon-slot form is retired — there is no dual-accept.

Async, await, and cancellation

`[?async EXPR]` evaluates EXPR in a new async context and returns a future immediately:

              [?let [= $f1 [?async [+ 1 1]]]
              [= $f2 [?async [* 2 2]]]
              [= $f3 [?async [$upper 'go']]]
           [?await-all $f1 $f2 $f3]]
            

**Future state machine.** Futures progress through `pending → running → done` / `failed` / `cancelled`. Once terminal, the state is immutable.

**Barrier variants:**

• `[?await $f]` — block until terminal; return value on done, propagate err on failed, CANCELLED on cancelled.
• `[?await $f timeout=DURATION]` — add a hard deadline; on expiry return `CXER0241` (AWAIT_TIMEOUT). The future continues running — `timeout=` bounds the caller's wait, not the future itself.
• `[?await-all FUTURES]` — block until all terminal. If all done, yield sequence of values. If any failed/cancelled, yield `CXER0240` with a `[causes …]` child carrying every non-done cause in input order.
• `[?await-any FUTURES]` — yield first to terminate. Other futures continue running; their results are discarded.
• `[?await-race FUTURES]` — yield first to terminate; **other futures are cancelled**. Use for "I only need one".

**Cooperative cancellation contract.** `[?cancel $f]` requests cancellation — it is a signal, not a kill. The runtime guarantees cancellation observation at:

• HTTP client calls at next network read/write boundary.
• `[?sleep DURATION]` — immediately.
• `[?send]` / `[?receive]` / `[?try-send]` / `[?try-receive]` — immediately, returning `CXER0260` (CANCELLED).
• `[?for]` — at every iteration boundary.
• `[?await]` — immediately.

**Pure CPU loops without yield points do NOT observe cancellation.** Authors who want a cancellable hot loop must insert `[?check-cancel]` at appropriate boundaries — it evaluates to `[ok]` normally, or `CXER0260` (CANCELLED) if cancellation is pending.

              [?def cancellable-compute impure ($n)
             [?for [in $i [$range 1 $n]]
               [where [= [?check-cancel] [ok]]]
               [yield [* $i $i]]]]
           [$cancellable-compute 4]
            

**Composition with resilience.** `[?async]` composes with every resilience directive. `[?async [?timeout 5s [$slow-call]]]` returns a future that resolves to `CXER0141` (TIMEOUT) after 5s if `slow-call` hasn't completed.

**Status.** Async/await is stable in V. Tier-2 binding parity (Python `asyncio`, Go `chan`, Rust `tokio`) ships per [`spec/v0_8_0_status.md`](../../spec/v0_8_0_status.md) gate 28.

[?retry] — bounded re-run with backoff

Re-run an inner body on `[err …]` return, up to `max=` attempts, sleeping between attempts per `backoff=` / `delay=` / `jitter=`. Terminal failure raises `CXER0140` (RETRY_EXHAUSTED).

**Backoff formulas** (delay for attempt N, N ≥ 1): `constant` = `delay=`; `linear` = `delay × N`; `exponential` = `delay × 2^(N-1)`; `fibonacci` = `delay × fib(N)`.

**Jitter modes** (D = pre-jitter delay): `none` = `D`; `full` = `uniform(0, D)`; `equal` = `D/2 + uniform(0, D/2)`; `decorrelated` = `uniform(delay, last_delay × 3)`.

              [?retry max=5 backoff=exponential delay=200ms jitter=equal
           [on [?fn ($e) [= $e@code 'CXER0163']]]        [# only on timeout #]
           [?pipe $client [$get _ '/users/42']]]
            

[?timeout] — hard deadline

Bound execution time of an inner body. On expiry, cooperatively cancel the body and return the `[on-timeout …]` clause body (if present) or `[result status=err code='cx-err:CXER0141' elapsed=DURATION]`.

              [?timeout 5s
             [$slow-database-query $q]
             [on-timeout [result status=err code='CXER0141' reason='db slow']]]
            

[?circuit-breaker] — fail-fast on consecutive failures

Three states: **closed** (passes through), **open** (rejects with `CXER0150` (BREAKER_OPEN) without calling `:body`), **half-open** (allows one probe). Transitions:

• Closed → open when failure ratio in rolling `window=` exceeds `threshold=`, with at least `min-samples=` recorded.
• Open → half-open after `reset=` elapses.
• Half-open → closed if probe succeeds.
• Half-open → open if probe fails.

              [?circuit-breaker
             threshold=0.5 window=60s reset=30s min-samples=20
             name='users-api'
             [?pipe $client [$get _ '/users/42']]]
            

[?fallback] — alternative on error

If primary returns `[err …]`, evaluate secondary and return its value (which may itself be `[err]` — `[?fallback]` does not wrap that case).

              [?fallback
             [?pipe $client [$get _ '/users/42']]
             [recover-with [$load-from-cache 42]]]
            

**`$err` in `[recover-with …]`.** Inside the recovery scope, `$err` is bound to the primary's `[err …]` value, so recovery can introspect the failure (e.g. `[recover-with [response status=500 reason=$err/@message]]`). The clause-child `[recover-with …]` form is the sole accepted shape (no legacy colon-slot).

[?rate-limit] — token-bucket cap

Permits at most `max=` invocations per `per=` window. Excess invocations return `CXER0151` (RATE_LIMITED) with a `retry-after=DURATION` attribute — the time until the next token frees.

              [?rate-limit max=100 per=1s name='github-api'
             [?pipe $client [$get _ '/repos/cx-home/cx']]]
            

[?bulkhead] — bound concurrent calls

Bounds concurrent invocations. If `max-concurrent=` slots are busy and `queue=` slots are full, returns `CXER0152` (BULKHEAD_FULL). Queued requests wait FIFO for a free slot.

              [?bulkhead max-concurrent=10 queue=50 name='db-pool'
             [$query-database $q]]
            

Composition

Resilience directives compose by nesting. The outermost runs first, so its policy sees the inner policies' err codes. Standard pattern reads top-down:

              [?retry max=3
            [?timeout 10s
              [?circuit-breaker threshold=0.5 window=60s reset=30s
                [?http-client target='https://api.example.com' method='get']]]]
            

Reading: retry up to 3 times a 10-second-bounded call gated by a 50%-failure circuit-breaker. If the breaker opens, `[?retry]` sees `CXER0150` and decides whether to keep retrying (default `[on …]` predicate returns truthy → yes; override to scope which errs retry).

**State identity (stateful directives).** `[?circuit-breaker]`, `[?rate-limit]`, and `[?bulkhead]` carry state across invocations. By default state is keyed by lexical source-text position — every evaluation of the same source node (including iterated under `[?for]` or `[?map par=true]`) shares state. Pass `name=STR` to key by name instead, enabling cross-position sharing (one rate-limit budget enforced by callers in different modules).

Directives turn data into a language

A directive is a CX element whose name starts with `?`. It carries semantics — iteration, branching, substitution, include, function call — that the evaluator interprets when running a CX program. Directives parse as regular CX, evaluate to text or values, and compose with each other through their slot bodies.

              EXPR                                     [; bare expression evaluates ]
           [?for [in $x PATH] [yield BODY]]         [; iterate ]
           [?if COND [then THEN] [else ELSE]]       [; branch ]
           [?let [= $x EXPR] BODY]                  [; bind a name ]
           [?def name ($a $b) BODY]                 [; define a function ]
            

Pattern matching — walking the tree

The current program surface replaces XPath-style queries with `[?for]` pattern generators and CXPath path values (`[?find]` retired). A pattern is a CX literal where element names match by shape, attribute predicates restrict by value, and `$bindings` capture matched subtrees. `[?for]` walks the tree (deep by default) and binds for each match; `[?match]` tests a single value (multi-arm dispatch).

              [shop
             [user [name 'Ada']]
             [item active=true 'i1']
             [pizza [name 'Margherita'] [price 12]]]
           [?for [user [name $n]] [yield $n]]
           [?for [item @active=true $i] [yield $i]]
           [?for [pizza [name $n] [price $p]]
                 [yield [hit name=$n price=$p]]]
            

Comprehensions and composition

`[?for]` iterates a sequence (or matches a pattern across the tree) and yields per-iteration values; `[where …]` filters, `[order-by …]` sorts, `[group-by …]` aggregates. `[?let]` binds names; `[?if]` branches. The `[?pipe]` directive composes them.

              [?for [in $x (1, 2, 3)] [where [> $x 1]] [yield [* $x $x]]]
           [?let [= $a 10] [= $b 32] [+ $a $b]]
           [?pipe (1, 2, 3, 4) [$count]]
            

                  [# W1 — strided range, then slice, then comprehension #]
             [?def $odds [$range 1 99 2]]
             [?def $first-ten $odds[:10]]
             [?def $squares [?for [in $x $first-ten] [yield [* $x $x]]]]

             [# W5 — infinite range with [take …] #]
             [?for [in $x [$range 1 *]] [where [$prime? $x]] [take 100] [yield $x]]

             [# W7 — map comprehension over CXPath source #]
             [?for [in $u //user] [yield-map [$u@id $u@email]]]
                

Quick reference

              [; Every user in the document. ]
           //user

           [; Every user whose @active attribute equals true. ]
           //user[= $_@active true]

           [; Email addresses of every active user. ]
           //user[= $_@active true]/@email

           [; The third user in document order. ]
           //user[3]

           [; Anything two levels deep under root. ]
           /*/*

           [; Every sibling that follows the first user. ]
           //user[1]/following-sibling::user

           [; Every ancestor element of a [para] node. ]
           //para/ancestor::*

           [; General predicate — prefix code over the $_ context binding. ]
           //user[and [>= $_@age 18] $_@active]

           [; Range and set combinators. ]
           [$range 1 10]
           [union //a //b]
           [intersect //x //y]
           [except //all //banned]
            

Four leading forms

Every CXPath has one of four leading-token forms. - **`//` descendant** — `//user` — `descendant-or-self::node()/child::user`; the most common shape. - **`/` absolute** — `/root/item` — child of the document root; rare in well-shaped data. - **relative** — `user/email` — applied against the current evaluation context. - **`$name/` binding** — `$u/email` — rooted at a previously-bound value (per `[?for]` / `[?let]` / `:bind`).

Twelve axes

Every step can specify an axis. The default axis is `child::`; the `attribute::` axis has the dedicated `@` sigil. CX implements all twelve XPath 3.1 axes: `child`, `descendant`, `descendant-or-self`, `parent`, `ancestor`, `ancestor-or-self`, `self`, `following-sibling`, `preceding-sibling`, `following`, `preceding`, `attribute`.

Composite shortcut forms: `/name` ≡ `child::name`; `//name` ≡ `descendant-or-self::node()/child::name`; `@name` ≡ `attribute::name`; `..` ≡ `parent::node()`; `.` ≡ `self::node()`. Attribute axis is name-disjoint from element axes — `//user/@name` selects the attribute only; `//user/name` selects the child element only.

General predicate + reserved bindings

Predicates filter the step sequence. A predicate body is prefix CX code coerced to a boolean via the Effective Boolean Value (EBV) rule. The atomic shorthands — `[@name]` / `[@!name]` (attribute present / absent), `[N]` (position), a bare child name (step-existence) — remain available and round-trip via canonical re-emit. Value comparisons are always prefix: `[= $_@name V]`.

**Three reserved bindings** in scope inside every predicate body: `$_` (current candidate item, type matches the candidate kind), `$_position` (1-based int index — equivalent to XPath `position()`), `$_last` (int cardinality of the candidate sequence — equivalent to XPath `last()`). Predicates are eagerly materialised, so `$_last` is known on every predicate evaluation.

**Comparison sigils** are value-comparison only: `=`, `!=`, `<`, `<=`, `>`, `>=`. No keyword synonyms (no `eq`/`ne`/`lt`/etc.). Comparing a sequence with more than one item raises `CXER0103`. **Purity** — every predicate body MUST be pure; impure callees fail load with `CXER0230`.

Cross-step reference — nested generators

To reference an **outer** step's focus from an inner predicate ("leads of teams with at least three members"), stack `[?for]` generators — each generator names its focus, and every later clause sees the earlier bindings:

              [org
             [team [member role='lead' [name 'a']] [member [name 'b']] [member [name 'c']]]
             [team [member role='lead' [name 'e']]]]
           [?for [in $t //team]
                 [in $m $t/member]
                 [where [and [= $m@role 'lead'] [>= [$count $t/member] 3]]]
             [yield $m/name]]
            

The grammar reserves a `:bind` path-step modifier (grammar.ebnf [159]-[160]) for naming a step's focus inline; the nested-generator form above is the conformance-exercised idiom.

In the host bindings

Every Tier-1 binding exposes CXPath identically through its Layer-1 surface — same selector, same bytes returned across the C ABI.

              emails = doc.select_all("//user[= $_@active true]/@email")
            

              emails, _ := doc.SelectAll("//user[= $_@active true]/@email")
            

              let emails = doc.select_all("//user[= $_@active true]/@email")?;
            

              emails := doc.select_all('//user[= $_@active true]/@email')!
            

CXER001x — security caps

- `CXER0010` — function call depth exceeded. - `CXER0011` — collection size cap reached (`sequence_len`, `map_entries`, `capture_size`). - `CXER0014` — eval-time include attempted without `--include-root`.

CXER004x — evaluator gates

- `CXER0040` — purity gate: `SideEffect` / `ReadOnly` filter raised under `[?cx pure-only]`. - `CXER0041` — module gate: `on_declaration` module called without `use-module`. - `CXER0042` — eval gate: `cx:eval` invoked without `[?cx allow-eval]`. - `CXER0043` — eval depth gate: `cx:eval` recursion exceeded `max-eval-depth`.

E9xx — include resolver

- `E901` — absolute path rejected. - `E902` — path escapes include root (lexical or symlink). - `E903` — URL-scheme path rejected. - `E904` — cycle detected. - `E905` — max depth exceeded. - `E906` — file not found. - `E907` — file not readable. - `E908` — path is a directory. - `E909` — I/O error during read. - `E910` — non-UTF-8 content. - `E911` — included file parse failure.

Recovering with [?match]

              [?lib 'cx-stdlib/io']
           [?match [$io:read-file '/no/such/file.cx']
             [case [err @code=$c] [where [= $c 'cx-err:CXER0271']] [needs-capability]]
             [case [err $e] [other-error code=$e@code]]
             [else :ok]]