OPAL

OPAL (Operator Permission and Access Layer) is the single command surface every operator — you, an automation rule, or a connected language model — uses to make Korall Engineering™ do something.

The one-sentence version

Every operation in Korall Engineering™ that does something — capture a screenshot, pair with a node, list mounted hives, run a diagnostic, flash firmware — is wrapped as an OPAL Task. The same task runs the same way whether you click it, schedule it, or an LLM invokes it; only the permission check changes.

Why OPAL exists

Korall Engineering™ is built around a hard separation between the embedded layer (real-time motor and sensor control, where mistakes are dangerous) and the strategic layer (high-level intent: "drive to the workshop, pick up the box"). See the Embedded-Strategic Barrier for the full architectural background.

OPAL is the strategic layer's interface to the embedded layer. Two consequences fall out of this:

• LLMs can drive Korall Engineering™ safely. A model never reaches a motor directly; it composes OPAL Tasks, and every task declares the permissions it needs. The operator can grant some scopes and not others, and revoke them at any time.
• Every operator goes through the same door. Clicking a button, a trigger firing at 9am, and a chat message from a model all execute the same OpalTask with the same code path. There is no "automation API" that diverges from "what the UI does."

The four pieces

A Task is to a button what a TaskPlan is to a workflow.

Three operators, one path

Every task invocation carries an operator type. The runtime checks permissions differently for each, but the task itself doesn't care who called it.

The same node.list task in all three cases. The same code. Different gate.

Permissions and audit

Each task declares the permission scope it needs (e.g. catalog.capture, node.create, filesystem.write). The operator's grants are checked at execution time:

• A Sentient operator always passes — you are the device's authority.
• An Automation operator passes if the rule was approved when it was authored.
• An LLM operator passes only if the model has been explicitly granted that scope. Unknown scopes pop a confirmation activity ("Allow this model to call filesystem.write?") that you can accept once or for the whole conversation.

Every execution — successful, failed, or denied — lands in OpalHistoryDatabase, visible in the OPAL History activity. So you can always see exactly what was done, by whom, against which Sentient and Node, with what parameters, and what came out.

Composition: TaskPlans

A single task does one thing. A TaskPlan is a JSON document chaining several:

{
  "steps": [
    {"task": "catalog.list_by_tag",  "tag": "trust"},
    {"task": "catalog.capture",      "id": "$1.results[0].id"},
    {"task": "filesystem.copy",      "from": "$2.image_path", "to": "/exports/"}
  ]
}

Outputs of one step are addressable by the next ($1.results[0].id). This is the surface LLMs use to express multi-step intent, and what the app uses internally for batch jobs and triggers.

Tasks come from domains

Each subsystem registers its own tasks into the central registry. The domains that exist today:

See the OPAL reference for the per-task catalogue.

Where you see OPAL in the UI

Common questions

Can I write my own task? Yes — see the internal developer documentation. A task is a C++ class with a name, a parameter list, a permission scope, and an execute() method. Once registered in any of the Register<Domain>Tasks files, it's available to every operator.

Are tasks stable across versions? Task names and parameter shapes are part of the public surface and follow semantic versioning. Renames go through a deprecation window with an alias.

Can a TaskPlan be interrupted? Yes — the runtime supports cooperative cancellation. Tasks that are interruptible (most I/O-bound work) can be canceled mid-execution; CPU-bound tasks finish their current step before stopping.

Does OPAL run only on the Hub? No — every node type (Agent, Remote, Hub) has an OPAL runtime. The set of available tasks differs by node: an Agent has access to its own actuators, a Remote can drive a paired Agent, a Hub can introspect any connected node.

Component reference