Pulse: Running Kairo Applications

Pulse is the official Kairo runtime. It takes the compiled artifacts that Forge produces and executes them. Pulse handles everything that happens after the build: loading artifacts, validating runtime metadata, resolving the declared entrypoint, creating the root execution boundary, running the application’s async scheduler, and mapping the application’s outcome to a process exit code. Pulse does not compile source code and does not resolve packages — those responsibilities belong to Forge.

What Pulse does

When you invoke pulse run, Pulse performs the following steps in order:

Load artifacts

Pulse reads the Forge-built artifacts from the package’s build/ directory.

Validate runtime metadata

Pulse checks that all required metadata is present, that artifact versions are consistent, and that the declared runtime contract is compatible with this version of Pulse.

Resolve the entrypoint

Pulse locates the function named by the entry field in [application] within the loaded artifact.

Create the root execution boundary

Pulse establishes the root boundary that scopes the lifetime of the running application.

Invoke the entrypoint

Pulse calls the entrypoint function to start the application.

Run the async scheduler

Pulse drives the async scheduler for the lifetime of the application, dispatching tasks as they become ready.

Handle I/O and faults

Pulse exposes Pulse.Console.out and Pulse.Console.error for standard output and error output. Root faults (unhandled errors at the boundary) propagate to process termination.

Map completion to exit behavior

When the entrypoint returns (or a root fault occurs), Pulse maps the outcome to an exit code and performs a clean runtime shutdown.

Commands

`pulse validate`

pulse validate [package-root]

Validates the Forge artifacts in the given package root — or in the current directory if no path is provided — without executing the application. Pulse checks that all required artifact files are present, that metadata versions are internally consistent, and that the runtime contract declared in kairo.toml is compatible. Use this to confirm a build is runnable before deploying it.

# Validate artifacts in the current directory
pulse validate

# Validate artifacts in a specific package directory
pulse validate ./packages/Astra.Sales

Run pulse validate in your CI pipeline after forge build to catch contract mismatches and missing artifacts before they reach a deployment environment.

`pulse run`

pulse run

Loads and runs the application from the Forge-built artifacts in the current directory. Pulse validates the artifacts (same checks as pulse validate) before executing. If validation fails, Pulse exits with code 3 and reports the problem without starting the application.

# Build first, then run
forge build
pulse run

Pulse must be invoked from the package root (the directory containing kairo.toml and build/). It reads the manifest to locate the entry field and the build/ directory for artifacts.

Entrypoint signatures

The function named by the [application].entry field in your manifest must match one of the following signatures. Pulse accepts all of them:

Signature	Description
`public func main()`	Synchronous void entrypoint. Success maps to exit `0`.
`public func main(): Int32`	Synchronous integer entrypoint. The return value becomes the exit code.
`public func main(): Result<Int32, E>`	Synchronous result entrypoint. `Ok(n)` → exit `n`; `Failure(...)` → exit `1`.
`public async func main()`	Async void entrypoint. Completion maps to exit `0`.
`public async func main(): Int32`	Async integer entrypoint. The resolved value becomes the exit code.
`public async func main(): Result<Int32, E>`	Async result entrypoint. `Ok(n)` → exit `n`; `Failure(...)` → exit `1`.

// Simplest valid entrypoint
public func main() {
    Pulse.Console.out("Hello, world!")
}

// Exit code control
public func main(): Int32 {
    let result = runApp()
    return result.isOk() ? 0 : 1
}

// Full async result entrypoint
public async func main(): Result<Int32, AppError> {
    let outcome = await bootstrap()
    return outcome
}

Exit codes

Pulse maps every possible application outcome to a well-defined process exit code:

Exit code	Cause
`0`	Successful completion of a void entrypoint, or `Result.ok(0)` return.
n	`Int32` return value n from an integer entrypoint.
`1`	`Result.failure(...)` returned from a result entrypoint.
`2`	An unhandled root fault propagated to the execution boundary.
`3`	Startup or artifact failure (missing artifacts, contract mismatch, invalid metadata).

Exit code 3 means Pulse could not start the application at all — the problem is in the artifact or runtime configuration, not in your application logic. Run pulse validate to diagnose artifact issues without attempting execution.

What Pulse does not do

Pulse is a runtime only. It has a narrow, well-defined scope:

Pulse does not compile source code. Run forge build to produce artifacts first.
Pulse does not resolve or restore packages. Run forge restore to update forge.lock.
Pulse does not accept source .ak files directly. It only loads Forge-built artifacts from build/.
Pulse rejects incomplete or incompatible artifacts. If metadata is missing or the runtime contract version does not match, Pulse exits with code 3 and reports a PLS-prefixed diagnostic.

Diagnostic codes

Pulse emits diagnostics with the PLS prefix when it encounters problems with artifacts or runtime configuration:

Prefix	Subsystem
`PLS`	Pulse runtime (artifact validation, contract compatibility, entrypoint resolution)

[PLS-0003] Runtime contract mismatch: artifact declares contract "0.1",
           but this Pulse version supports "0.2" and above.
           Rebuild with a compatible version of Forge.

Next steps

Forge

Build your application artifacts with Forge before running them with Pulse.

Manifest

Configure your entrypoint and runtime contract in kairo.toml.

Get Started

Language

Packages & Modules

Toolchain

Ecosystem

Pulse: Running Kairo Applications

What Pulse does

Commands

`pulse validate`

`pulse run`

Entrypoint signatures

Exit codes

What Pulse does not do

Diagnostic codes

Next steps

Forge

Manifest

​What Pulse does

​Commands

​pulse validate

​pulse run

​Entrypoint signatures

​Exit codes

​What Pulse does not do

​Diagnostic codes

​Next steps

Forge

Manifest

What Pulse does

Commands

`pulse validate`

`pulse run`

Entrypoint signatures

Exit codes

What Pulse does not do

Diagnostic codes

Next steps