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