amduat/README.md

# 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`.
- The filesystem ASL store layout expects digests at least 2 bytes long
  (two directory levels). Experimental shorter digests need a different store.
- The filesystem ASL store (`amduat-asl ... --root`) is a legacy convenience
  backend; once the index/log store is introduced it is considered
  non-conformant to ASL index/log specs and should be used only for quickstart
  demos.
- Compatibility & migration: existing `asl_store_fs` stores will not be
  automatically upgraded. Plan to re-ingest artifacts into the index/log store
  when it lands.

## Documentation

- Implementation clarifications: `docs/spec-clarifications.md`
- Spec coverage matrix: `AUDITS.md` (Spec Coverage section)
- Index/log API sketch: `docs/index-log-api-sketch.md`
- Federation core API: `include/amduat/fed/` (registry, ingest, replay, view)

## 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).