> ## Documentation Index
> Fetch the complete documentation index at: https://docs.astrakairo.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Pulse Runtime Reference: pulse validate and pulse run

> Reference for the Pulse runtime commands, entrypoint signatures, exit codes, and diagnostic codes for running Kairo applications.

Pulse is the Kairo runtime environment. It takes the artifacts produced by `forge build` and either validates them or executes your application. Pulse does not compile source code or resolve package dependencies — it works exclusively with pre-built artifacts. The Pulse CLI exposes two commands: `pulse validate` for pre-flight checks and `pulse run` for launching your application. This page is the complete reference for both commands, valid entrypoint signatures, exit codes, and Pulse diagnostic codes.

## `pulse validate`

Validates all Forge artifacts produced by `forge build` without executing any application code. Use `pulse validate` to confirm that a build output is well-formed before deploying to a target environment.

```bash theme={null}
pulse validate [package-root]
```

If you omit `package-root`, Pulse uses the current working directory.

**What it checks:**

* **Presence** — all required artifact files exist under `build/` and `.forge/`.
* **JSON readability** — manifest and plan files are valid, parseable JSON.
* **Schema versions** — artifact schema versions match the expected Pulse version.
* **Application kind** — the `application` field in `kairo.toml` is a recognised kind.
* **Entrypoint metadata** — the declared entrypoint function is present and has a valid signature.
* **Cross-artifact consistency** — the build plan and output manifest agree on module names, entrypoints, and artifact paths.
* **File existence** — every path referenced in the manifest resolves to an actual file on disk.

**What it does NOT do:**

* `pulse validate` does not execute any application code.
* It does not compile source or resolve packages.
* It does not run test cases or perform business-logic checks.

```bash theme={null}
pulse validate ./dist/my-app
```

<Note>
  Run `pulse validate` in your deployment pipeline after `forge build` and before `pulse run` to catch artifact problems early, without starting your application.
</Note>

## `pulse run`

Loads and executes a Kairo application from pre-built Forge artifacts.

```bash theme={null}
pulse run [package-root]
```

If you omit `package-root`, Pulse uses the current working directory.

**What it does:**

* Runs `pulse validate` internally as a pre-flight step. If validation fails, the application does not start.
* Reads `[application].entry` from `kairo.toml` to locate the entrypoint function.
* Loads the compiled application artifacts from `build/`.
* Executes the entrypoint function.
* Returns the process exit code derived from the return value (see [Exit Codes](#exit-codes)).

**Requirements:**

* Artifacts must have been produced by `forge build` for the current source state.
* The entrypoint function must match one of the valid signatures listed below.
* `kairo.toml` must declare `[application].entry`.
* Artifacts with missing or incompatible runtime metadata are rejected before any application code runs.

<Warning>
  `pulse run` does not rebuild your project. If you modify source files, run `forge build` before `pulse run` to ensure you are executing current code.
</Warning>

## Entrypoint Signatures

The function named by `[application].entry` in `kairo.toml` must match one of the following signatures. Pulse infers the exit-code behaviour from the return type.

| Signature                                    | Exit code behaviour                                                |
| -------------------------------------------- | ------------------------------------------------------------------ |
| `public func main()`                         | Always exits `0` on completion                                     |
| `public func main(): Int32`                  | Return value becomes the exit code                                 |
| `public func main(): Result<Int32, E>`       | `Result.success` → declared exit code; `Result.failure` → exit `1` |
| `public async func main()`                   | Always exits `0` on completion                                     |
| `public async func main(): Int32`            | Return value becomes the exit code                                 |
| `public async func main(): Result<Int32, E>` | `Result.success` → declared exit code; `Result.failure` → exit `1` |

Any signature not listed above is rejected by `pulse validate` with a `PLS` diagnostic error.

<Note>
  The entrypoint function name is controlled by `[application].entry` in your manifest — `main` is the recommended convention, not a hard requirement. The function must be `public`.
</Note>

## Exit Codes

| Exit code | Meaning                                                      |
| --------- | ------------------------------------------------------------ |
| `0`       | Successful completion (void entrypoint, or `Result.success`) |
| `1`       | Application returned `Result.failure(...)`                   |
| `2`       | Uncaught root fault during execution                         |
| `3`       | Startup or artifact validation failure                       |
| *n*       | Entrypoint returned integer value *n*                        |

<Note>
  Exit code `3` is emitted by Pulse itself when artifact validation fails during `pulse run`. Your application code never runs in this case.
</Note>

<Tip>
  When a `pulse run` fails with exit code `3`, run `pulse validate` directly to see the full list of failing checks with their `PLS` diagnostic codes before filing a bug report.
</Tip>

## Pulse Diagnostic Codes

All diagnostics produced by the Pulse runtime carry the `PLS` prefix followed by a numeric identifier. Pulse diagnostics cover runtime conditions such as startup failures, artifact validation errors, runtime contract incompatibilities, and uncaught root faults. They are not compiler diagnostics.

Pulse runtime diagnostics are emitted to standard error in the standard process-hosted application model.