99 lines
3 KiB
Markdown
99 lines
3 KiB
Markdown
# Amduat (PEL quickstart)
|
|
|
|
This repo contains the PEL/1 stack and small CLI tools to seed and run
|
|
PEL/PROGRAM-DAG/1 programs against an ASL store.
|
|
|
|
## Build
|
|
|
|
```
|
|
cmake --build build
|
|
```
|
|
|
|
## Initialize an ASL store
|
|
|
|
```
|
|
amduat-asl init --root .amduat-asl
|
|
```
|
|
|
|
## Seed a PEL program artifact
|
|
|
|
`amduat-pel-seed` creates a Program DAG in memory, encodes it under
|
|
`ENC/PEL-PROGRAM-DAG/1`, tags it as `TYPE_TAG_PEL_PROGRAM_DAG_1`, and
|
|
stores it in ASL.
|
|
|
|
```
|
|
concat1_ref=$(amduat-pel-seed --seed concat1 --root .amduat-asl --quiet)
|
|
```
|
|
|
|
Available seeds:
|
|
|
|
- `const` (const "hello", no inputs)
|
|
- `concat` (concat input 0 + input 1)
|
|
- `concat1` (identity: concat input 0 only)
|
|
- `slice` (slice input 0, offset=1 length=3)
|
|
- `hash` (HASH-ASL1-256 of input 0)
|
|
- `const-hash` (const "hello" then hash)
|
|
|
|
## Store an input artifact
|
|
|
|
```
|
|
input_ref=$(printf 'hello' | amduat-asl put --root .amduat-asl --input - --quiet)
|
|
```
|
|
|
|
## Run a program and print output bytes
|
|
|
|
`amduat-pel-run` executes a Program via `PEL/1-SURF`, writes outputs and
|
|
result artifacts to the store, and can stream an output artifact's bytes
|
|
to stdout (like `amduat-asl get`).
|
|
|
|
```
|
|
amduat-pel-run --root .amduat-asl \
|
|
--program-ref "$concat1_ref" \
|
|
--input-ref "$input_ref" \
|
|
--output-raw --quiet
|
|
```
|
|
|
|
The command above prints `hello` to stdout. Without `--quiet`, execution
|
|
status and refs are printed to stderr.
|
|
|
|
## Notes
|
|
|
|
- Program artifacts are standard ASL artifacts whose bytes are encoded
|
|
`ProgramBytes` (`ENC/PEL-PROGRAM-DAG/1`) and whose type tag is
|
|
`TYPE_TAG_PEL_PROGRAM_DAG_1` (`0x00000101`).
|
|
- `amduat-pel-run` reports `result_ref`, `trace_ref`, and `output_ref[N]`
|
|
when not using `--output-raw`.
|
|
|
|
## PEL reference
|
|
|
|
- Scheme ref (PEL/PROGRAM-DAG/1): `amduat_pel_program_dag_scheme_ref()`
|
|
- Type tags:
|
|
- Program DAG: `0x00000101` (`TYPE_TAG_PEL_PROGRAM_DAG_1`)
|
|
- Trace DAG: `0x00000102` (`TYPE_TAG_PEL_TRACE_DAG_1`)
|
|
- Surface result: `0x00000103` (`TYPE_TAG_PEL1_RESULT_1`)
|
|
- Encoding profile IDs:
|
|
- Program DAG: `0x0101` (`PEL_ENC_PROGRAM_DAG_V1`)
|
|
- Trace DAG: `0x0102` (`PEL_ENC_TRACE_DAG_V1`)
|
|
- Surface result: `0x0103` (`PEL_ENC_EXECUTION_RESULT_V1`)
|
|
|
|
## TGK handoff (stub)
|
|
|
|
TGK should consume PEL surface artifacts (result + trace) and their refs to
|
|
construct provenance graphs and overlays. Inputs to expect:
|
|
|
|
- `result_ref`: a `PEL/1-SURF` execution result artifact.
|
|
- `trace_ref`: a `PEL/TRACE-DAG/1` trace artifact (optional but recommended).
|
|
- `program_ref` + `input_refs`: available inside result/trace payloads.
|
|
|
|
Recommended next step: map trace nodes/outputs to TGK nodes/edges and build
|
|
overlay indexes (e.g., lookup by artifact ref, program ref, op name).
|
|
|
|
## Common mistakes
|
|
|
|
- Passing a **program ref** as an input ref. Program artifacts are encoded DAGs,
|
|
so printing their bytes yields strings like `pel.bytes.const` plus embedded
|
|
params (e.g. `hello`), not the intended data.
|
|
- Forgetting that `concat1` is identity: output bytes match input bytes.
|
|
- Expecting `params_ref` to affect DAG execution (it is accepted by the surface
|
|
API but not used in the current DAG executor).
|