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

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

3.7 KiB Raw Blame History