Entities and lifecycle

In Cyoda, an entity is a durable state machine. It is a JSON document that belongs to a typed model, sits in a named lifecycle state, and carries a complete audit trail of every transition it has ever undergone. The entity is not a row to be updated in place; the entity is the state machine.

The entity IS the state machine

A Cyoda workflow is close in spirit to a BPM process, but the two are not the same. A BPM flow tends to be linear — it has a start, a sequence of activities, and an end. A Cyoda entity workflow is a state machine in the strict sense: there is no requirement for a terminating state, transitions need not follow a linear path, and an entity can move between states in any topology the model calls for, including cycles and branches.

That distinction matters in day-to-day modeling. You do not design “the process” and then attach entities to it; you design the states and transitions of a piece of business reality, and the entity lives inside that machine for as long as the business cares about it.

The picture above sketches the building blocks:

• States (teal rectangles) — the named stages of the entity’s life.
• Transitions — the atomic units of change. Auto transitions (solid, teal) fire as soon as their source state is entered; manual transitions (dashed, orange) fire only when an actor invokes them.
• Processors (green pills on a transition) — code that runs as part of the transition, under the platform’s event contract.
• Criteria (purple diamonds on a transition) — predicates that gate whether the transition is allowed to fire.

Every transition produces a new, durable revision of the entity. Nothing is overwritten.

Schema

Every entity belongs to a named model identified by modelName and modelVersion. Cyoda auto-discovers the model schema from ingested samples rather than requiring it up front: as records flow in, Cyoda observes the fields that appear, the types they take, and the shape of nested arrays and objects. That observed shape is the schema.

A model has two structural modes. While unlocked, it evolves by merging — new fields appear, types widen, array widths grow. When locked, the structural contract is frozen and any incoming entity that does not match is rejected. Lock is the right default for production systems with external producers, where silently accepting a widened shape would be a compliance or correctness failure. modelVersion is application-controlled; to change the contract after lock, the application bumps the version and registers the new schema for it — by submitting a comprehensive set of representative samples (the same mechanism as initial discovery; the samples themselves are not stored). Old revisions are never re-validated or re-cast; each remains valid under the model version active at write time. See Modeling entities for when to choose each mode and how to plan evolutions.

The wire format and field conventions for exported models (type descriptors, array representations, structural markers) are in the entity-model export reference.

History and temporal queries

Because transitions produce revisions rather than overwriting state, the full history of an entity is always retrievable. You can ask:

• “What did this entity look like at timestamp T?” — point-in-time reconstruction.
• “What transitions has this entity been through, and when?” — transition log.
• “Which version of the model was this revision validated against?” — schema lineage.

This is not an add-on audit layer bolted onto a mutable store; it is the storage model. See the API reference for the temporal-query grammar.