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
```

Dev loop (build + restart):

```sh
./scripts/dev-restart.sh
```

Query store meta:

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

Browser UI (use `socat` to forward the Unix socket):

```sh
socat TCP-LISTEN:8080,fork,reuseaddr UNIX-CONNECT:amduatd.sock
```

Then open `http://localhost:8080/v1/ui`.

Discover the store-backed API contract ref:

```sh
curl --unix-socket amduatd.sock 'http://localhost/v1/contract?format=ref'
```

Fetch the contract bytes (JSON):

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

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>"}'
```

Define a PEL/PROGRAM-DAG/1 program (store-backed):

```sh
curl --unix-socket amduatd.sock -X POST http://localhost/v1/pel/programs \
  -H 'Content-Type: application/json' \
  -d '{"nodes":[{"id":1,"op":{"name":"pel.bytes.concat","version":1},"inputs":[{"external":{"input_index":0}},{"external":{"input_index":1}}],"params_hex":""}],"roots":[{"node_id":1,"output_index":0}]}'
```

Create a named concept and publish a ref (so you can use the name instead of hex refs):

```sh
curl --unix-socket amduatd.sock -X POST http://localhost/v1/concepts \
  -H 'Content-Type: application/json' \
  -d '{"name":"hello","ref":"<program_ref>"}'
```

Publish a new version:

```sh
curl --unix-socket amduatd.sock -X POST http://localhost/v1/concepts/hello/publish \
  -H 'Content-Type: application/json' \
  -d '{"ref":"<program_ref_v2>"}'
```

Resolve the latest ref:

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

Inspect concepts:

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

## Current endpoints

- `GET /v1/meta` → `{store_id, encoding_profile_id, hash_id, api_contract_ref}`
- `GET /v1/contract` → contract bytes (JSON) (+ `X-Amduat-Contract-Ref` header)
- `GET /v1/contract?format=ref` → `{ref}`
- `GET /v1/ui` → browser UI for authoring/running programs
- `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/concepts`
  - request: `{name, ref?}` (`name` is lowercase; `ref` publishes an initial version)
  - response: `{name, concept_ref}`
- `POST /v1/concepts/{name}/publish` → publishes a new version `{ref}`
- `GET /v1/concepts` → `{concepts:[{name, concept_ref}]}`
- `GET /v1/concepts/{name}` → `{name, concept_ref, latest_ref, versions[]}`
- `GET /v1/resolve/{name}` → `{ref}` (latest published)
- `POST /v1/pel/run`
  - request: `{program_ref, input_refs[], params_ref?, scheme_ref?}` (`program_ref`/`input_refs`/`params_ref` accept hex refs or concept names; omit `scheme_ref` to use `dag`)
  - response: `{result_ref, trace_ref?, output_refs[], status}`
- `POST /v1/pel/programs`
  - request: authoring JSON for `PEL/PROGRAM-DAG/1` (kernel ops only; `params_hex` is raw hex bytes)
  - response: `{program_ref}`

## Notes

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