# Core Concepts

HakoRun identifies functions by path, distinguishes versions by timestamp, and offers stored and immediate execution.

## Function Paths

- Each function is identified by the `path` string given at upload (e.g. `math/add`) and is called at `/run/<path>`.
- A `path` containing `..` is rejected at upload (HTTP 400).
- Storage keys use the MD5 of `path`, not the raw string; see [Storage](/storage).
- Re-uploading a path replaces its language with the latest upload's.

## Versions

| Behavior | Description |
|----------|-------------|
| Version number | Unix seconds at upload time, returned as `version` by `/upload` |
| Default run | `/run/<path>` without `version` runs the latest version |
| Pinned version | `/run/<path>?version=<timestamp>`; a missing version returns 404 |
| Non-integer `version` | Treated as absent; runs the latest version |
| Same-second uploads | Two uploads to one path within a second share a version, and the later code overwrites the earlier |

## Stored Run vs Run-Now

| Mode | Endpoint | Code Source | Language Check |
|------|----------|-------------|----------------|
| Stored run | `POST /run/*path` | Storage backend (body `code`/`language` are overwritten) | At upload |
| Run-now | `POST /run-now` | Request body, never stored | Per request; `code` must not be blank |

Both modes share one execution path once the code is resolved:

```mermaid
graph LR
    Body[getRunBody capped by CODE_MAX_SIZE] --> Run[run]
    Run -->|stream=false| Once[runScript]
    Run -->|stream=true| SSE[runScriptWithSSE]
    Once --> Cmd[sandbox.SandboxCommand]
    SSE --> Cmd
    Cmd --> Wrapper[wrapper reads stdin]
```

## Execution Lifecycle

- Every request starts a fresh sandboxed child process that exits when done; no state is shared.
- The deadline is `TIMEOUT_SCRIPT` plus 5 seconds; the process is killed on timeout.
- Non-stream mode responds once the process exits; stream mode pushes output while it runs, see [Responses and SSE](/responses).

## Related Pages

- [Script Runtime](/script-runtime)
- [Storage](/storage)
- [Resource Limits](/resource-limits)