Bundle Architecture

EdgeEmbed Runtime is a core + bundles platform. The core, EdgeEmbed Runtime, owns every runtime decision. A bundle declares the domain — and nothing else.

This page explains where the line is drawn and why.

The shape of a bundle

A bundle is a directory:

robotics_bundle/
├── manifest.json            metadata, version, entry points
├── events.json              the domain's event vocabulary
├── resources.json           contended resource classes and instances
├── intents.json             named runtime intents the policy can produce
├── actions.json             concrete actions the executor can dispatch
├── policy.json              rules mapping events → desired intents
├── action_mapping.json      intents → ordered action plans
├── concurrency.json         which actions can or cannot run together (optional)
├── assets/                  domain assets (models, lookup tables)
└── backends/                one HAL plugin per supported backend
    ├── robot_mock_plugin.c
    ├── robot_mock_plugin.manifest.json
    ├── robot_platform_plugin.c
    └── robot_platform_plugin.manifest.json

Everything in that directory is vocabulary: what events exist, what resources they contend for, what actions the system can take, and what the policy is when they collide. None of it contains orchestration logic.

What stays in the core

EdgeEmbed Runtime owns:

Responsibility	What it does
Event Manager	Normalises external requests, coalesces, rate-limits, priority-queues
Priority arbitration	Resolves competing events using policy-declared priorities
Policy Manager	Evaluates events against policy.json to produce desired intents
Action Planner	Expands intents into ordered action plans via action_mapping.json
Concurrency	Honors concurrency.json groups during planning and dispatch
Execution Engine	Dispatches actions, serialises per resource, tracks lifecycle
HAL boundary	Loads the bundle's HAL plugin and routes dispatched actions to it
Diagnostics	Counters, traces, structured config validation errors

The core never names a domain. It does not know what a "safe-stop" is, what a cliff means, or what the LED ring does. It only knows how to turn structured input into structured, ordered, observed output.

What stays in the bundle

A bundle owns:

Responsibility	What it ships
Vocabulary	events.json, resources.json, intents.json, actions.json
Behavior contract	policy.json, action_mapping.json, concurrency.json
Domain assets	Models, lookup tables, calibration data, anything the HAL plugin consumes
Platform glue	One C source file per backend, implementing the HAL plugin ABI

That is the entire surface a domain product adds.

Why this split exists

Three reasons.

Reusability. The orchestration code that arbitrates a robot safe-stop against a slow-down is the same code that would arbitrate camera pipelines against display overlays, or audio streams against alert tones. Writing it once and configuring it per domain is the difference between a one-product company and a platform.

Reviewability. Behavior changes live in JSON. A safety reviewer can read policy.json and action_mapping.json and see exactly what the system will do — without grepping C code or running it. Configuration is validated before init, so behavior drift becomes a CI-detectable diff, not a field incident.

Portability. The HAL plugin is the only platform-specific code in the whole stack. Swapping one platform backend for another, or Linux for QNX, is a HAL plugin swap — not a rewrite. The same robotics_bundle/ directory ships against every backend.

The integration consumer

An OEM application links against the EdgeEmbed Runtime library (libedgeembed.so) and includes one header:

#include <edgeembed.h>

Initialisation points the runtime at a bundle directory; from that moment on, every external API is generic (edgeembed_submit_event, etc.) and the bundle's events.json determines what the application is allowed to submit. The integration code never names a domain symbol either.

That is the test: if removing the bundle directory would break the application, the bundle is doing its job. If removing the bundle wouldn't break the application, the domain has leaked into the application code.

Where a bundle fits

A bundle is the first thing you ship on this architecture. The robotics demo bundle — a small AMR safe-stop controller — describes the events, resources, intents, actions, and policy contract for its domain; the runtime decides what to do. See Getting started to build and run it.