Pragma and clause reference

Lucen is driven by three comment pragmas. This page is the complete reference for them and for every clause they accept. The accepted forms here are the ones the clause validator enforces; a malformed clause is a loud import-time ClauseValueError with a did-you-mean suggestion, never a silent ignore.

The three pragmas

Pragma	Placement	Purpose
`# LUCEN START [clauses]`	Immediately above a `for` loop or a comprehension assignment	Opens a marked block and carries the tuning and assertion clauses
`# LUCEN END`	Immediately below the same construct	Closes the marked block
`# LUCEN TRUST [clauses]`	Immediately above a `def`	Asserts a helper is safe to run under parallelism

A marked comprehension is parallelized over its outermost iterable and rebuilt from ordered slots, so its result, including dict and set iteration order, is the one plain Python produces:

# LUCEN START
scores = [score(r) for r in records]
# LUCEN END

List, dict, and set comprehensions are supported, with filters and with further for clauses. A bare generator expression is lazy and is never parallelized; total = sum(elt for t in it) is supported, because sum drains the generator at that line. Its elements are computed in parallel and sum itself adds them afterwards, so the total is the builtin's own, down to the last bit.

The pragmas are ordinary comments. A file with Lucen not activated runs exactly as if they were absent. Clauses are comma-separated on the pragma line, for example:

# LUCEN START calibrate=false, timeout=5.0, on_error=collect

Every clause only ever trades a compiler-held proof for a programmer-held assertion, or exactness for speed. None of them changes the computed result; the ones that assert something the runtime can check are still checked.

Clauses on `# LUCEN START`

Backend and scheduling

Clause	Accepted forms	What it does
`backend`	`thread` \| `process` \| `sequential` \| `thread(pool_size=N, chunks=M)` \| `process(chunks=M, pool=<factory>)`	Pins the execution backend and its worker and chunk counts, overriding the automatic routing.
`calibrate`	`true` \| `false` \| `static` \| `always` \| `threshold(min_gain=<float>)`	Controls the profitability gate. `false` forces the parallel path; `threshold` sets the minimum projected gain. Every setting produces identical output.
`grainsize`	`<N>` \| `<N>(min_workers=M)`	Sets the level width for a recognized-DAG wavefront block.
`affinity`	`compact` \| `scatter` \| `explicit(cores=[...][, numa_node=N])`	Requests CPU affinity for the workers.
`nested`	`sequential` \| `shared_pool` \| `independent`	Policy for a marked block reached while another is already dispatching.

A process worker is a separate interpreter, so the pool costs one import graph per worker on a spawn platform. Size it for your imports rather than your core count; see Limitations 2.6.

Correctness assertions (expert)

These waive a compiler proof. They are the only clauses that can affect correctness, and only when the assertion is false; where the runtime can still check the assertion, it does.

Clause	Accepted forms	What it does
`depend`	`none` \| `acyclic(order=<callable>)`	Asserts iterations are independent (`none`), or that a dependency is acyclic under a given order. A false `depend=none` is still caught by the runtime write-set audit.
`skip_runtime_check`	`true` \| `false`	Disables the runtime write-set audit. Only meaningful together with `depend=none`; the two together are the only way to reach a silent wrong result, by design.
`trust`	`callables` \| `pickle` \| `all`	Waives the helper-purity proof (`callables`), the pickle-convergence check (`pickle`), or both (`all`).

Reductions

Clause	Accepted forms	What it does
`reduce`	`sum` \| `prod` \| `min` \| `max` \| `count` \| `any` \| `all` \| `bit_and` \| `bit_or` \| `bit_xor` \| `concat` \| `custom(fn=<callable>, identity=<value>[, tree=false])`	Names the reduction operator, or supplies a custom associative one with its identity.
`reduction_order`	`sequential_equivalent` \| `stable` \| `custom(combine=<callable>)`	How partial results are combined. The default `sequential_equivalent` is bit-identical to sequential; `stable` permits a reproducible tree-combine.

Errors and timeouts

Clause	Accepted forms	What it does
`timeout`	`<seconds>` \| `<seconds>(per_task=true[, on_timeout=<callable>])`	Bounds the block's wall time, raising `ParallelTimeoutError`. `per_task` applies the bound per iteration.
`on_error`	`collect` \| `collect(max_errors=N)` \| `custom(handler=<callable>)`	Gathers per-iteration exceptions instead of failing fast; readable afterward with `lucen.get_collected_errors`.
`strict`	`true` \| `false` \| `true(allow=[reason, ...])`	Turns this block's fallbacks into hard errors, optionally allowing named downgrade reasons.
`on_fallback`	`hard` \| `quiet` \| `report` \| `<mode>(allow=[reason, ...])` \| `custom(handler=<callable>)`	Sets how a fallback is surfaced for this block.

An exception raised on the process backend, whether it propagates or is gathered by on_error=collect, is rebuilt from its pickled form in the parent: the traceback is not carried, and a type that cannot be reconstructed from its message alone degrades to RuntimeError. See Limitations 2.5.

Observability

Clause	Accepted forms	What it does
`progress`	`true` \| `false` \| `callback(<callable>[, per_task=true, include_result=true])`	Reports per-chunk or per-iteration progress.

Clauses on `# LUCEN TRUST`

# LUCEN TRUST above a def asserts that helper is safe under parallelism, overriding the purity proof for it.

Clause	Accepted forms	What it does
`args`	`checked` \| `unchecked` \| `unchecked(only=[name, ...][, skip_runtime_check=true])`	How the helper's arguments are treated: checked as reads, or trusted, optionally for named arguments only.
`qualname`	`Class.method` \| `Class.method(module=exact.path)` \| `<registry_key>`	Identifies the callable the trust applies to when the bare name is ambiguous.

Configuration file

Project-wide defaults and hard ceilings live in lucen.toml at the project root: pool sizes, chunk counts, timeout ceilings, the error mode, an experimental-features veto, and a [trust] callables list. Its precedence runs from the built-in default, through [defaults], through a per-block pragma clause, clamped by [limits]. Degenerate values are rejected when the file loads, with the same strictness a pragma clause gets. See the technical specification for the full schema.

Experimental features

Three schedulers are off by default and enabled per process, not per block:

lucen.activate(experimental=["early_exit", "typed_buffers"])

Flag	Effect
`early_exit`	Parallelizes loops containing `break`, reproducing sequential first-match semantics speculatively.
`typed_buffers`	Dense array-output maps ship typed result slabs on the process backend instead of Python lists, roughly an order of magnitude cheaper to transfer.
`branch_sensitive_deps`	Per-branch dependency classification, more permissive than the default branch merge, under the runtime write-set audit.

None of them changes the computed result. A [limits] allow_experimental = false in lucen.toml vetoes all three for the project, which fleet operators can set to keep them out of a deployment.

Removed clauses

Two earlier clauses were removed and now fail loud with a pointer to the current form rather than being silently ignored: process_wait (recognized-DAG blocks run on the wavefront driver automatically) and batch_size (renamed to chunks=, a sub-argument of backend=).