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

cmake -S . -B build
cmake --build build -j

Core dependency

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

git submodule update --init --recursive

Quickstart (local)

Initialize a store:

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

Run the daemon:

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

Dev loop (build + restart):

./scripts/dev-restart.sh

Query store meta:

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

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

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

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

Discover the store-backed API contract ref:

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

Fetch the contract bytes (JSON):

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

Upload raw bytes:

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

Download raw bytes:

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

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

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):

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):

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}]}'

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}
• 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}
• 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.