Runex

ADR-0006: Prefer Runtime-Loadable Ontology Data Over Python-Registered Business Logic ​

  • Status: Accepted
  • Date: 2026-05-19

Context ​

Business semantics in runex used to be a Python concern:

  • state machines registered in code
  • actions implemented as Python classes or imperative logic
  • new behavior added by editing code, restarting, and redeploying

The system now supports runtime-loaded ontology bundles:

  • (supertag ...)
  • (machine ...)
  • (action ...)

This changes where business logic lives. The question is whether that should remain the preferred architecture or merely be a convenience layer over Python-defined behavior.

Decision ​

We prefer runtime-loadable ontology data over Python-registered business logic for business semantics.

This means:

  1. object types, lifecycles, and reactive rules should primarily live in .scm bundles
  2. Python remains the place for:
    • runtime implementation
    • capabilities / kernels
    • channel adapters
    • low-level infrastructure
  3. business semantics should be data when the runtime can express them

The preferred framing is:

change behavior by loading ontology data, not by editing framework code

Why ​

runex's category depends on runtime malleability.

If business semantics stay primarily in Python:

  • agents cannot author or load new behavior at runtime
  • shell consumers cannot reason over one introspectable semantic surface
  • every semantic change becomes a code lifecycle event
  • the ontology runtime collapses back toward a conventional app backend

Runtime-loadable ontology data preserves the key distinction between:

  • the stable execution substrate
  • the mutable business model it runs

Alternatives Considered ​

1. Keep business semantics in Python classes/functions ​

Rejected.

Reason:

  • it makes runtime evolution expensive
  • it blocks agent-authored modeling
  • it ties semantic change to code deployment

2. Use .scm only for small rules, keep major behavior in Python ​

Rejected as the default.

Reason:

  • it creates a two-track semantic system
  • the boundary between "small" and "major" quickly becomes unstable
  • introspection and verification become incomplete

3. Generate Python from .scm and treat that as the real source ​

Rejected.

Reason:

  • it recenters code rather than data
  • it weakens the runtime-loading value proposition
  • it complicates debugging and authorship without restoring meaningful architectural simplicity

Consequences ​

Positive ​

  • business modeling becomes runtime-loadable
  • agents can author and refine ontology bundles directly
  • manifest() can expose a fuller semantic world
  • semantic evolution is decoupled from lower-level runtime code changes

Negative / Tradeoffs ​

  • the DSL must be carefully designed and documented
  • some developers will initially find data-driven semantics less familiar than Python callbacks
  • not every conceivable behavior belongs in .scm; the boundary still requires judgment

We accept these costs because the system's point is not only to execute business rules, but to make them runtime-operable.

Implications ​

  • feature work should ask first whether a new behavior belongs in ontology bundles before adding Python business logic
  • docs should continue separating:
    • ontology authoring
    • extension authoring
    • runtime architecture
  • Python-side additions should justify why they cannot be expressed as runtime-loaded semantics