Documentation Index
Fetch the complete documentation index at: https://docs.cerulion.com/llms.txt
Use this file to discover all available pages before exploring further.
A trigger policy decides when a node fires. It can be set on the CLI via --policy SPEC (on node create and node modify) or in source via a #[cerulion_node(...)] attribute. Trigger policy lives only on the macro side — graph YAML carries no policy block.
--policy SPEC grammar
SPEC is parsed by parse_policy_spec. Accepted forms:
| SPEC | Maps to MacroPolicy | Rules |
|---|
period_ms=N | Period { period_ms: N } | N must be a positive integer > 0. Bare period_ms (no =N) → error “requires a value”. period_ms=0 → error “must be > 0”. |
deadline_ms=N | Deadline { deadline_ms: N } | Same N rules. |
sync_window_ms=N | Sync { window_ms: N } | Same N rules. |
external | External | Case-insensitive keyword. |
data_trigger=NAME or trigger=NAME | DataTrigger { input_name: NAME } | NAME must be non-empty and match a declared input. |
| anything else | error | ”unknown policy spec X” listing the accepted forms. |
--policy default was removed. It used to alias period_ms=100; it now errors with “unknown policy spec”. A 100 ms period must be written --policy period_ms=100.
Macro-attribute equivalents
Each --policy SPEC has an equivalent #[cerulion_node(...)] attribute. See Node macro reference for full attribute semantics.
--policy SPEC | Macro attribute |
|---|
period_ms=N | #[cerulion_node(period_ms = N)] |
deadline_ms=N | #[cerulion_node(deadline_ms = N)] |
sync_window_ms=N | #[cerulion_node(sync_window_ms = N)] |
external | #[cerulion_node(external)] |
data_trigger=NAME / trigger=NAME | field marked #[input(trigger)] named NAME |
unbounded_sync and tick_deadline_ms = N attributes have no --policy SPEC equivalent; they are macro-only.
Defaulting matrix
When --policy is omitted, node create resolves the policy from the declared inputs (resolve_create_policy):
| Inputs declared | Result |
|---|
0 inputs (no -i, no -T) | Error: source-only nodes must declare a non-data policy explicitly (--policy period_ms=N or --policy external). |
1+ inputs via -i only | No node-level policy attr is written (bare #[cerulion_node]). The runtime fires on any input arrival and emits a graph-build warning. No silent auto-promotion to data_trigger. |
-T set | DataTrigger { input_name: <T's name> }, regardless of the -i count. |
Non-data --policy + -T | Error (conflict). |
The engine convenience wrapper node_cmd::node_create (used by tests/TUI scaffolding) supplies Period { period_ms: 100 } when called with policy = None. The CLI path uses the strict node_create_with_options, which enforces the 0-inputs-error rule. The “100 ms default” is a convenience-API behavior, not the CLI default.
Policy short labels
node list and node info print a short policy label via format_policy_short:
| Label | Policy |
|---|
period <N>ms | Period |
deadline <N>ms | Deadline |
sync <N>ms | Bounded sync |
sync ∞ | Unbounded sync |
external | External |
trigger:<input> | Data trigger |
- | None |
