Skip to main content
entities.yaml declares the persistent typed fields of the entity a flow owns. It is the authority for what persists in entity state.
This replaces the retired package.yaml.entity_schema. The older model (embedded schema, grouped field sections, jsonb fields, inline nullable:) is no longer accepted.
entities.yaml

​
Rules

  • One entity type per flow. A flow declares at most one entity type.
  • State is not declared here. State is flow-scoped, declared in schema.yaml; entity.current_state is implicit. Declaring a state field is a contract error.
  • The envelope is platform-owned. The fields id, current_state, revision, created_at, updated_at, and flow_instance are implicit and must not be declared.

​
Writer coverage

Every declared field must have an initial value, a writer (a handler data_accumulation or compute, or an agent save_* tool), or an explicit _unused_reason. A field with none of these fails swarm verify with entity_writer_coverage. This forces you to state intent rather than leave a field silently unset. See Analyzer checks.

​
Reader coverage

The analyzer also reports entity_reader_coverage as informational lint_evidence when a declared field has no internal handler reader. That can be correct for fields written for audit, operator dashboards, API readers, or swarm entity view. In that case, add _unused_reader_reason to the field with a clear reason of at least 10 characters.
entities.yaml
_unused_reader_reason suppresses only entity_reader_coverage. It does not satisfy writer coverage, authorize a runtime/API read surface, or change persistence semantics. Use _unused_reason only when the field intentionally has no writer.

​
Field options

A field uses a terse form (field_name: TypeName) or a verbose block with:
​
string
required
A built-in scalar or a named type from types.yaml.
​
any
An explicit create-time value, overriding the type default.
​
boolean
When true, the field cannot be written after creation.
​
string
Documentation for the field.
​
string
A non-empty reason, at least 10 characters, explaining why a field intentionally has no writer. This suppresses entity_writer_coverage.
​
string
A non-empty reason, at least 10 characters, explaining why a field intentionally has no internal reader because it is used by external/operator readout. This suppresses only entity_reader_coverage.

​
Accumulator projection

A field may declare materialize_from: {node_id}.{accumulator_name} to hold a runtime-written typed copy of a same-flow node accumulator. The target must be a list of a named type. When the source and target item types differ, a project: mapping naming every target field is required. A materialize_from field is the sole runtime writer after initial:; any other authored write to it is invalid, and it is not agent-writable.

​
Companion field pattern

There is no Optional<T>. To distinguish “not yet written” from “written at the type default”, declare a boolean companion field: