O-Lang Protocol Specification v1.1

1. Purpose & Philosophy

1.1 The Autonomy Crisis in AI Systems

Current AI architectures grant unbounded autonomy to agents and LLMs. Developers construct workflows that:

• execute arbitrary code with full system permissions
• make decisions without audit trails or policy constraints
• bypass governance through embedded orchestration logic
• produce non-reproducible, non-deterministic outcomes

This creates unacceptable risk in regulated environments (healthcare, finance, government) where AI decisions impact human lives, compliance, and legal liability.

1.2 From Agents to Governance

The industry is transitioning from autonomous agents to governable systems. O-Lang enables this shift by establishing a runtime governance boundary that separates AI intent from execution authority:

• Intent ≠ Execution — Workflows declare what should happen; the kernel governs whether and how it may execute
• Policy Mediation — Every capability invocation is mediated by the kernel against explicit allow-lists, constraints, and resolver contracts — never trusted
• Observable Meaning — Symbol validity, undefined references, and semantic violations are surfaced as structured, auditable events — never hidden or fabricated
• Deterministic Auditability — Identical inputs produce identical execution traces across all compliant kernels, enabling regulatory verification and forensic replay

This boundary ensures that AI systems remain governable, certifiable, and institutionally trustworthy — even when using non-deterministic components like LLMs.

1.3 The Governance Gap

Existing orchestration frameworks (LangChain, LlamaIndex, etc.) operate inside application code, where:

• developer authority = execution authority
• tools inherit permissions implicitly
• no runtime enforcement layer exists
• compliance is retrofitted, not built-in

O-Lang closes this gap by providing a runtime-enforced governance boundary that exists outside application code.

1.4 What O-Lang Provides

O-Lang defines a portable protocol for:

• Portable execution format — Workflows are language-agnostic, versionable, and human-readable
• Runtime-enforced policy boundary — Capabilities are explicitly allowed, never trusted
• Capability invocation contract — Standardized I/O, sandboxing, and error handling across all capabilities
• Semantic enforcement of workflow meaning — Symbols must exist in reality, not just in intent

O-Lang does not execute business logic.
It governs how logic is invoked, constrained, observed, and audited — transforming AI from autonomous agents to governable, certifiable systems.

1.5 Trust vs Conformance

O-Lang distinguishes between conformance and trust:

• Conformance validates that a resolver declaration adheres to the O-Lang Resolver Contract (inputs, outputs, steps, failures).
• Trust is established by the runtime kernel, which enforces policy, validates capability behavior, and mediates all external interactions.

A resolver may be conformant but not trusted — certification of entire packages (including runtime behavior) is a separate governance layer beyond static conformance.

1.6 Key Definitions

The following terms have specific meanings in the context of the O-Lang Protocol:

• Kernel: A semantic runtime that parses workflows, enforces policy, validates capabilities, and emits auditable execution traces. It is not an executor of business logic.
• Workflow: A declarative, human-readable document that defines a sequence of steps, inputs, outputs, and failure modes. It is a semantic contract, not a script.
• Capability: An external, executable component (e.g., @o-lang/notify-telegram) that performs side effects (e.g., HTTP calls, LLM inference). Capabilities are explicitly allowed but never trusted by the kernel.
• Resolver (Conformance Context): A conformant workflow that adheres to the O-Lang Resolver Contract (Section 14). It is a static declaration with defined inputs, outputs, steps, and failures. This is what is validated by the official test harness.
• Symbol: A named value referenced in a workflow. Symbols include inputs, step outputs (Save as), emitted values, and persisted data. A symbol is either defined (exists in reality) or undefined (referenced but not produced) — never null or empty.

These definitions supersede colloquial or implementation-specific usage.

2. Core Concepts

2.1 Kernel (Normative)

The Kernel is a semantic runtime, not an executor.

It is responsible for:

• parsing workflows
• validating capability eligibility
• enforcing execution policy
• tracking symbol lifecycles
• detecting semantic violations
• producing auditable outputs

2.2 Workflow

A Workflow is a semantic contract, not a script.

Characteristics:

• deterministic step order
• immutable inputs
• symbol-tracked outputs
• stateless execution
• observable failure modes

Example:

Workflow "HR Summary" with policy_query, user_id
Allow resolvers:
- doc-search
- llm-groq
- notify-telegram
Step 1: Ask doc-search "{policy_query}" Save as doc
Step 2: Ask llm-groq "Summarize for staff:
{doc.text}" Save as summary
Step 3: Notify {user_id} using Telegram Save as notification
Return summary

This workflow demonstrates:

• Deterministic order: Steps execute sequentially
• Immutable inputs: policy_query and user_id are read-only
• Symbol-tracked outputs: doc, summary, and notification are explicitly declared via Save as
• Observable failure: If llm-groq fails, summary remains undefined — the kernel surfaces this as a semantic violation
• Stateless execution: No global state; all context flows through symbols

Note on typing: Input types are inferred from usage context or declared in the compiled resolver contract. The workflow syntax prioritizes readability; type safety is enforced at conformance time.

2.3 Capability

A Capability is an external executable boundary.

Capabilities may be:

• HTTP services
• local binaries
• containers
• edge services
• IoT hardware interfaces

Capabilities are never trusted.
All capability results are validated by the kernel, not assumed correct.

2.4 Concrete Domain Example: Healthcare Resource Allocation

Scenario: An AI triage system proposes allocating ICU beds during a public health emergency.

Outcome: Non-compliant action (notification without approval) is blocked. Full audit trail generated. No silent failure.

This example demonstrates O-Lang’s core value: runtime governance separates AI intent from execution authority. The AI may propose actions, but the kernel enforces policy before any real-world effect occurs.

3. Syntax Grammar and Keywords (Normative)

O-Lang workflows MUST conform to the Linear Declarative Workflow Form (LDWF): a line-oriented, human-readable, machine-strict format.

3.1 General Syntax Rules

• Whitespace is insignificant except within quoted strings
• All keywords are case-insensitive but conventionally capitalized
• Blank lines MUST separate logical sections and steps
• Indentation is semantic-neutral and MUST NOT affect parsing
• One intent per line (e.g., Save as x, not Save as x and notify)

3.2 Workflow Declaration

Workflow "<name>" [with <input>[, <input>]*]

• <name>: quoted string
• <input>: workflow input symbol (alphanumeric)
• Inputs are immutable and available in initial context

3.3 Allowed Resolvers Block

Allow resolvers:
- <capability-name>
[ - <capability-name> ]*

• MUST appear once, after Workflow
• Only listed capabilities may be invoked
• Capability names are normalized identifiers

3.4 Step Declaration

Steps are declared sequentially. Step numbers are optional but, if used, MUST be monotonically increasing positive integers.

[Step <n>:] <action> [Save as <symbol>]

• Blank lines MUST separate steps
• <symbol> is normalized to alphanumeric + underscore

Action Types

Kernels MUST support the following action forms:

3.5 Control Flow

Conditional Blocks

If <condition>:
<step-or-action>+
[Else:
<step-or-action>+]
EndIf

• <condition>: comparison involving system-provided symbols only (e.g., {score} > 80)
• User-defined symbols MAY be used in conditions (updated from v1.0)
• Blocks MUST be explicitly closed with EndIf

Parallel Execution

Run in parallel [for <duration>]:
<step-or-action>+
End

• <duration>: number + unit (s, m, h, d)
• Context is snapshotted before block entry

Escalation Chains

Run in parallel with escalation:
Level 1: [Immediately | Within <duration>]
<step-or-action>+
Level 2: Within <duration>
<step-or-action>+
End

• Reserved for multi-level timeout escalation
• Kernels MUST parse but MAY treat as standard parallel blocks in v1.1

3.6 Constraints

Global or per-step constraints define execution parameters:

Constraint: max_generations = <number>
# Within a step:
Step 1: Ask LLM "..."
Constraint: temperature=0.7
Constraint: tools=["search", "calc"]

• Constraints are key-value pairs
• Values may be strings, numbers, or JSON arrays

3.7 Return Statement

Return <symbol>[, <symbol>]*

• Declares workflow outputs
• Referenced symbols MUST be produced by steps

3.8 Formatting & Linting (Normative)

4. Semantic Execution Model (Normative)

4.1 Symbols

A symbol is any named value referenced in a workflow:

• inputs
• step outputs (Save as)
• emitted values
• persisted values

Symbols are tracked explicitly by the kernel.

4.2 Symbol Lifecycle

Declared / Referenced
↓
Produced by Capability
↓
Available in Context
↓
Consumed or Persisted
↓
Observed or Missing

4.3 Semantic Enforcement Rules

Undefined ≠ null ≠ empty.

4.4 Fail-Fast Execution Semantics (Normative)

O-Lang enforces fail-fast semantics by default. If a step fails to produce a required symbol, any subsequent step that references that symbol will halt with a UNRESOLVED_PLACEHOLDERS error.

Example:

• Step A succeeds → produces account_info
• Step B fails → account_info remains undefined
• Step C references ${account_info.balance} → kernel halts with UNRESOLVED_PLACEHOLDERS

This ensures workflows never proceed with corrupted or incomplete state.

4.5 Explicit Partial Success (Normative)

Workflows may implement explicit partial success using conditional guards:

If account_info.exists:
  Step 2: Ask llm "Balance is ${account_info.balance}"
Else:
  Step 3: Notify admin "Account not found"
EndIf

In this pattern:

• Step 1 always executes
• Step 2 executes only if account_info.exists is truthy
• Step 3 executes only if the condition fails

All execution paths are explicit, auditable, and policy-governed — never implicit or hidden.

4.6 Determinism Boundary (Normative)

4.7 Kernel Execution Invariant: Canonical Action Form (Normative)

The kernel MUST canonicalize surface syntax (Ask, Use) into execution form (Action) BEFORE dispatching to resolvers.

Rationale: Resolvers are implementation details that should not parse workflow syntax. Canonical form enables deterministic execution traces, prevents resolver coupling to evolving DSL syntax, and enables safe external resolver protocols (HTTP endpoints expect Action prefix).

Violation: Kernel MUST throw [O-Lang INTERNAL] error before resolver dispatch if invariant broken. This indicates a kernel bug, not workflow authoring error.

4.8 State Transition Semantics (Normative)

O-Lang workflows execute as a discrete-state transition system:

• State: A finite map S = { symbol₁ → value₁, ..., symbolₙ → valueₙ } representing the current context.
• Transition function: δ : S × Step → S ∪ Error
  • Each step consumes the current state S and produces a new state S' by adding resolved symbols (via Save as) or halting on error.
  • No step mutates existing symbols; all updates are monotonic additions.
• Initial state: S₀ = { input₁ → value₁, ..., inputₖ → valueₖ }
• Final state: S_final after last step, filtered by Return clause.

Key properties:

• Monotonicity: S ⊆ S' — symbols are never removed or overwritten.
• Isolation: Parallel steps operate on snapshots of S, not shared mutable state.
• Observability: Every transition is logged in the execution trace.

5. Parallel and Timed Execution Semantics (Normative)

5.1 Parallel Block Lifecycle

1. Kernel snapshots current context
2. Launches all steps in block concurrently
3. Waits up to <duration> (if specified)
4. Cancels any incomplete steps after timeout
5. Merges only successfully resolved symbols into post-block context
6. Sets timed_out = true if any step was cancelled

Concurrency model: Parallel steps execute logically simultaneously but physically asynchronously. The kernel guarantees:

• No shared mutable state between steps (each receives an immutable snapshot of context),
• Deterministic merge order (symbols merged in declaration order, not completion order),
• Bounded execution (timeout enforces liveness).

Thus, parallel execution is deterministic if and only if all invoked resolvers are deterministic.

5.2 Symbol Merge Rules

• Resolved symbol: included in final context
• Unresolved symbol: discarded (not set to null or undefined)
• Partially failed block: still progresses to next workflow step
• No implicit error propagation: failure is observable but not exceptional

5.3 Escalation Chains (Reserved)

Syntax is reserved for multi-level timeout escalation. Not part of v1.1 core, but kernels MUST ignore unknown block types gracefully.

6. Capability Contract and Multi-Language Support

6.1 Capability Invocation

Capabilities are invoked via function-call syntax:

medical-api("{symptoms}") Save as diagnosis

• Kernel resolves function name against Allow capabilities list
• If not allowed, kernel skips step and logs policy violation

6.2 Input/Output Contract

• Input: JSON-serializable context subset (only referenced symbols)
• Output: Single JSON value or error
• No side effects outside declared and kernel-permitted boundaries

6.3 Multi-Language Implementation

Capabilities may be implemented in any language that can:

• Read JSON input from stdin or HTTP request
• Write JSON output to stdout or HTTP response
• Exit with code 0 (success) or non-zero (failure)

Examples:

• Python: HTTP resolver with Flask/FastAPI
• JavaScript: Node.js subprocess or HTTP endpoint
• Rust: Native binary accepting JSON over stdin
• Go: gRPC or REST service
• Shell: Script that reads $1 as JSON and outputs result

6.4 Kernel-Capability Interface

Kernels MUST support at least one of:

• HTTP: POST /resolve with JSON payload
• Subprocess: spawn binary with JSON arg
• In-process: language-native function call (for embedded use)

Security note: Kernels operating in secure mode MUST restrict capability interfaces to sandboxed channels (e.g., HTTP-only). In-process execution is permitted only in development or trusted environments.

The choice of interface is implementation-defined — the protocol only specifies what is called, not how.

6.5 Capability Declaration (Normative)

Every capability MUST expose a static declaration document describing its behavior.

{
"id": "capability.health.triage",
"intents": ["diagnose"],
"input_schema": {
"symptoms": "string[]"
},
"output_schema": {
"risk_level": "string"
},
"constraints": {
"jurisdiction": ["NG"]
}
}

6.6 Resolver Safety Contract (Normative)

Context: A resolver is any external component (database, API, sensor, LLM, or custom service) that produces values for workflow symbols. In conventional systems, resolvers are called tools (LangChain), nodes (n8n), or functions (OpenAI). In O-lang, resolvers execute outside the kernel and must honor explicit failure semantics — never fabricating data or silently falling back to hardcoded values when inputs are invalid.

Resolvers MUST honor explicit failure semantics — never fabricating data or silently falling back to hardcoded values when inputs are invalid.

Rationale: Silent fallbacks turn configuration errors into data corruption errors. They violate determinism, destroy auditability, and create unacceptable risk in safety-critical domains (finance, healthcare, government).

Example violation (implicit retry + fallback): Resolver receives valid customer_id: 12345 → DB times out → resolver internally retries 3× → still fails → returns hardcoded balance: 5000 with no error. Execution trace shows balance: DEFINED — failure is structurally invisible.

Compliant pattern (explicit workflow retry): Resolver fails immediately on first timeout → returns DATABASE_TIMEOUT → kernel halts with balance: UNDEFINED → workflow's explicit Loop count=3 directive commands retry → trace shows attempt_1: UNDEFINED, attempt_2: UNDEFINED, attempt_3: DEFINED (2500). All retry decisions are auditable and bounded.

See Appendix A for detailed execution trace comparison and cross-domain applicability.

7. Runtime Observability

Means:

• The symbol existed in intent
• It did NOT exist in reality
• The kernel refused to lie

This is semantic truth enforcement.

In most frameworks:
this would silently write null, "", or crash later.

O-Lang makes meaning observable.

7.1 Execution Trace Contract (Normative)

{
"workflow": "string",
"intent": "string",
"step": "number | null",
"capability": "string | null",
"symbols_produced": ["symbol"],
"symbols_missing": ["symbol"],
"policy_decision": "allowed | blocked | skipped",
"timestamp": "ISO-8601",
"trace_id": "opaque-string"
}

• Trace fields MUST be semantically equivalent across kernels
• Trace emission MUST NOT be optional
• Traces MUST correspond to actual execution events

8. Security Model

O-Lang directly addresses the Confused Deputy Problem (Hardy, 1988).

Why orchestration-in-code fails:

• execution authority == developer authority
• tools inherit permissions implicitly
• no runtime enforcement layer

O-Lang solution:

• workflow intent ≠ execution authority
• capabilities explicitly allowed
• kernel mediates every invocation

Capabilities never gain power they weren't granted.

9. Error Semantics (Normative)

All errors emitted by the kernel MUST be structured and classified.

{
"code": "SYMBOL_UNDEFINED",
"message": "Symbol medical_summary was referenced but never produced",
"step": 4
}

9.1 Standard Error Codes

• INVALID_OLANG
• UNDECLARED_CAPABILITY
• POLICY_VIOLATION
• CAPABILITY_FAILURE
• SYMBOL_UNDEFINED
• TIMEOUT
• SEMANTIC_VIOLATION

10. IoT & Edge Architecture

[ Sensor / Actuator ]
↓
[ Edge Capability ]
↓
[ O-Lang Kernel ]
↓
[ Policy / Audit / Control Plane ]

Why O-Lang fits IoT better than code orchestration:

• offline-safe
• deterministic replay
• hardware isolation
• auditable decisions
• no dynamic code execution

O-Lang governs when hardware is touched — not how.

11. LangChain Integration

11.1 LangChain as a Capability

LangChain is just another capability.

11.2 Complementary Usage

LangChain builds the flow → O-Lang governs execution.

12. Implementation Guidance

O-Lang is defined by its protocol semantics, not by any specific implementation. Multiple kernel implementations are expected and encouraged.

12.1 Reference Implementation

A reference implementation is provided to:

• demonstrate protocol semantics
• serve as a conformance baseline
• enable rapid ecosystem adoption

The reference implementation is not normative — the specification takes precedence in all cases.

12.2 Conformance Requirements

All compliant implementations MUST:

• implement all normative requirements in this specification
• produce equivalent semantic execution traces for identical inputs
• pass all required tests in the official O-Lang Conformance Test Suite (OCTS)
• Passing conformance tests does not imply runtime trust or certification.

Implementation language, performance characteristics, and internal architecture are not constrained by this specification.

12.3 Ecosystem Interoperability

Kernels in different languages MUST interoperate at the protocol level:

• identical workflows produce equivalent contexts
• capability contracts are language-agnostic
• audit trails are structurally consistent

This ensures portability across environments while preserving governance guarantees.

12.4 Feature Compliance Matrix

13. System Classification

O-Lang is not a developer framework, scripting language, or orchestration engine. It is a semantic governance protocol designed for systems-level integration in regulated domains.

13.1 What O-Lang Is Not

• Not a DSL — O-Lang does not encode domain logic or business rules; it governs how such logic may be invoked.
• Not an operational workflow engine — O-Lang does not manage queues, retries, or infrastructure; it validates semantic correctness before any execution occurs.
• Not a LangChain alternative — It does not replace developer-facing composition tools; it governs their runtime behavior when used in regulated contexts.

13.2 What O-Lang Is

• A runtime governance boundary — Enforces separation between AI intent and execution authority via kernel-mediated capability invocation.
• A semantic execution layer — Validates symbol validity, placeholder resolution, and policy compliance before side effects occur.
• An AI systems primitive — Provides the missing contract between application intent and infrastructure execution in healthcare, finance, and public-sector AI.
• A minimal, verifiable runtime — The kernel is the enforcement boundary — not a wrapper around existing agent frameworks.

13.3 Non-Goals for v1.1

This specification intentionally does not define:

• Capability handler certification processes
• Package registry governance models
• Economic trust or reputation mechanisms
• Runtime sandboxing implementation details

These topics are reserved for future versions under O-Lang Foundation governance. This narrow scope ensures the protocol remains focused on its core mission: runtime-enforced separation of intent from execution.

14. Final Principle

15. Conformance Model (Normative)

15.1 Definition of Conformance

An implementation is considered O-Lang conformant if and only if it:

• implements all normative requirements in this specification
• produces equivalent semantic execution traces for identical workflows
• passes all required tests in the official O-Lang Conformance Test Suite (OCTS)

15.2 Version Binding

15.3 Test Traceability

Every conformance test MUST reference one or more normative clauses in this specification. No test may assert behavior not explicitly defined herein.

16. Formal Semantics Summary (Informative)

O-Lang can be modeled as a guarded transition system:

• States: Context ∈ Symbol ⇀ Value
• Actions: Step ∈ { Action, Ask, Use, ... }
• Transitions: Context → Context via resolver-mediated updates
• Guards: If conditions, Allow resolvers, Constraint clauses
• Final states: Defined by Return clause

This model ensures:

• Safety: No transition occurs without explicit declaration.
• Liveness: Timeouts prevent infinite hangs.
• Auditability: Every transition is observable.

Unlike Turing-complete agent frameworks, O-Lang constrains expressivity to enforce governance — making it suitable for regulated domains.

Appendix A: Failure Handling Patterns — Explicit vs Implicit Retries (Informative)

Terminology bridge: In O-lang, a resolver is any external component that produces symbol values — equivalent to tools in LangChain, nodes in n8n, functions in OpenAI Assistants, or sensors/actuators in IoT systems. The critical distinction is not naming, but where failure handling occurs: conventional systems embed retry…enforces failure visibility outside tools at the kernel boundary (governance-level).

Domain applicability note: The examples below use a financial balance-check scenario for concrete illustration, but the safety principles apply universally across domains including healthcare diagnostics, IoT sensor fusion, government service delivery, agritech monitoring, and any system where transient infrastructure failures must not result in silent data fabrication.

A.1 Execution Trace Comparison: Explicit Workflow Retries Preserve Auditability

Trace always shows: attempt_1: UNDEFINED → attempt_2: UNDEFINED → attempt_3: DEFINED (2500). No path exists for silent corruption.

A.2 Critical Distinctions: Where Retry Authority Resides

Why this matters in connectivity-constrained environments: In settings where network flakiness is the norm (not the exception) — Nigerian USSD banking, rural IoT deployments, edge healthcare diagnostics — conventional systems that "gracefully degrade" by fabricating values aren't graceful. They're structurally unsafe. O-Lang's explicit-retry model ensures temporary unavailability is preferable to permanent corruption.