Metadata-Version: 2.4
Name: piarun
Version: 0.0.3
Summary: piarun: the #StatefulCompute engine
Author-Email: Dima Korolev <dmitry.korolev@gmail.com>
License-Expression: LicenseRef-Proprietary
License-File: LICENSE
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Programming Language :: C
Classifier: Topic :: Software Development :: Compilers
Project-URL: Repository, https://github.com/piarun/prn-v2-uvx-piarun
Requires-Python: >=3.9
Description-Content-Type: text/markdown

# piarun

**piarun: the #StatefulCompute engine**

`piarun` compiles a supported Rust subset into base64-encoded, certified PRN IR and can execute that IR with its native runtime. The `piarun` Python distribution contains one native C executable named `piarun`; Python is used for package installation, not command execution. No runtime package dependencies, compiler installation, credentials, or network access are required by the installed binary.

## Install and run

After publication:

```sh
uvx piarun version
uvx piarun help
uvx piarun advertise
uvx piarun rs2ir --source 'fn main() { println!("hello"); }'
uvx piarun run --source 'fn main() { println!("hello"); }'
uvx --from piarun piarun rs2ir --input main.rs
uv tool install piarun
piarun version
```

Before publication, build and run the local wheel:

```sh
uv build
uvx --from ./dist/piarun-0.0.3-py3-none-macosx_11_0_arm64.whl piarun version
```

Use the wheel filename produced on your platform. `uvx --from . piarun version` also builds directly from the checkout. `piarun` is the package name and the only executable name.

For source edits without a version bump, use `uvx --no-cache --from . piarun ...` to bypass a previously cached tool environment.

## Compiler contract

```sh
piarun rs2ir --input main.rs
printf 'fn main() { println!("hello"); }' | piarun rs2ir --input -
piarun rs2ir --source 'fn main() { println!("hello"); }' | base64 --decode
piarun run --source 'fn main() { println!("hello"); }'
```

Successful `rs2ir` output is always a single line of base64, whether displayed in a terminal, piped, captured, or invoked with `--json`. Pipe it directly into `base64 --decode`; no JSON envelope or field extraction is needed. Metadata commands and ordinary errors retain their structured JSON output when piped or passed `--json`.

Execute the first 20 primes directly from the wheel:

```sh
cat <<'EOF' | uvx --from . piarun run --input -
pub async fn main() {
  let mut n = 2;
  let mut found = 0;
  while n < 100 {
    let mut d = 2;
    let mut prime = 1;
    while d * d <= n {
      if n % d == 0 {
        prime = 0;
      }
      d = d + 1;
      tokio::task::yield_now().await;
    }
    if prime == 1 {
      if found < 20 {
        println!("{}", n);
        found = found + 1;
      }
    }
    n = n + 1;
    tokio::task::yield_now().await;
  }
  assert_eq!(found, 20);
}
EOF
```

The code is RFC 4648 standard padded base64 of compact UTF-8 `Program` JSON, including its PUOPS certificate. The decoded JSON has no insignificant whitespace and no terminal newline; string contents retain their whitespace. An unsupported construct or failed certification is an error, never an uncertified success. Rust input is bounded to 4 MiB and JSON to 32 MiB. See [CLI-CONTRACT.md](CLI-CONTRACT.md) for fields and exit codes.

## Build

```sh
cmake -S . -B build -DCMAKE_BUILD_TYPE=Release
cmake --build build --parallel 4
ctest --test-dir build --output-on-failure
./build/piarun version
uv build
```

The executable is C11 throughout, including the compiler submodule. CMake and declarative `pyproject.toml` metadata build platform wheels with `scikit-build-core`. Python files are verification and release tooling only; there are no Python modules, launchers, or Python shared-library dependencies in the wheel. Wheels use `py3-none-PLATFORM` tags and support installers using Python 3.9+. Source builds require Git, CMake 3.20+, and a C11 compiler; wheels do not.

Builds default to `distribution: local`. Release workflows set `pypi`; other distributors can set `-DPRN_DISTRIBUTION=github` or another label. `version` also includes the UTC build date, source revision, frontend revision, and platform. `SOURCE_DATE_EPOCH` controls reproducible build dates. **Distribution describes artifact provenance, not the installer's download location:** a release wheel copied from PyPI and installed locally remains the same artifact. Missing Git history is honestly reported as `uncommitted`; release jobs supply the exact commit explicitly.

## Platforms and release

The wheel matrix targets macOS 11+ on Apple Silicon and Intel, Linux glibc 2.17+ and musl 1.2+ on x86-64/AArch64, and Windows 10 version 1903+ on AMD64 and Windows 11 on ARM64. [RELEASE.md](RELEASE.md) explains native build/test jobs, provenance, and trusted publishing. See [VALIDATION.md](VALIDATION.md) for what has actually been run locally; a configured target is not evidence of a successful execution test.
