Entries

An Entry represents a concrete domain-level data instance in Orbital. Entries are the primary units of data that Ørbs read, render, evaluate, and use to make behavioral decisions.

Technically, every Entry is stored and transported as an Orbital Message, meaning it follows the same header structure, versioning rules, and persistence model as all other data in the system. What distinguishes an Entry is not its storage format, but its semantics and constraints.

---

Entry vs Message

The defining difference between Messages and Entries is that Entries are always associated with a Schema and represent concrete, schema-scoped data instances.

• Managed Messages includes both Schemas and Entries.
  Managed Entries are Managed Messages validated against a Schema, effectively acting as instances of that Schema.

• Transactional Messages include both transaction definitions and transaction records.
  Transactional Entries are Transactional Messages that represent individual transactions and progress through a linear lifecycle, also constrained by a Schema.

In short, all Entries are Messages, but Entries are distinguished by being schema-bound instances, while other Messages define structure, configuration, or behavior.

---

Schema-Entry Relationship

Each Entry is associated with a single Schema through its subject namespace and validated against a specific Schema version.

Current Model

The Entry–Schema relationship is derived rather than explicitly declared:

1. Subject-based association
   The Schema is determined by the Entry’s NATS subject path:
   {orb}.{module}.entries.{schemaId}.{entryId}
   The {schemaId} segment defines the Schema namespace the Entry belongs to.

2. Version tracking
   Entries record schemaVersion in their metadata, indicating the Schema version they were validated against. PLANNED

This model allows the system to:

• Route entries deterministically via subject hierarchy
• Detect schema drift when an Entry’s recorded schemaVersion differs from the current Schema version
• Support future migration and re-validation tooling

Future Enhancements

Planned improvements include:

• Schema migration tooling across versions
• Validation enforcement at write time
• Bulk re-validation commands

Entry Lifecycles

Entries follow the same lifecycle categories as the Message category it’s based on. It determines how an Entry behaves over time and how it is interpreted by consumers.

Managed Entries

Managed Entries are Managed Messages that conform to a specific Schema. They represent data used for content, rules, and other domain objects whose lifecycle can be explicitly managed, such as being activated or deactivated over time.

Typical lifecycle states include:

SAVED → PUBLISHED → UNPUBLISHED → ARCHIVED

Managed Entries:

• support versioning
• create a new version on content changes or state transitions
• are interpreted by read models based on state and, when applicable, validity windows

Optional properties such as validFrom and validTo may be used to schedule activation and deactivation.

---

Transactional Entries

Transactional Entries are Transactional Messages conform to a specific Schema. They represent discrete processes or events with explicit and linear state transitions:

INITIATED → PENDING → COMPLETED

Transactional Entries:

• create new versions only when the state changes
• cannot be manually altered, unpublished, or deleted
• act as an immutable record of what occurred

They are typically used for financial transactions, workflows, or audit-critical processes.