Glossary
Overview
Section titled “Overview”This page is the single canonical source for JacqOS vocabulary. Every other page in the docs uses these terms with these meanings. Where the same idea has informal synonyms in the wider industry — “world state” for worldview, “schema” for ontology, “rule” for invariant — the canonical term wins, and the informal name appears only inside an analogy frame with a bridge back here.
Entries are alphabetical. Each entry defines the term in one or two sentences, gives a short worked example, and links to the canonical reference page where you can read more.
A principal associated with an observation, model call, human review, or effect step. Actors explain who produced evidence or under whose authority an event was recorded; they do not become workflow nodes and do not grant effect authority by themselves.
Example. A review observation can carry actor_id = "user:clinician-7" and
actor_kind = "human" so provenance can show which reviewer approved a staged
candidate.
For local apps, put identity fields your ontology must reason about in the observation payload and map them into atoms. The V1 portable observation envelope also reserves actor metadata fields for export, audit, and cloud handoff.
An AI agent role or component that reads a worldview and emits observations, candidate evidence, proposal evidence, or external events. In JacqOS, an agent is identified for provenance; it is not a hidden workflow primitive with its own private truth.
Example. agent_id = "refund_triage" can label the component that asked a
model to propose a refund, while the ontology still decides whether that
proposal can become an intent.
See Multi-Agent Patterns.
A typed unit of evidence extracted from a single observation by a mapper. Atoms are the structural boundary between raw external input and semantic logic: rules in .dh query atoms via the built-in atom(...) relation, never the raw observation payload.
Example. A POS webhook observation flattens into atoms like atom("pos.received", "ord-42") and atom("pos.line_item", "ord-42", "cola", 2) that downstream rules consume.
See Atoms, Facts, Intents and Rhai Mapper and Helper API.
AtomBatch
Section titled “AtomBatch”The deterministic flattening of one observation into the complete set of atoms it produces. AtomBatch is the durable plane that sits between observations and facts; the mapper output for a given observation is a single AtomBatch, identified by a mapper_output_digest.
Example. Replaying the same observation through the same mapper always yields the same AtomBatch, byte-for-byte, regardless of host or build.
See Evaluation Package.
Authority scope
Section titled “Authority scope”A domain label describing what authority an actor exercised or claimed for one
event, such as clinician.review or finance.approve_refund. The label is
evidence until the ontology accepts it.
Example. A human review may claim authority_scope = ["refund.approve"]; your rules still decide whether that actor is trusted to
approve that refund class.
See Invariant Review.
BlobRef
Section titled “BlobRef”A content-addressed handle for a large raw payload that lives outside the observation log. Observations carry BlobRef references rather than embedding multi-megabyte bodies inline, keeping the log compact while preserving exact replay.
Example. An LLM completion observation stores the prompt and response as two BlobRefs; the observation row itself is small and cheap to scan.
See Effect Capabilities (blob.put / blob.get).
Candidate
Section titled “Candidate”The reserved candidate.* relay namespace for fallible-sensor evidence. Models that extract structured data from noisy input — voice parsers, vision models, LLM extractors — emit candidate.* facts; an explicit acceptance rule must promote a candidate before any downstream rule may treat it as accepted truth.
Example. A voice parser producing candidate.order_item("ord-42", "water", 18000) cannot directly become an accepted_order_item fact — the ontology requires a confirmation observation before promotion. A bad parse stays staged; it cannot silently become a fact.
See Fallible Sensor Containment and .dh Language Reference.
Effect
Section titled “Effect”The execution lifecycle of an intent plus the observations it produces. Effects are the only path through which derived intents touch the outside world; the runtime invokes the declared effect capability, records the receipt as a new observation, and feeds it back into the next evaluation cycle.
Example. An intent.send_email("req-1") becomes an effect that calls the SMTP capability, then writes a email.dispatched observation back to the lineage.
See Effects and Intents.
Effect capability
Section titled “Effect capability”A declared permission for an external action that guest code is allowed to request. V1 ships five capabilities — http.fetch, llm.complete, blob.put / blob.get, timer.schedule, log.dev — and undeclared capability use is a hard load error.
Example. A jacqos.toml that omits [capabilities.http] cannot fire any intent.* that resolves to an HTTP effect, even if the rule that derives it is otherwise valid.
Evaluator
Section titled “Evaluator”One complete semantic evaluation configuration: an ontology IR plus mapper semantics plus helper digests. The evaluator is the deterministic engine that derives facts from observations; for any lineage, exactly one committed evaluator activation may execute effects.
Example. Promoting a shadow build to the production evaluator for a lineage is what makes that build effect-authoritative; until promoted, the shadow can derive facts but cannot fire intent.* effects.
Event time
Section titled “Event time”Time evidence supplied by an observation producer or payload. obs.timestamp
is the event-time label mappers receive; it can drive freshness, deadlines, and
calendar facts, but it never changes observation order.
Example. A lab result observed at 2026-04-01T12:00:00Z can be compared
with a request timestamp to derive result.fresh("lab-7").
See Rhai Mapper and Helper API.
Evaluation package
Section titled “Evaluation package”The frozen runtime handoff for one evaluator: a portable bundle of ontology IR, canonical mapper export, helper digests, and metadata. Identified by a package_digest, an evaluation package is the contract boundary used to move the same semantic evaluation between environments without re-derivation.
Example. jacqos export evaluation-package produces an evaluation package you can ship to a fresh host; replaying the same lineage there yields the same worldview.
See Evaluation Package.
evaluator_digest
Section titled “evaluator_digest”The primary semantic identity of an evaluator. Computed as a hash over the ontology IR, mapper semantics, and helper digests; prompt-only changes do not change the evaluator_digest. Two evaluators with the same digest derive the same facts from the same observations.
Example. Editing a prompt in prompts/extraction.md changes neither the ontology IR nor the helper digests, so the evaluator_digest is unchanged — the evaluator remains semantically identical.
A derived truth record that the system currently believes, with explicit provenance back to the atoms and rules that produced it. Facts are the queryable shape of the worldview; guest code never asserts facts directly — they are derived by .dh rules from atoms or from other facts.
Example. booking_confirmed("req-1", "slot-42") is a fact derived from a confirmation atom plus the rule that closes a booking once a slot has been held and confirmed.
Helper
Section titled “Helper”A capability-free pure function callable from .dh rules via the helper.<name>(...) prefix. Helpers compute deterministic values — string normalization, parsing, math — and have no I/O, no atom construction, and no awareness of the call site. Helpers are a strict subset of the mapper sandbox: every helper could run as a mapper, but no mapper can run as a helper.
Example. helper.normalize_email(raw) lowercases and trims an email address inside a rule body; it cannot read files, cannot call out to the network, and cannot append observations.
Mapper vs helper. Mappers cross the structural boundary from observations to atoms — they are the only place atom(...) is registered. Helpers are called from already-loaded ontology rules and never see observations at all.
See Rhai Mapper and Helper API.
Human review identity
Section titled “Human review identity”The stable identity and digest binding for a human-review decision. A review is still an observation plus ontology rules; it does not directly mutate facts or bypass invariants.
Example. A review observation can carry review_id, reviewer_actor_id,
and review_digest so Studio can prove which evidence was reviewed before a
candidate was accepted.
See Invariant Review.
Intent
Section titled “Intent”A derived request to perform an external action, expressed as a fact in the reserved intent.* namespace. Intents sit at the world-touching boundary: the evaluator derives them from facts the same way it derives ordinary facts, and the runtime turns them into effects.
Example. intent.send_confirmation_email("req-1") is an intent derived once a booking is confirmed; the runtime resolves it to an HTTP effect against the configured email capability.
See Effects and Intents.
Invariant
Section titled “Invariant”A parameterized integrity constraint declared in .dh with the invariant keyword. The body is a Datalog query over relations, comparisons, and aggregates. After every evaluation fixed point, the evaluator computes the parameter domain (every binding of the invariant’s free variables that appears in the current state) and checks that the body succeeds for every binding in the domain. If the body fails for any binding, the invariant is violated and the transition that produced the offending state is rejected. Invariants are JacqOS’s primary human-review surface — instead of reading AI-generated rule code, developers declare the boundaries the evaluator enforces.
Example. invariant no_double_booking(slot) :- count booking_confirmed(_, slot) <= 1. is satisfied iff every slot binding the evaluator has seen has at most one confirmed booking. A second confirmation for the same slot fails the body for that domain element and rejects the transition.
See Invariant Review and .dh Language Reference.
Ingestion time
Section titled “Ingestion time”Store-local audit metadata recording when an observation was appended or imported. It is not mapper input, helper input, or ontology input, so replaying the same observations into a clean store does not change semantic state.
Example. Importing a 2026-04-01 claim file on 2026-04-24 may create a new local ingestion timestamp, but rules still derive from the claim observations’ event-time evidence.
Lineage
Section titled “Lineage”One immutable observation history, identified by a lineage_id. A lineage may have child branches (for shadow comparison or counterfactual exploration), but branches do not merge back: once an observation is appended, the history is fixed.
Example. Forking lineage_id = "prod-2026-04" to a child for shadow analysis lets a new evaluator derive a separate worldview from the same observation prefix without affecting the parent.
Lineage vs worldview. A lineage is a sequence of observations — what happened. A worldview is the set of derived facts a specific evaluator computes over that sequence — what those observations mean under one ontology. The same lineage produces different worldviews under different evaluators.
Mapper
Section titled “Mapper”The structural boundary between raw observations and semantic atoms. A mapper is a Rhai script that takes one observation and emits a deterministic batch of atoms; the canonical mapper export is the portable contract that downstream tools verify, not the Rhai source.
Example. mappings/inbound.rhai consumes a webhook payload and emits atom("payment.received", id, amount) and friends; the same observation always produces the same atoms.
Mapper vs helper. Mappers cross from observations into atoms (they hold the atom(...) capability). Helpers run inside rule bodies and can do neither. See Helper for the other side of the boundary.
See Rhai Mapper and Helper API.
mapper_output_digest
Section titled “mapper_output_digest”The hash of the canonical mapper export for one observation. Two mapper implementations that produce the same canonical export — even in different languages — converge on the same mapper_output_digest and are interchangeable for replay purposes.
Example. A future Wasm rewrite of an existing Rhai mapper that emits the same atoms in the same order has the same mapper_output_digest and replays existing fixtures byte-for-byte.
Observation
Section titled “Observation”An append-only piece of evidence that something happened. Observations are the only canonical truth surface in JacqOS: every fact, intent, and effect traces back to specific observations through explicit provenance edges.
Example. webhook.received with a JSON body, email.sent with a delivery receipt, and timer.fired from a scheduled wakeup are all observations; once written they cannot be edited or removed.
See Observation-First.
Observation order
Section titled “Observation order”The sequencer order of observations inside one lineage. It defines replay prefixes and is the deterministic tie-breaker when event timestamps are equal, missing, or out of order.
Example. Two webhook observations can both carry
2026-04-01T12:00:00Z; JacqOS still replays them by their lineage order, not
by sorting on the timestamp string.
Ontology
Section titled “Ontology”The set of .dh files that defines what facts mean, which states are valid, and how derivation proceeds. The ontology declares the formal signature of an application — relations, rules, intents, invariants — and the evaluator interprets it deterministically against atoms.
Example. ontology/schema.dh, ontology/rules.dh, and ontology/intents.dh together form the ontology of a scaffolded app. Editing a rule and saving the file hot-reloads the ontology in under 250ms.
package_digest
Section titled “package_digest”The hash of the frozen evaluation package contents. Two evaluation packages with the same package_digest are byte-identical handoffs and produce identical worldviews from identical observations.
Example. A CI job pins production deployments by package_digest, refusing any package whose digest is not on the allowlist.
Proposal
Section titled “Proposal”The reserved proposal.* relay namespace for fallible-decider output — typically LLM-suggested actions like sending an offer or applying a remediation. Proposals never become executable intents until an explicit domain decision relation ratifies them against policy and invariants.
Example. A pricing model emitting proposal.send_offer("cust-7", 3299) cannot directly fire intent.send_offer; the ontology requires a sales.decision.offer_authorized(...) fact derived from a policy rule before the intent may derive. A bad proposal stays queued; it cannot silently become an effect.
See LLM Decision Containment and .dh Language Reference.
Worldview
Section titled “Worldview”The set of facts derived from a specific evaluator over a lineage. A worldview is the queryable shape of “what the system currently believes” — what an agent reads when it queries shared state. The same lineage under different evaluators produces different worldviews.
Example. A shadow build’s worldview may include experimental remediation facts that the production evaluator’s worldview does not, because each computes facts under its own ontology.
Informal synonyms to avoid. “World state,” “the model,” “derived reality,” and “the world view” are all aliases used elsewhere in the industry. The canonical JacqOS term is worldview. Where docs analogize to a SQL view or a spreadsheet, the analogy still resolves back to the worldview defined here.