ADR 001: Runtime Design

Status

Accepted.

Context

IvoryOS needs to expose Python objects, workflow scripts, direct-control calls, queue state, pause/resume controls, and generated UI forms through one running Flask application.

The runtime must support:

  • one active deck per running process;

  • direct-control calls from the UI, API clients, and generated proxies;

  • workflow execution with preparation, main script, and cleanup phases;

  • cooperative pause, retry, stop-pending, and stop-current controls;

  • serialized access to instruments that are not safe for concurrent calls.

Decision

IvoryOS keeps runtime state in a process-wide GlobalState singleton. The active deck, interface schema, building blocks, optimizer registry, runner status, notification handlers, and shared runner lock live there.

Direct-control calls and workflow runners use that shared state instead of copying the deck into local module-level caches. The active deck is configured when ivoryos.run(__name__) starts the server.

Workflow control is cooperative. IvoryOS does not kill a running Python method or hardware driver call mid-call. Stop and pause controls take effect at action boundaries or explicit safe wait points.

Consequences

  • A running IvoryOS process has one active deck.

  • Instrument calls can be serialized through the shared runner lock.

  • Routes, parsers, and runners can resolve the active deck consistently.

  • Long-running or blocking driver calls must return before pause or stop controls can fully take effect.

  • Integrations that need multiple physical servers should run multiple IvoryOS processes and connect them through client/proxy APIs.