Skip to content

Glossary

This glossary collects the named concepts defined across OpenArmature's capability specifications — each with a one-line gloss and a link to the section where it is normatively defined. Terms are grouped by capability; the index links to every term for alphabetical lookup. The gloss orients — the linked spec section is authoritative.

Index

Graph engine

  • Compiled graph — The immutable, executable result of compiling a graph definition; compilation fails on no declared entry, unreachable nodes, dangling edges, multiple outgoing edges, or conflicting reducers. graph-engine §2
  • Compile-time warning — A non-fatal advisory the compiler may emit alongside a successfully compiled graph (distinct from a compile error) — e.g. projection_reducer_round_trip, warning that a subgraph's declared-same-name projection round-trips a field through a reducer; asserted in fixtures via expected_compile_warning. graph-engine §2
  • Declared same-name projection boundary — A subgraph projection form between field-name matching and explicit inputs/outputs maps: an explicit in-set / out-set of field names projected by identity across the boundary, compile-validated. graph-engine §2
  • Drain — The engine's flush of all queued observer events before an invocation returns, so delivery completes within the invocation boundary. graph-engine §6
  • Edge — A directed connection between nodes: a static edge (fixed destination) or a conditional edge (destination computed from state, or the END sentinel). Each node has exactly one outgoing edge. graph-engine §2
  • END — The engine-provided sentinel routing target that halts execution; a distinct constant, not a reserved node name. graph-engine §2
  • Error category — A canonical identifier classifying a failure (e.g. node_exception, no_declared_entry, dangling_edge, fan_out_empty), surfaced per the language's idiom for cross-impl consistency. graph-engine §4
  • Fan-out lineage chain — The ordered chain of enclosing fan-out / parallel-branch positions (fan_out_index_chain / branch_name_chain) that disambiguates a span or event nested inside multiple fan-out layers, so a lineage-resolved parent can be chosen deterministically; the checkpoint sibling is enclosing_fan_out_lineage. graph-engine §6
  • Framework-emitted augmentation event — A typed event the engine emits beyond raw node events — typed LLM completion / failure, embedding, rerank, and tool-call events — carrying provider- or tool-specific structured detail to observers. graph-engine §6
  • Invocation — A single execution of a compiled graph via the entry surface (invoke()), returning one of three outcomes. (In conformance fixtures, one invoke() call within an invocations: list — conformance-adapter §2.) graph-engine §3
  • Invocation outcome — The result shape of an invocation: completed (reached END), errored (a node raised), or suspended (a node paused; see Suspension). graph-engine §3
  • Node — A named, asynchronous unit of work that receives the current state and returns a partial update; it must not mutate the state it received. graph-engine §2
  • Node event — The started/completed event pair the engine dispatches per node execution (and per retry attempt) to observers. graph-engine §6
  • Observer — An async callable receiving node lifecycle events from a strictly-serial delivery queue; the read-only telemetry surface over an invocation. graph-engine §6
  • Reducer — A function merging a node's partial update into prior state for one field; each field has exactly one. Eight canonical reducers ship — last_write_wins (default), append, merge, concat_flatten, merge_all, bounded_append, dedupe_append, merge_by_key — and custom reducers may be registered per field. graph-engine §2
  • State — The typed schema (a record of named, typed fields) describing data flowing through a graph; validated at graph boundaries. graph-engine §2
  • Subgraph — A compiled graph used as a node inside another graph; runs against its own state schema and projects results back into the parent via inputs/outputs mappings, field-name matching, or a declared same-name projection boundary. graph-engine §2

Pipeline utilities

  • Branch middleware — Middleware wrapping a single parallel branch's invocation, analogous to fan-out instance middleware. pipeline-utilities §11.7
  • Branch spec — The per-branch definition inside a parallel-branches node: the branch's subgraph plus its inputs/outputs projections. pipeline-utilities §11.1.1
  • Cause chain — The structured caught_exception on a failure-isolation event: an ordered list of {category, message, carrier} links (outermost→innermost) plus a derived top-level category and message. pipeline-utilities §6.3
  • Checkpointer — The save / load / list / delete protocol backends implement to persist checkpoint records, keyed by invocation_id. pipeline-utilities §10.1
  • Checkpointing — Opt-in durable persistence of invocation progress so an interrupted run can resume; provided by a registered Checkpointer. pipeline-utilities §10
  • CheckpointRecord — The in-memory typed object the engine hands to save: serialized state plus the completed-node positions needed to resume. pipeline-utilities §10.2
  • Degraded instance — A fan-out instance that returns a configured degraded_update instead of raising; it counts as a §9.3 success whose contribution is the degraded value. pipeline-utilities §9.8
  • error_policy — A fan-out / parallel-branches failure mode: fail_fast (default — the first failure aborts) or collect (gather per-instance / per-branch errors and continue). pipeline-utilities §9.5
  • Failure isolation — The canonical middleware that catches exceptions escaping the inner chain and returns a configured degraded partial update, emitting a named failure-isolation event. pipeline-utilities §6.3
  • Fan-in / collect — The merge of each fan-out instance's collect_field value back into the parent's target_field via that field's reducer. pipeline-utilities §9.3
  • Fan-out node — A node that runs a subgraph (or async callable) once per item in a parent field — or count times — with bounded concurrency, collecting per-instance results into a parent field. The one place subgraph executions overlap in time. pipeline-utilities §9
  • Idempotency contract — The requirement that resumed nodes tolerate re-execution, since resume may re-run a node whose effects partially applied before the interruption. pipeline-utilities §10.5
  • Instance middleware — Middleware wrapping each fan-out instance's invocation as a unit, sitting between the fan-out node's outer middleware and the instance subgraph's own middleware. pipeline-utilities §9.7
  • Middleware — An async callable wrapping a node with the shape (state, next) -> partial_update; it may inspect or transform input, short-circuit, catch exceptions, or retry by calling next again. pipeline-utilities §2
  • Middleware chain — An ordered sequence of middleware around one node, composing outer-to-inner; each layer's return flows back through the previous layer's next call. pipeline-utilities §2
  • Parallel branches — A node holding a static map of named, heterogeneous subgraphs that run concurrently within one invocation; topology-driven, complementing data-driven fan-out. pipeline-utilities §11
  • Per-instance projection — How each fan-out instance receives its slice of parent state: the per-item value via item_field, plus any inputs-mapped parent fields. pipeline-utilities §9.1
  • Pre-/post-node phase — The two halves of a middleware split by await next(...): the pre-phase runs on the way in (outer-to-inner), the post-phase on the way out (inner-to-outer). pipeline-utilities §2
  • Resume — Continuation of a checkpointed (or suspended) invocation via invoke(resume_invocation=...), replaying from the last completed position. (Suspension's resume: suspension §7.) pipeline-utilities §10.4
  • Retry — The canonical middleware that re-invokes the wrapped chain on classifier-matched exceptions, up to max_attempts, with configurable backoff (default exponential with full jitter). pipeline-utilities §6.1
  • State migration — Versioned transformation of a persisted checkpoint's state shape (schema_version chain resolution) so older records load into a newer schema. pipeline-utilities §10.12
  • Timing — The canonical middleware that measures wrapped-node wall-clock duration on a monotonic clock and reports it via callback. pipeline-utilities §6.2

LLM provider

  • Call-level retry — The provider's own opt-in retry lane, distinct from (and nested inside) graph-engine retry middleware; beyond transient API failures it can retry a structured_output_invalid failure via a caller-authored reask builder, and may apply a per-attempt override schedule across attempts. llm-provider §7.1
  • Conditionally-managed field — A managed wire field the mapping produces only sometimes, managed only while it is being produced — e.g. response_format while a response_schema is supplied, stream_options while streaming; outside that window it is an ordinary unmanaged extras key. llm-provider §6
  • Content block — A typed segment of message content: text, image, thinking, or redacted_thinking; imported unchanged by harness-chat. llm-provider §3.1
  • Decoded-value deep equality — The normative test for whether an extras value is equal to (a no-op) or conflicting with a managed field's value: parsed values compared structurally — objects member-wise (key order irrelevant), arrays element-wise in order, scalars by value — not by byte-level JSON or language object identity. llm-provider §6
  • Extras pass-through — The convention by which vendor-specific request parameters not in the typed config are forwarded to the provider via an extras bag, with null-skip semantics — except a key that names a managed wire field, which is merged or rejected rather than forwarded untouched. llm-provider §6
  • Managed field — A wire-body field a mapping sets for its own correctness (its response consumer reads it, or it enforces a mapping contract); a colliding extras key does not get untouched pass-through but is merged if the field is list-shaped or rejected pre-send if non-additive and conflicting (a managed-field collision). Each §8 mapping enumerates the keys it manages. llm-provider §6
  • Message — A typed conversation entry of kind system, user, assistant, or tool, each carrying kind-specific content. llm-provider §2
  • Per-attempt override — An optional call-level-retry schedule that overrides RuntimeConfig fields per retry attempt (e.g. lowering temperature on a re-ask), part of the adaptive retry extensions. llm-provider §7.1
  • Provider — An object bound to a model identifier that, given messages and optional tools, returns one assistant message wrapped in a Response. llm-provider §2
  • Provider interface — The ready() / complete(...) contract every provider satisfies. llm-provider §5
  • reask — A caller-authored builder that constructs the corrective follow-up message re-sent when a structured_output_invalid failure is retried in place; the framework authors no prompt text, the caller supplies the wording (principle 7). llm-provider §7.1
  • Reasoning-continuity signature — An opaque token attached to a thinking block that lets a provider verify reasoning continuity across turns. llm-provider §3.1.7
  • Response — A provider call's result: the assistant message, a finish reason, and usage information. llm-provider §2
  • RuntimeConfig — The caller-supplied per-request parameter record (temperature, max tokens, etc.) plus an extras pass-through bag for vendor-specific knobs. llm-provider §6
  • Structured output — Provider support for constraining a completion to a caller-supplied response schema, with a documented fallback for models lacking native support. llm-provider §8
  • Tool — A function the model may request the caller execute, defined by name, description, and a JSON-Schema parameters shape. llm-provider §2
  • Tool call — An assistant message's request to invoke a named tool with structured arguments; answered by a tool message bearing the matching tool_call_id. llm-provider §2
  • Tool definition — The record (name, description, parameters) describing a tool to the provider. llm-provider §4
  • Wire-format mapping — The normative translation between the spec's message / tool / config shapes and a vendor API's wire bytes; defined for OpenAI-compatible, Anthropic Messages, and Google Gemini. llm-provider §8

Retrieval provider

  • Batch chunking — The general §8 rule that an embedding mapping whose input exceeds the vendor's per-call cap splits it into ≤cap chunks, issues one request per chunk, and stitches the results back in input order (chunk-and-stitch); the stitched usage sums the chunks and the stitched raw is the list of per-request responses. retrieval-provider §8
  • Embedding runtime config — A RuntimeConfig-shaped record for embedding requests; minimally an optional dimensions plus an extras pass-through bag. retrieval-provider §2
  • EmbeddingProvider — An object bound to an embedding model that turns input strings into vectors wrapped in an EmbeddingResponse. retrieval-provider §2
  • EmbeddingResponse — An embed() result: the vectors, model identifier, a nullable usage record, and an optional request id plus the verbatim provider raw response (an object or an array). retrieval-provider §2
  • EmbeddingUsage — An embedding usage record carrying input_tokens only (vectors have no output tokens); the whole record is nullable, and a malformed input_tokens on the wire collapses usage to null (see Malformed ancillary figure). retrieval-provider §2
  • Malformed ancillary figure — A provider figure present on the wire but malformed (non-integer / negative / boolean) in an ancillary field (usage counters, response_id) is treated as not reported: nulled, never raised, never fabricated or coerced, kept verbatim on raw, and not surfaced on typed events. The llm-provider §7 sibling is the malformed usage counter. retrieval-provider §7
  • RerankProvider — The retrieval protocol for relevance reranking — re-scores candidate documents against a query, returning relevance-sorted ScoredDocument entries — named as part of the RetrievalProvider umbrella. retrieval-provider §5
  • RerankResponse — A rerank() result: the relevance-sorted ScoredDocument list, model identifier, a nullable usage record, and an optional request id / verbatim provider raw response. retrieval-provider §6
  • RerankUsage — A rerank usage record; nullable, following the same not-reported semantics as EmbeddingUsage. retrieval-provider §6
  • RetrievalProvider — The umbrella capability covering EmbeddingProvider and RerankProvider; a capability-level descriptor for cross-protocol concerns, not a concrete protocol itself. retrieval-provider §2
  • ScoredDocument — One entry of a RerankResponse: an original-index reference, a relevance score, and the echoed document (the provider's echoed text where present, else null; the verbatim echo is preserved on raw). retrieval-provider §6

Observability

  • Attribute namespace — The openarmature.* dotted-key namespace for OA span attributes; upstream GenAI semconv names are adopted only once they reach upstream Stable. observability §5
  • Correlation ID — A per-invocation, application-supplied identifier that flows across every observability backend as a join key; distinct from the backend-local invocation_id. observability §2
  • Detached trace mode — An opt-in mode where a specific subgraph or fan-out gets its own trace, with the parent's dispatch span carrying an OTel Link to it. observability §4.4
  • Driving span — The currently-open span an implementation drives as work executes; its lifecycle (open / attribute / close) is specified for deterministic emission. observability §6
  • GenAI semconv — The OpenTelemetry Generative-AI semantic-convention attribute subset OA emits on LLM spans (the Stable subset). observability §5.5.3
  • invocation_id — The per-invocation identifier (caller-supplied or framework-generated) that correlates spans within a single backend; the checkpoint / resume key, distinct from the cross-backend correlation_id. observability §3.2
  • Langfuse mapping — The normative projection of OA spans onto Langfuse's trace / observation / generation data model and attributes. observability §8
  • Log correlation — The contract that log records emitted during an invocation carry the correlating ids (correlation_id, invocation_id) so logs join to traces. observability §7
  • Queryable observer — The pattern where a concrete observer exposes extra read methods that pipeline nodes consume at runtime, without expanding the abstract Observer protocol. observability §9
  • Span — An OTel unit of work — a named interval with timestamps, status, attributes, and parent/child links; each meaningful unit of a graph invocation maps to one. observability §2
  • Span attributes — Scalar (or scalar-array) key/value pairs on a span, namespaced under openarmature.. observability §2
  • Span hierarchy — The span tree of an invocation: invocation span (root) → node / subgraph / fan-out spans, with one node span per retry attempt. observability §4
  • Span status — A span's OK / ERROR / UNSET status; engine error categories map to ERROR with a category-bearing description. observability §2
  • Trace — An OTel tree of spans under one trace id; by default one outermost invocation is one trace, with subgraphs / fan-outs nested (unless detached). observability §2
  • Turn-level wrapper span — An optional harness-emitted span wrapping a whole turn, parenting the invocation span(s) within it. observability §4.6

Prompt management

  • ChatSegment — A unit of a chat-prompt template (role + content) in the chat-prompt variant of Prompt. prompt-management §3.1
  • ContentBlockTemplate — A templated content block within a ChatSegment, mirroring llm-provider content blocks at the template layer. prompt-management §3.1
  • Fetch vs. render — The deliberate split between retrieving a template (the I/O-bound step) and applying variables to it (local), enabling separate caching and inspection. prompt-management §2
  • Prompt — An unrendered template plus identity metadata; what a backend returns from a fetch, renderable and content-addressable without another round-trip. prompt-management §2
  • PromptBackend — The fetch-by-name-and-label protocol backends implement; backends fetch, they do not render. prompt-management §2
  • PromptGroup — A tracing convention grouping related PromptResults (e.g. classifier + follow-up) under one logical span grouping; not a fetch or render primitive. prompt-management §10
  • PromptManager — The user-facing API composing one or more PromptBackends and exposing fetch + render. prompt-management §2
  • PromptResult — The rendered output of applying variables to a Prompt: the rendered Message sequence, identity metadata, and a rendered_hash. prompt-management §2
  • token_budget — An advisory, observability-only ceiling a Prompt may carry (input_max_tokens / total_max_tokens); it never alters the request — it drives the observability signals that compare the provider's reported usage against the budget. prompt-management §2

Sessions

  • Session — The typed state record persisted under a session_id, carrying cross-invocation state plus identity metadata; distinct from per-invoke state. sessions §2
  • session_id — The caller-supplied, application-stable identifier scoping a session across many invocations; never engine-generated. sessions §2
  • SessionRecord — The stored representation of a session: session_id, serialized state, schema_version, and opaque backend metadata. sessions §2
  • SessionState — The optional typed projection of cross-invoke state — a narrower view than full invoke State, excluding per-invoke scratch fields. sessions §2
  • SessionStore — The load / save / delete / list protocol for session persistence; mirrors Checkpointer but session-keyed. sessions §2

Suspension

  • Paused-invocation record — The persisted state of a suspended invocation (state, signal descriptor, ids, completed positions), stored via the same machinery as checkpoints. suspension §2
  • Signal descriptor — The typed record attached at suspension: a caller-supplied signal_id correlation token plus optional application metadata. suspension §2
  • Signal payload — The application-defined data delivered at resume time and merged into invocation state before execution continues. suspension §2
  • signal_id — The caller-supplied correlation token on a signal descriptor, used to route an inbound signal back to its paused invocation. suspension §2
  • Suspended outcome — The invoke() return shape when a graph suspends — carrying invocation / correlation ids, the signal descriptor, the state at the pause, and the suspending node. suspension §2
  • Suspension — The intentional pause of an in-progress invocation at a node via suspend(); the engine persists state and returns a suspended outcome, resumed later with a signal payload. suspension §2

Harness

  • Harness — The integration layer wrapping the engine for a deployment runtime; owns inbound dispatch, the outbound surface, session lookup, and signal coordination. harness §2
  • Harness mode — Whether a harness is sessioned (every transmission tied to a session_id, state loaded / saved per turn) or stateless (independent turns, no session); fixed at construction. harness §2
  • Inbound dispatch path — One of the classification paths the harness routes inbound traffic into (stateless, new-session, existing-session, signal-resume). harness §2
  • Outbound surface — The mechanisms a harness uses to expose in-invocation effects: sync returns, async dispatches from node bodies, and signal subscriptions. harness §2
  • Session resolver — The (sessioned-mode) mechanism mapping inbound traffic to a session_id; the contract specifies that resolution happens, not how. harness §2
  • Signal coordinator — The mechanism routing inbound signal callbacks to the correct paused invocation. harness §2
  • Turn — One bounded engine execution serving an inbound request or event — exactly one invoke() (or resume) call, beginning at invoke entry and ending at its outcome. harness §2

Harness — chat

  • ChatMessage — The canonical typed message at the chat-harness boundary, mirroring llm-provider's message shape. harness-chat §2
  • ChatTurnOutcome — The discriminated return of the chat harness's send(): completed reply, errored turn, or suspended turn. harness-chat §2
  • ConversationHistory — The per-session field holding the ordered chat message list. harness-chat §2
  • Pending message — A synthetic assistant message a node may append before suspend() to tell the user the turn is awaiting a signal. harness-chat §2
  • send() callable — The convenience surface above raw invoke(): takes a session id and an inbound user message, returns a ChatTurnOutcome. harness-chat §2
  • Subscribed listener — The default mechanism by which a chat harness surfaces the post-resume assistant reply after a suspend → signal → resume cycle. harness-chat §2

Conformance adapter

  • Adapter — A language-specific runtime that discovers fixtures, parses their YAML into native graph calls, executes them, and asserts against the expected: block. Implementation-private; the fixtures are spec-public. conformance-adapter §2
  • Assertion shape — A field under expected: specifying what to verify — exact-equality (final_state, execution_order) or invariant (invariants, observer_event_invariants). conformance-adapter §2
  • carries (raised-error field assertion) — A conformance directive asserting fields carried on a raised error (not a returned value): under an expected raises:, a carries: map pins named error fields by value / presence / substring. Generalized to a capability-neutral convention whose keys name the error's own fields. conformance-adapter §5.13
  • Case — One scenario within a fixture; a fixture may hold a single top-level case or multiple under cases:. conformance-adapter §2
  • chunk_size (batch-chunking cap) — A construction directive overriding an embedding provider's per-call input cap in fixtures, so batch-chunking behavior can be exercised deterministically without hitting the real vendor limit. conformance-adapter §5.14
  • contains_event (typed-event assertion) — An assertion under expected.observers.<collector> that a typed event of a given event_type was captured with a fields: map matched by value; it pins the present-but-null vs absent distinction — an explicit null matches only a field that is present and null, distinct from an omitted field. conformance-adapter §5.5
  • Directive — A named YAML field declaring something the adapter translates into a runtime construct or assertion (e.g. update, fan_out, observers[], final_state). conformance-adapter §2
  • Directive vocabulary — The full catalog of fixture directives the adapter supports, organized by kind (node-behavior, state / schema, edge, composition, observer, persistence, invocation-shape, expected-outcome, invariant, value-matcher, provider call-retry, structured-output error, carries, chunk_size, and retrieval-provider directives). conformance-adapter §5
  • Fixture — A declarative test case: a YAML file (graph, initial state, expected outcome) plus a sibling Markdown describing intent and spec coverage. conformance-adapter §2
  • Harness primitive — A runtime construct the adapter must provide to satisfy directives needing infrastructure beyond the bare engine — in-memory observers, persistence backends, OTel capture, etc. conformance-adapter §2
  • Invariant — A name-keyed boolean predicate checked when ordering is observable but not uniquely determined (fan-out scheduling, parallel branches, observer dispatch). conformance-adapter §2
  • typed_observers (typed-event collectors) — A directive registering one or more kind: typed_event_collector observers on a fixture; each retains the graph-engine §6 typed event families (LlmCompletionEvent, EmbeddingEvent, RerankEvent, ToolCallEvent, …) for contains_event assertions. conformance-adapter §5.5