Skip to content

Execution and Dataflow

Kedi executes source in order while preserving lexical declaration state. Parallel mode changes scheduling of model work, not the language result.

Compilation Phases

Compilation performs these conceptual phases:

  • resolve source documents and module paths;
  • parse syntax into an AST with source spans;
  • validate declarations, directives, package/profile graphs, and types;
  • execute the prelude and build the type environment;
  • compile custom types and procedures with captured lexical state;
  • construct the runtime's adapter, tool, MCP, approval, and execution engine.

Some failures are necessarily deferred. A dynamic Python type, backend expression, model connection, or tool call cannot be fully validated until execution reaches it.

Source Order

Assignments, imports, directives, and executable statements take effect where they appear:

[stage] = draft

@before() -> str:
  = <stage>

[stage] = final

@after() -> str:
  = <stage>

Procedures capture top-level agent/declaration state at definition, while value lookup follows the runtime's lexical environment. Use distinct names when an intentional snapshot should be obvious.

Value Environments

Lookup combines the current procedure frame, lexical closures, top-level globals, imported exports, prelude names, initial Python API globals, generated types, and compiled procedures according to their precedence.

Procedure-local names do not leak. A Python block receives visible Kedi values as globals, but new Python locals do not become Kedi bindings.

Native and Rendered Values

[count: int] = `3`
[message] = count\=<count>

count is a native integer; message is rendered text. A sole Python expression or procedure call on an assignment/return boundary can preserve its native result. Mixed literal text always renders.

This distinction drives dependency tracking and type validation. Avoid stringifying a collection merely to pass it to another typed procedure.

Model Templates

One >> block is one adapter call:

>> Incident: <incident>.
Affected service: [service: str].
Severity: [severity: str].

Kedi prepares substitutions, builds a combined output schema, invokes the active adapter, validates returned fields, and publishes them into the current environment.

Continuation lines in the same block cannot read outputs from that same call. Start another >> block for a dependency:

>> Incident <incident> affects [service: str].
>> Recommended owner for <service>: [owner: str].

Procedure Frames and Joins

Each invocation gets a frame for parameters, locals, nested declarations, agent state, and scheduled work. A procedure return is a join point: pending model results required by the return are forced and the native result is checked against the return annotation.

When a procedure exits, Kedi restores outer tool/profile frames. Scheduled work is drained before an exception leaves the frame so background model failures cannot disappear.

Failure Propagation

Parsing and structural failures prevent execution. Runtime type, Python, approval, tool, adapter, and model errors stop the affected flow and acquire Kedi trace frames as they propagate.

In parallel mode, all already-scheduled jobs are drained. The first failure is raised and additional concurrent failures are logged. Unconsumed calls still run and can fail; discarding a model response does not discard its error.