Governing model evolution

Documentation status: guide — see Maturity and evidence.

logiCells models are executable contracts. Changes therefore have compatibility consequences beyond source code.

Change categories

Review changes according to what they alter: concept, role, facet projection, persistence mapping, action, published action signature, event, process state, view binding, service mapping, or generated binding surface.

A published action signature change is a contract change. A role-path change can affect persistence, joins, and views. Renaming an event can break listeners. A process-state change can affect automation and agents. Changes to class identifiers can alter package resolution and existing references.

Evolution workflow

For an intentional contract change:

model change
  -> impact analysis
  -> update paired YAML/XML examples when applicable
  -> update declarative tests
  -> update generated/publication contracts
  -> run package/load smoke tests
  -> update documentation and migration notes

Keep small validated examples for important patterns. They serve both as documentation and regression material. Platform concepts and application examples must remain visibly separated.