amduat-api/README.md

# amduat-api

`amduat-api` builds `amduatd`, a minimal HTTP server over a Unix domain socket that exposes Amduat substrate operations for a **single ASL store root**.

## Build

```sh
cmake -S . -B build
cmake --build build -j
```

## Core dependency

This repo vendors the core implementation as a git submodule at `vendor/amduat`.

```sh
git submodule update --init --recursive
```

## Quickstart (local)

Initialize a store:

```sh
./vendor/amduat/build/amduat-asl init --root .amduat-asl
```

Run the daemon:

```sh
./build/amduatd --root .amduat-asl --sock amduatd.sock
```

Query store meta:

```sh
curl --unix-socket amduatd.sock http://localhost/v1/meta
```

Upload raw bytes:

```sh
curl --unix-socket amduatd.sock -X POST http://localhost/v1/artifacts \
  -H 'Content-Type: application/octet-stream' \
  --data-binary 'hello'
```

Download raw bytes:

```sh
curl --unix-socket amduatd.sock http://localhost/v1/artifacts/<ref>
```

Download artifact framing (`ENC/ASL1-CORE v1`):

```sh
curl --unix-socket amduatd.sock \
  'http://localhost/v1/artifacts/<ref>?format=artifact' --output artifact.bin
```

Run a PEL program from store-backed refs (default `scheme_ref=dag`):

```sh
curl --unix-socket amduatd.sock -X POST http://localhost/v1/pel/run \
  -H 'Content-Type: application/json' \
  -d '{"program_ref":"<program_ref>","input_refs":["<input_ref_0>"],"params_ref":"<params_ref>"}'
```

## Current endpoints

- `GET /v1/meta` → `{store_id, encoding_profile_id, hash_id}`
- `POST /v1/artifacts`
  - raw bytes: `Content-Type: application/octet-stream` (+ optional `X-Amduat-Type-Tag: 0x...`)
  - artifact framing: `Content-Type: application/vnd.amduat.asl.artifact+v1`
- `GET|HEAD /v1/artifacts/{ref}`
  - raw bytes default
  - artifact framing: `?format=artifact`
- `POST /v1/pel/run`
  - request: `{program_ref, input_refs[], params_ref?, scheme_ref?}` (refs are hex strings; omit `scheme_ref` to use `dag`)
  - response: `{result_ref, trace_ref?, output_refs[], status}`

## Notes

- This is intentionally a local-first surface (Unix socket, no TLS). HTTPS can be added later without changing the semantics.