Execution Model

Execution Model

Authoritative rule: agents/rules/execution-model.md · Engineer-facing reference: Ephemeral Blueprints and the Compute-Data Boundary

TL;DR — the foundational shape

Before designing any feature, integration, or operational change, measure the proposal against this shape:

• Gateway = gatekeeper only. Session auth, authorisation, SSE / callback delivery, subscription routing. Never reads or writes domain data on behalf of a client.
• Workers = atomic compute blocks. Stateless. Claim a block, hydrate inputs from the shared cache, execute one tool, write outputs to the cache, emit boundary events, release the slot.
• Playbooks = ephemeral blueprints. Control flow and policy for a request. Invoked on demand; no resident state between invocations beyond what the event log records.
• Shared cache = state vehicle between blocks. Arrow IPC, scoped to execution_id + step. Rebuildable from the event log.
• Event log = source of truth. Append-only; immutable. Replay reproduces state for any past time.

Hard rules derived from the shape

Data access rule

Any data touch (read, write, projection, subscription, third- party API) happens inside a playbook step under that playbook's policy block. Clients never reach a database directly. The gateway never reaches a database to satisfy a client request.

Secrets and credentials rule

• Business-logic credentials (Auth0 / Duffel / Amadeus, tenant DSNs, OAuth secrets, signing keys) live in the NoETL keychain; playbooks reference by alias.
• Platform / runtime credentials (worker's NATS connection, server's signing key) live in pod env / k8s Secrets.

Ephemeral execution rule

No persistent per-tenant AI-agent processes or MCP servers. Both "AI agent" and "MCP server" are dispatched on demand and release their slots when blocks complete.

Callback / hook rule

A block must not hold a worker slot waiting for an external operation that takes more than a few seconds. Capture the callback subject, return, free the slot, resume on the callback. See Umbrella: Container Tool Callback for the canonical instance.

Decision tree for new work

1. Initiates work / gates access / routes responses → gateway.
2. Touches data / external API / composes operations under business rules → playbook in catalog.
3. Executes a unit of computation → worker tool. Add a new tool kind only if no existing one fits.
4. Needs shared state between blocks → shared cache.
5. Waits on something external → callback / hook pattern. Never hold a slot for the wait.

Why this is load-bearing

Per the authoritative rule:

The shape is the platform's "knowhow" for cost-effective and performance-optimized agentic AI computation.

Concretely:

• No persistent agent infra to monitor or pay for between requests.
• Adding integrations is a catalog row, not a new deployment.
• Workers can be added, removed, or restarted freely without data loss; state lives in the cache + event log.
• Audit, replay, retry, and schema evolution have one home (the playbook policy block).

When reviewing a proposal: "does this honor the boundary?" If not, push back before implementation lands.