Glossary
Canonical definitions of the core Valem terms. Other docs link here instead of redefining them inline — every term below is deep-linkable, so feel free to point at one.
The spec
ModelSpec
The declarative JSON document describing a model: schema, constants, defaultValues, derivations, meta-derivations, constraints, effects, tests, and an optional view definition. Usually LLM-generated. See reference/model-spec-format.md.
Derivation
A computed, read-only field defined by a JSONata expression, re-evaluated when its dependencies
change. eager (computed during the mutation) or lazy (computed on demand).
Meta-derivation
A computed piece of per-field metadata (min, max, required, relevant, …) stored in the meta
cache, not the base document. Drives effective schema and view behavior.
Constraint
A boolean invariant evaluated after each mutation. Policy rollback (revert + 409) or flag
(commit + report).
SpecEvolution
An incremental diff applied to a spec (upsert/remove per section + optional new
schema/version/view). Validated and recompiled; live state carried forward via withModel().
Address vs expression path
An address (a path used as data: spec path fields, defaultValues paths, mutation/patch keys,
view bind) must be canonical JSON Path — $.-rooted with bracket indices
($.order.items[0].qty). The validator rejects legacy dot-index ($.items.0.x) and unrooted
addresses as errors (PathConverter.toCanonicalAddress gives the canonical rewrite). An
expression body (expr/trigger/payload and JSONata view fields) uses JSONata navigation
(order.total) and is never rewritten or constrained. PathConverter also bridges JSON Path →
JsonPointer.
State
Base document (baseDoc)
The writable portion of model state — a Jackson ObjectNode. Only base fields can be mutated
directly.
Merged document (mergedDocument())
A deep copy of the base document with all derived-cache values spliced in. The evaluation context
for global constraints and effect triggers, and the shape returned by GET /state.
Derived cache
In-memory map of $.path → value holding computed derivation results.
Meta cache
In-memory map of $.path#property → value holding meta-derivation results.
Effective schema
A field’s static JSON Schema fragment overlaid with live meta-cache values. Returned by
GET /schema/{path}.
Snapshot
An immutable deep copy of state (baseDoc + derived/meta caches). Used for rollback, point-in-time
history, and restore. No timestamp; blobs excluded (content-addressed).
BlobRef
A lightweight pointer {$blobId, $mediaType, $bytes} stored in state in place of binary data; bytes
live in a BlobStore (content-addressed by SHA-256).
The engine
Dependency graph
Precompiled DAG of node dependencies that makes incremental evaluation possible — only nodes
reachable from a mutation are recomputed. Built by ModelSpecCompiler.
Node kinds
BASE (writable path), DERIVED (computed path), META (path#property), plus synthetic
$constraint:<id> / $effect:<id> nodes.
Dirty propagation
BFS over the dependency graph from mutated paths (plus wildcard [*] pattern matching) to compute
the full set of nodes needing re-evaluation.
Evaluation level
Topological depth group (depth = 1 + max-predecessor-depth). Nodes in one level are mutually
independent; a level-k+1 derivation can see level-k results but not its own-level siblings.
Derivation trace
A record (expression, input paths, result or pass/fail, error) written to a 500-entry ring buffer
for both derivation and constraint evaluations. Powers GET /explain.
Effects
Effect
An effect request the pure core emits as data when a JSONata trigger fires on state change; the
imperative shell then executes it, selected by executor: caller (pure — surfaced as
dispatchedEffects in the mutation result, no egress), server (a guarded HTTP request), llm (an
LlmClient call), or timer (a scheduled fold-back), plus operator-installed plugin kinds. The
result folds back as an ordinary mutation, so state stays deterministic and replay never re-runs
the I/O. Replaces the removed actions section (a spec still carrying actions is rejected). See
reference/model-spec/effects.md and
deployment/security-model.md.
Fold-back
The re-entry of an effect executor’s result into model state as an ordinary, logged mutation
(source: foldback), applied via a keyed compare-and-swap against the effect’s dedupeKey
(CURRENT → apply, SUPERSEDED → discard + re-fire for the latest value, CANCELLED → discard).
Because the result is a logged mutation, replay never re-runs the I/O.
statusPath
The canonical address of the per-effect I/O status sub-document ({phase, key, at, error}) that
drives the pending → in_flight → applied | failed | cancelled effect state machine and the edge /
in-flight guard.
Egress guard
The SSRF guard fronting the built-in server effect executor (and, separately, the LLM web_fetch
tool): loopback/private/link-local IP blocking, https-only by default, optional destination-host
allowlist and response-size cap. Does not extend to third-party effect-kind plugins. See
deployment/security-model.md.
Composition and views
Branch / lineage / promote
A branch is a model created with template.ref, materialized into a self-contained spec with
the ancestor chain pinned in read-only lineage. Promote moves a model one-way into a
web-class repository (POST /models/{id}/promote), closure-checked. Cross-owner inherited effects
are quarantined until approved. See
model-guide/composition-and-branching.md.
View definition / EvaluatedView
A renderer-agnostic UI component tree embedded in the spec; ViewEvaluator resolves it against
merged state + meta into an EvaluatedView. See
reference/view-system.md.