Extract PEL CLI formatting/helpers into amduat_format library

CMakeLists.txt

@@ -82,6 +82,12 @@ set(AMDUAT_ENC_SRCS
   src/near_core/enc/tgk1_edge.c
 )
 
+set(AMDUAT_FORMAT_SRCS
+  src/near_core/format/json.c
+  src/near_core/format/ref.c
+  src/near_core/format/pel.c
+)
+
 set(AMDUAT_PEL_SRCS
   src/kernel/pel/core.c
   src/pel_stack/surf/surf.c
@@ -123,6 +129,9 @@ amduat_link(hash_asl1 amduat_asl amduat_util)
 amduat_add_lib(enc SRCS ${AMDUAT_ENC_SRCS})
 amduat_link(enc amduat_asl amduat_hash_asl1 amduat_util)
 
+amduat_add_lib(format SRCS ${AMDUAT_FORMAT_SRCS})
+amduat_link(format amduat_asl amduat_enc amduat_util)
+
 amduat_add_lib(pel SRCS ${AMDUAT_PEL_SRCS})
 amduat_link(pel amduat_asl amduat_enc amduat_hash_asl1 amduat_util)
 
@@ -176,7 +185,7 @@ target_include_directories(amduat_pel_cli
   PRIVATE ${AMDUAT_INCLUDE_DIR}
 )
 target_link_libraries(amduat_pel_cli
-  PRIVATE amduat_pel amduat_asl_store_fs amduat_asl amduat_enc
+  PRIVATE amduat_format amduat_pel amduat_asl_store_fs amduat_asl amduat_enc
           amduat_hash_asl1 amduat_util
 )
 set_target_properties(amduat_pel_cli PROPERTIES OUTPUT_NAME amduat-pel)

include/amduat/format/json.h

@@ -0,0 +1,19 @@
+#ifndef AMDUAT_FORMAT_JSON_H
+#define AMDUAT_FORMAT_JSON_H
+
+#include "amduat/asl/core.h"
+
+#include <stdbool.h>
+#include <stdio.h>
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+bool amduat_format_json_escape(FILE *stream, amduat_octets_t text);
+
+#ifdef __cplusplus
+} /* extern "C" */
+#endif
+
+#endif /* AMDUAT_FORMAT_JSON_H */

include/amduat/format/output.h

@@ -0,0 +1,17 @@
+#ifndef AMDUAT_FORMAT_OUTPUT_H
+#define AMDUAT_FORMAT_OUTPUT_H
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+typedef enum {
+  AMDUAT_FORMAT_OUTPUT_TEXT = 0,
+  AMDUAT_FORMAT_OUTPUT_JSON = 1
+} amduat_format_output_t;
+
+#ifdef __cplusplus
+} /* extern "C" */
+#endif
+
+#endif /* AMDUAT_FORMAT_OUTPUT_H */

include/amduat/format/pel.h

@@ -0,0 +1,49 @@
+#ifndef AMDUAT_FORMAT_PEL_H
+#define AMDUAT_FORMAT_PEL_H
+
+#include "amduat/format/output.h"
+#include "amduat/format/ref.h"
+#include "amduat/pel/core.h"
+#include "amduat/pel/opreg_kernel.h"
+#include "amduat/pel/program_dag.h"
+#include "amduat/pel/surf.h"
+#include "amduat/pel/trace_dag.h"
+
+#include <stdbool.h>
+#include <stdio.h>
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+const char *amduat_format_pel_status_name(amduat_pel_execution_status_t status);
+const char *amduat_format_pel_error_kind_name(
+    amduat_pel_execution_error_kind_t kind);
+const char *amduat_format_pel_node_status_name(
+    amduat_pel_node_trace_status_t status);
+const char *amduat_format_pel_store_phase_name(
+    amduat_pel_store_failure_phase_t phase);
+const char *amduat_format_pel_store_error_name(
+    amduat_pel_store_error_code_t code);
+const char *amduat_format_pel_kernel_kind_name(
+    amduat_pel_kernel_op_kind_t kind);
+
+bool amduat_format_pel_program(FILE *stream,
+                               const amduat_pel_program_t *program,
+                               amduat_format_output_t format);
+
+bool amduat_format_pel_trace(FILE *stream,
+                             const amduat_pel_trace_dag_value_t *trace,
+                             amduat_format_output_t format,
+                             amduat_format_ref_format_t ref_format);
+
+bool amduat_format_pel_result(FILE *stream,
+                              const amduat_pel_surface_execution_result_t *result,
+                              amduat_format_output_t format,
+                              amduat_format_ref_format_t ref_format);
+
+#ifdef __cplusplus
+} /* extern "C" */
+#endif
+
+#endif /* AMDUAT_FORMAT_PEL_H */

include/amduat/format/ref.h

@@ -0,0 +1,35 @@
+#ifndef AMDUAT_FORMAT_REF_H
+#define AMDUAT_FORMAT_REF_H
+
+#include "amduat/asl/core.h"
+
+#include <stdbool.h>
+#include <stdio.h>
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+typedef enum {
+  AMDUAT_FORMAT_REF_HEX = 0,
+  AMDUAT_FORMAT_REF_BYTES = 1
+} amduat_format_ref_format_t;
+
+/* For AMDUAT_FORMAT_REF_BYTES, output is hex of EncodedRef bytes. */
+bool amduat_format_ref_to_text(amduat_reference_t ref,
+                               amduat_format_ref_format_t fmt,
+                               char **out_text);
+
+bool amduat_format_ref_write_text(FILE *stream,
+                                  amduat_reference_t ref,
+                                  amduat_format_ref_format_t fmt);
+
+bool amduat_format_ref_write_json(FILE *stream,
+                                  amduat_reference_t ref,
+                                  amduat_format_ref_format_t fmt);
+
+#ifdef __cplusplus
+} /* extern "C" */
+#endif
+
+#endif /* AMDUAT_FORMAT_REF_H */

include/amduat/pel/opreg_kernel.h

@@ -50,6 +50,11 @@ const amduat_pel_kernel_op_desc_t *amduat_pel_kernel_op_lookup(
     amduat_octets_t name,
     uint32_t version);
 
+const amduat_pel_kernel_op_desc_t *amduat_pel_kernel_op_descs(
+    size_t *out_len);
+
+const char *amduat_pel_kernel_op_name(amduat_pel_kernel_op_kind_t kind);
+
 bool amduat_pel_kernel_op_eval(
     const amduat_pel_kernel_op_desc_t *desc,
     const amduat_artifact_t *inputs,

include/amduat/util/hex.h

@@ -17,6 +17,11 @@ bool amduat_hex_encode_lower(const uint8_t *bytes,
                              char *out,
                              size_t out_len);
 
+/* Convenience: allocates output; caller frees with free(). */
+bool amduat_hex_encode_alloc(const uint8_t *bytes,
+                             size_t byte_len,
+                             char **out);
+
 /* Decodes exactly; rejects odd length or invalid hex. Accept upper/lowercase. */
 bool amduat_hex_decode(const char *hex,
                        uint8_t *out,

src/internal/hex.c

@@ -49,6 +49,36 @@ bool amduat_hex_encode_lower(const uint8_t *bytes,
   return true;
 }
 
+bool amduat_hex_encode_alloc(const uint8_t *bytes,
+                             size_t byte_len,
+                             char **out) {
+  size_t out_len;
+  char *buf;
+
+  if (out != NULL) {
+    *out = NULL;
+  }
+  if (out == NULL) {
+    return false;
+  }
+
+  out_len = amduat_hex_encoded_size(byte_len);
+  if (out_len == 0) {
+    return byte_len == 0;
+  }
+
+  buf = (char *)malloc(out_len);
+  if (buf == NULL) {
+    return false;
+  }
+  if (!amduat_hex_encode_lower(bytes, byte_len, buf, out_len)) {
+    free(buf);
+    return false;
+  }
+  *out = buf;
+  return true;
+}
+
 static bool amduat_hex_nibble(char c, uint8_t *out) {
   if (c >= '0' && c <= '9') {
     *out = (uint8_t)(c - '0');

src/near_core/format/json.c

@@ -0,0 +1,73 @@
+#include "amduat/format/json.h"
+
+#include <stdio.h>
+
+bool amduat_format_json_escape(FILE *stream, amduat_octets_t text) {
+  size_t i;
+
+  if (stream == NULL) {
+    return false;
+  }
+  if (text.len != 0 && text.data == NULL) {
+    return false;
+  }
+
+  if (fputc('"', stream) == EOF) {
+    return false;
+  }
+  for (i = 0; i < text.len; ++i) {
+    uint8_t c = text.data[i];
+    switch (c) {
+      case '"':
+        if (fputs("\\\"", stream) < 0) {
+          return false;
+        }
+        break;
+      case '\\':
+        if (fputs("\\\\", stream) < 0) {
+          return false;
+        }
+        break;
+      case '\b':
+        if (fputs("\\b", stream) < 0) {
+          return false;
+        }
+        break;
+      case '\f':
+        if (fputs("\\f", stream) < 0) {
+          return false;
+        }
+        break;
+      case '\n':
+        if (fputs("\\n", stream) < 0) {
+          return false;
+        }
+        break;
+      case '\r':
+        if (fputs("\\r", stream) < 0) {
+          return false;
+        }
+        break;
+      case '\t':
+        if (fputs("\\t", stream) < 0) {
+          return false;
+        }
+        break;
+      default:
+        if (c < 0x20u) {
+          if (fprintf(stream, "\\u%04x", (unsigned int)c) < 0) {
+            return false;
+          }
+        } else {
+          if (fputc((int)c, stream) == EOF) {
+            return false;
+          }
+        }
+        break;
+    }
+  }
+  if (fputc('"', stream) == EOF) {
+    return false;
+  }
+  return true;
+}

src/near_core/format/pel.c

@@ -0,0 +1,784 @@
+#include "amduat/format/pel.h"
+
+#include "amduat/format/json.h"
+#include "amduat/format/ref.h"
+#include "amduat/util/hex.h"
+
+#include <stdio.h>
+#include <stdlib.h>
+#include <string.h>
+
+const char *amduat_format_pel_status_name(
+    amduat_pel_execution_status_t status) {
+  switch (status) {
+    case AMDUAT_PEL_EXEC_STATUS_OK:
+      return "OK";
+    case AMDUAT_PEL_EXEC_STATUS_SCHEME_UNSUPPORTED:
+      return "SCHEME_UNSUPPORTED";
+    case AMDUAT_PEL_EXEC_STATUS_INVALID_PROGRAM:
+      return "INVALID_PROGRAM";
+    case AMDUAT_PEL_EXEC_STATUS_INVALID_INPUTS:
+      return "INVALID_INPUTS";
+    case AMDUAT_PEL_EXEC_STATUS_RUNTIME_FAILED:
+      return "RUNTIME_FAILED";
+    default:
+      return "UNKNOWN";
+  }
+}
+
+const char *amduat_format_pel_error_kind_name(
+    amduat_pel_execution_error_kind_t kind) {
+  switch (kind) {
+    case AMDUAT_PEL_EXEC_ERROR_NONE:
+      return "NONE";
+    case AMDUAT_PEL_EXEC_ERROR_SCHEME:
+      return "SCHEME";
+    case AMDUAT_PEL_EXEC_ERROR_PROGRAM:
+      return "PROGRAM";
+    case AMDUAT_PEL_EXEC_ERROR_INPUTS:
+      return "INPUTS";
+    case AMDUAT_PEL_EXEC_ERROR_RUNTIME:
+      return "RUNTIME";
+    default:
+      return "UNKNOWN";
+  }
+}
+
+const char *amduat_format_pel_node_status_name(
+    amduat_pel_node_trace_status_t status) {
+  switch (status) {
+    case AMDUAT_PEL_NODE_TRACE_OK:
+      return "NODE_OK";
+    case AMDUAT_PEL_NODE_TRACE_FAILED:
+      return "NODE_FAILED";
+    case AMDUAT_PEL_NODE_TRACE_SKIPPED:
+      return "NODE_SKIPPED";
+    default:
+      return "NODE_UNKNOWN";
+  }
+}
+
+const char *amduat_format_pel_store_phase_name(
+    amduat_pel_store_failure_phase_t phase) {
+  switch (phase) {
+    case AMDUAT_PEL_STORE_FAILURE_PROGRAM:
+      return "PROGRAM";
+    case AMDUAT_PEL_STORE_FAILURE_INPUT:
+      return "INPUT";
+    default:
+      return "UNKNOWN";
+  }
+}
+
+const char *amduat_format_pel_store_error_name(
+    amduat_pel_store_error_code_t code) {
+  switch (code) {
+    case AMDUAT_PEL_STORE_ERROR_NOT_FOUND:
+      return "NOT_FOUND";
+    case AMDUAT_PEL_STORE_ERROR_INTEGRITY:
+      return "INTEGRITY";
+    case AMDUAT_PEL_STORE_ERROR_UNSUPPORTED:
+      return "UNSUPPORTED";
+    default:
+      return "UNKNOWN";
+  }
+}
+
+const char *amduat_format_pel_kernel_kind_name(
+    amduat_pel_kernel_op_kind_t kind) {
+  switch (kind) {
+    case AMDUAT_PEL_KERNEL_OP_CONCAT:
+      return "concat";
+    case AMDUAT_PEL_KERNEL_OP_SLICE:
+      return "slice";
+    case AMDUAT_PEL_KERNEL_OP_CONST:
+      return "const";
+    case AMDUAT_PEL_KERNEL_OP_HASH_ASL1:
+      return "hash_asl1";
+    default:
+      return "unknown";
+  }
+}
+
+static char *amduat_format_hex_encode(amduat_octets_t bytes) {
+  char *hex = NULL;
+  if (!amduat_hex_encode_alloc(bytes.data, bytes.len, &hex)) {
+    return NULL;
+  }
+  return hex;
+}
+
+static bool amduat_format_diagnostics_text(
+    FILE *stream,
+    const char *prefix,
+    const amduat_pel_diagnostic_entry_t *diags,
+    size_t diags_len) {
+  size_t i;
+
+  if (diags_len == 0) {
+    return true;
+  }
+  if (prefix == NULL) {
+    prefix = "";
+  }
+
+  for (i = 0; i < diags_len; ++i) {
+    char *msg_hex = amduat_format_hex_encode(diags[i].message);
+    if (msg_hex == NULL) {
+      return false;
+    }
+    fprintf(stream, "%sdiagnostic[%zu].code=%u\n", prefix, i, diags[i].code);
+    fprintf(stream, "%sdiagnostic[%zu].message_hex=%s\n",
+            prefix, i, msg_hex);
+    free(msg_hex);
+  }
+  return true;
+}
+
+static bool amduat_format_diagnostics_json(
+    FILE *stream,
+    const amduat_pel_diagnostic_entry_t *diags,
+    size_t diags_len) {
+  size_t i;
+
+  fputs("[", stream);
+  for (i = 0; i < diags_len; ++i) {
+    char *msg_hex = amduat_format_hex_encode(diags[i].message);
+    if (msg_hex == NULL) {
+      return false;
+    }
+    if (i != 0) {
+      fputc(',', stream);
+    }
+    fprintf(stream, "{\"code\":%u,\"message_hex\":", diags[i].code);
+    if (!amduat_format_json_escape(
+            stream, amduat_octets(msg_hex, strlen(msg_hex)))) {
+      free(msg_hex);
+      return false;
+    }
+    fputs("}", stream);
+    free(msg_hex);
+  }
+  fputs("]", stream);
+  return true;
+}
+
+static bool amduat_format_program_text(FILE *stream,
+                                       const amduat_pel_program_t *program) {
+  size_t i;
+
+  fprintf(stream, "nodes_len=%zu\n", program->nodes_len);
+  fprintf(stream, "roots_len=%zu\n", program->roots_len);
+
+  for (i = 0; i < program->nodes_len; ++i) {
+    const amduat_pel_node_t *node = &program->nodes[i];
+    size_t j;
+    char *params_hex;
+
+    fprintf(stream, "node[%zu].id=%u\n", i, node->id);
+    fprintf(stream, "node[%zu].op.name=%.*s\n", i,
+            (int)node->op.name.len,
+            node->op.name.data ? (const char *)node->op.name.data : "");
+    fprintf(stream, "node[%zu].op.version=%u\n", i, node->op.version);
+    fprintf(stream, "node[%zu].inputs_len=%zu\n", i, node->inputs_len);
+
+    for (j = 0; j < node->inputs_len; ++j) {
+      const amduat_pel_dag_input_t *input = &node->inputs[j];
+      if (input->kind == AMDUAT_PEL_DAG_INPUT_EXTERNAL) {
+        fprintf(stream, "node[%zu].input[%zu].kind=external\n", i, j);
+        fprintf(stream,
+                "node[%zu].input[%zu].external.input_index=%u\n",
+                i, j, input->value.external.input_index);
+      } else {
+        fprintf(stream, "node[%zu].input[%zu].kind=node\n", i, j);
+        fprintf(stream,
+                "node[%zu].input[%zu].node.node_id=%u\n",
+                i, j, input->value.node.node_id);
+        fprintf(stream,
+                "node[%zu].input[%zu].node.output_index=%u\n",
+                i, j, input->value.node.output_index);
+      }
+    }
+
+    params_hex = amduat_format_hex_encode(node->params);
+    if (params_hex == NULL) {
+      return false;
+    }
+    fprintf(stream, "node[%zu].params_len=%zu\n", i, node->params.len);
+    fprintf(stream, "node[%zu].params_hex=%s\n", i, params_hex);
+    free(params_hex);
+  }
+
+  for (i = 0; i < program->roots_len; ++i) {
+    fprintf(stream, "root[%zu].node_id=%u\n",
+            i, program->roots[i].node_id);
+    fprintf(stream, "root[%zu].output_index=%u\n",
+            i, program->roots[i].output_index);
+  }
+
+  return true;
+}
+
+static bool amduat_format_program_json(FILE *stream,
+                                       const amduat_pel_program_t *program) {
+  size_t i;
+
+  fputs("{\"nodes\":[", stream);
+  for (i = 0; i < program->nodes_len; ++i) {
+    const amduat_pel_node_t *node = &program->nodes[i];
+    size_t j;
+    char *params_hex;
+
+    if (i != 0) {
+      fputc(',', stream);
+    }
+    fputs("{\"id\":", stream);
+    fprintf(stream, "%u", node->id);
+    fputs(",\"op\":{\"name\":", stream);
+    if (!amduat_format_json_escape(stream, node->op.name)) {
+      return false;
+    }
+    fprintf(stream, ",\"version\":%u}", node->op.version);
+    fputs(",\"inputs\":[", stream);
+    for (j = 0; j < node->inputs_len; ++j) {
+      const amduat_pel_dag_input_t *input = &node->inputs[j];
+      if (j != 0) {
+        fputc(',', stream);
+      }
+      if (input->kind == AMDUAT_PEL_DAG_INPUT_EXTERNAL) {
+        fprintf(stream,
+                "{\"kind\":\"external\",\"input_index\":%u}",
+                input->value.external.input_index);
+      } else {
+        fprintf(stream,
+                "{\"kind\":\"node\",\"node_id\":%u,\"output_index\":%u}",
+                input->value.node.node_id,
+                input->value.node.output_index);
+      }
+    }
+    fputs("]", stream);
+    params_hex = amduat_format_hex_encode(node->params);
+    if (params_hex == NULL) {
+      return false;
+    }
+    fputs(",\"params_hex\":", stream);
+    if (!amduat_format_json_escape(
+            stream, amduat_octets(params_hex, strlen(params_hex)))) {
+      free(params_hex);
+      return false;
+    }
+    free(params_hex);
+    fputs("}", stream);
+  }
+  fputs("],\"roots\":[", stream);
+  for (i = 0; i < program->roots_len; ++i) {
+    if (i != 0) {
+      fputc(',', stream);
+    }
+    fprintf(stream,
+            "{\"node_id\":%u,\"output_index\":%u}",
+            program->roots[i].node_id,
+            program->roots[i].output_index);
+  }
+  fputs("]}", stream);
+  return true;
+}
+
+bool amduat_format_pel_program(FILE *stream,
+                               const amduat_pel_program_t *program,
+                               amduat_format_output_t format) {
+  if (stream == NULL || program == NULL) {
+    return false;
+  }
+  if (format == AMDUAT_FORMAT_OUTPUT_TEXT) {
+    return amduat_format_program_text(stream, program);
+  }
+  return amduat_format_program_json(stream, program);
+}
+
+static bool amduat_format_trace_text(FILE *stream,
+                                     const amduat_pel_trace_dag_value_t *trace,
+                                     amduat_format_ref_format_t ref_format) {
+  size_t i;
+
+  fprintf(stream, "pel1_version=%u\n", trace->pel1_version);
+  fprintf(stream, "scheme_ref=");
+  if (!amduat_format_ref_write_text(stream, trace->scheme_ref, ref_format)) {
+    return false;
+  }
+  fputc('\n', stream);
+  fprintf(stream, "program_ref=");
+  if (!amduat_format_ref_write_text(stream, trace->program_ref, ref_format)) {
+    return false;
+  }
+  fputc('\n', stream);
+  fprintf(stream, "status=%s(%u)\n",
+          amduat_format_pel_status_name(trace->status),
+          (unsigned int)trace->status);
+  fprintf(stream, "error_kind=%s(%u)\n",
+          amduat_format_pel_error_kind_name(trace->summary.kind),
+          (unsigned int)trace->summary.kind);
+  fprintf(stream, "status_code=%u\n",
+          (unsigned int)trace->summary.status_code);
+
+  fprintf(stream, "has_exec_result_ref=%s\n",
+          trace->has_exec_result_ref ? "true" : "false");
+  if (trace->has_exec_result_ref) {
+    fprintf(stream, "exec_result_ref=");
+    if (!amduat_format_ref_write_text(stream,
+                                      trace->exec_result_ref,
+                                      ref_format)) {
+      return false;
+    }
+    fputc('\n', stream);
+  }
+
+  fprintf(stream, "input_refs_len=%zu\n", trace->input_refs_len);
+  for (i = 0; i < trace->input_refs_len; ++i) {
+    fprintf(stream, "input_ref[%zu]=", i);
+    if (!amduat_format_ref_write_text(stream,
+                                      trace->input_refs[i],
+                                      ref_format)) {
+      return false;
+    }
+    fputc('\n', stream);
+  }
+
+  fprintf(stream, "has_params_ref=%s\n",
+          trace->has_params_ref ? "true" : "false");
+  if (trace->has_params_ref) {
+    fprintf(stream, "params_ref=");
+    if (!amduat_format_ref_write_text(stream,
+                                      trace->params_ref,
+                                      ref_format)) {
+      return false;
+    }
+    fputc('\n', stream);
+  }
+
+  fprintf(stream, "node_traces_len=%zu\n", trace->node_traces_len);
+  for (i = 0; i < trace->node_traces_len; ++i) {
+    const amduat_pel_node_trace_dag_t *node = &trace->node_traces[i];
+    size_t j;
+    char prefix[64];
+
+    fprintf(stream, "node_trace[%zu].node_id=%u\n", i, node->node_id);
+    fprintf(stream, "node_trace[%zu].op.name=%.*s\n", i,
+            (int)node->op_name.len,
+            node->op_name.data ? (const char *)node->op_name.data : "");
+    fprintf(stream, "node_trace[%zu].op.version=%u\n", i, node->op_version);
+    fprintf(stream, "node_trace[%zu].status=%s(%u)\n", i,
+            amduat_format_pel_node_status_name(node->status),
+            (unsigned int)node->status);
+    fprintf(stream, "node_trace[%zu].status_code=%u\n", i,
+            node->status_code);
+    fprintf(stream, "node_trace[%zu].output_refs_len=%zu\n", i,
+            node->output_refs_len);
+    for (j = 0; j < node->output_refs_len; ++j) {
+      fprintf(stream, "node_trace[%zu].output_ref[%zu]=",
+              i, j);
+      if (!amduat_format_ref_write_text(stream,
+                                        node->output_refs[j],
+                                        ref_format)) {
+        return false;
+      }
+      fputc('\n', stream);
+    }
+    fprintf(stream, "node_trace[%zu].diagnostics_len=%zu\n", i,
+            node->diagnostics_len);
+    snprintf(prefix, sizeof(prefix), "node_trace[%zu].", i);
+    if (!amduat_format_diagnostics_text(stream,
+                                        prefix,
+                                        node->diagnostics,
+                                        node->diagnostics_len)) {
+      return false;
+    }
+  }
+
+  return true;
+}
+
+static bool amduat_format_trace_json(FILE *stream,
+                                     const amduat_pel_trace_dag_value_t *trace,
+                                     amduat_format_ref_format_t ref_format) {
+  size_t i;
+
+  fputs("{\"pel1_version\":", stream);
+  fprintf(stream, "%u", trace->pel1_version);
+  fputs(",\"scheme_ref\":", stream);
+  if (!amduat_format_ref_write_json(stream, trace->scheme_ref, ref_format)) {
+    return false;
+  }
+  fputs(",\"program_ref\":", stream);
+  if (!amduat_format_ref_write_json(stream, trace->program_ref, ref_format)) {
+    return false;
+  }
+  fputs(",\"status\":", stream);
+  if (!amduat_format_json_escape(
+          stream,
+          amduat_octets(amduat_format_pel_status_name(trace->status),
+                        strlen(amduat_format_pel_status_name(trace->status))))) {
+    return false;
+  }
+  fprintf(stream, ",\"status_code\":%u",
+          (unsigned int)trace->summary.status_code);
+  fputs(",\"error_kind\":", stream);
+  if (!amduat_format_json_escape(
+          stream,
+          amduat_octets(
+              amduat_format_pel_error_kind_name(trace->summary.kind),
+              strlen(amduat_format_pel_error_kind_name(trace->summary.kind))))) {
+    return false;
+  }
+  fprintf(stream, ",\"error_kind_code\":%u",
+          (unsigned int)trace->summary.kind);
+
+  fputs(",\"has_exec_result_ref\":", stream);
+  fputs(trace->has_exec_result_ref ? "true" : "false", stream);
+  fputs(",\"exec_result_ref\":", stream);
+  if (trace->has_exec_result_ref) {
+    if (!amduat_format_ref_write_json(stream,
+                                      trace->exec_result_ref,
+                                      ref_format)) {
+      return false;
+    }
+  } else {
+    fputs("null", stream);
+  }
+
+  fputs(",\"input_refs\":[", stream);
+  for (i = 0; i < trace->input_refs_len; ++i) {
+    if (i != 0) {
+      fputc(',', stream);
+    }
+    if (!amduat_format_ref_write_json(stream,
+                                      trace->input_refs[i],
+                                      ref_format)) {
+      return false;
+    }
+  }
+  fputs("]", stream);
+
+  fputs(",\"has_params_ref\":", stream);
+  fputs(trace->has_params_ref ? "true" : "false", stream);
+  fputs(",\"params_ref\":", stream);
+  if (trace->has_params_ref) {
+    if (!amduat_format_ref_write_json(stream,
+                                      trace->params_ref,
+                                      ref_format)) {
+      return false;
+    }
+  } else {
+    fputs("null", stream);
+  }
+
+  fputs(",\"node_traces\":[", stream);
+  for (i = 0; i < trace->node_traces_len; ++i) {
+    const amduat_pel_node_trace_dag_t *node = &trace->node_traces[i];
+    size_t j;
+    if (i != 0) {
+      fputc(',', stream);
+    }
+    fprintf(stream, "{\"node_id\":%u,", node->node_id);
+    fputs("\"op\":{\"name\":", stream);
+    if (!amduat_format_json_escape(stream, node->op_name)) {
+      return false;
+    }
+    fprintf(stream, ",\"version\":%u},", node->op_version);
+    fputs("\"status\":", stream);
+    if (!amduat_format_json_escape(
+            stream,
+            amduat_octets(amduat_format_pel_node_status_name(node->status),
+                          strlen(amduat_format_pel_node_status_name(
+                              node->status))))) {
+      return false;
+    }
+    fprintf(stream, ",\"status_code\":%u", node->status_code);
+    fputs(",\"output_refs\":[", stream);
+    for (j = 0; j < node->output_refs_len; ++j) {
+      if (j != 0) {
+        fputc(',', stream);
+      }
+      if (!amduat_format_ref_write_json(stream,
+                                        node->output_refs[j],
+                                        ref_format)) {
+        return false;
+      }
+    }
+    fputs("],\"diagnostics\":", stream);
+    if (!amduat_format_diagnostics_json(stream,
+                                        node->diagnostics,
+                                        node->diagnostics_len)) {
+      return false;
+    }
+    fputs("}", stream);
+  }
+  fputs("]}", stream);
+
+  return true;
+}
+
+bool amduat_format_pel_trace(FILE *stream,
+                             const amduat_pel_trace_dag_value_t *trace,
+                             amduat_format_output_t format,
+                             amduat_format_ref_format_t ref_format) {
+  if (stream == NULL || trace == NULL) {
+    return false;
+  }
+  if (format == AMDUAT_FORMAT_OUTPUT_TEXT) {
+    return amduat_format_trace_text(stream, trace, ref_format);
+  }
+  return amduat_format_trace_json(stream, trace, ref_format);
+}
+
+static bool amduat_format_result_text(
+    FILE *stream,
+    const amduat_pel_surface_execution_result_t *result,
+    amduat_format_ref_format_t ref_format) {
+  size_t i;
+
+  fprintf(stream, "pel1_version=%u\n", result->pel1_version);
+  fprintf(stream, "scheme_ref=");
+  if (!amduat_format_ref_write_text(stream, result->scheme_ref, ref_format)) {
+    return false;
+  }
+  fputc('\n', stream);
+  fprintf(stream, "program_ref=");
+  if (!amduat_format_ref_write_text(stream, result->program_ref, ref_format)) {
+    return false;
+  }
+  fputc('\n', stream);
+
+  fprintf(stream, "status=%s(%u)\n",
+          amduat_format_pel_status_name(result->core_result.status),
+          (unsigned int)result->core_result.status);
+  fprintf(stream, "error_kind=%s(%u)\n",
+          amduat_format_pel_error_kind_name(result->core_result.summary.kind),
+          (unsigned int)result->core_result.summary.kind);
+  fprintf(stream, "status_code=%u\n",
+          (unsigned int)result->core_result.summary.status_code);
+  if (!amduat_format_diagnostics_text(stream,
+                                      "",
+                                      result->core_result.diagnostics,
+                                      result->core_result.diagnostics_len)) {
+    return false;
+  }
+
+  fprintf(stream, "input_refs_len=%zu\n", result->input_refs_len);
+  for (i = 0; i < result->input_refs_len; ++i) {
+    fprintf(stream, "input_ref[%zu]=", i);
+    if (!amduat_format_ref_write_text(stream,
+                                      result->input_refs[i],
+                                      ref_format)) {
+      return false;
+    }
+    fputc('\n', stream);
+  }
+
+  fprintf(stream, "output_refs_len=%zu\n", result->output_refs_len);
+  for (i = 0; i < result->output_refs_len; ++i) {
+    fprintf(stream, "output_ref[%zu]=", i);
+    if (!amduat_format_ref_write_text(stream,
+                                      result->output_refs[i],
+                                      ref_format)) {
+      return false;
+    }
+    fputc('\n', stream);
+  }
+
+  fprintf(stream, "has_params_ref=%s\n",
+          result->has_params_ref ? "true" : "false");
+  if (result->has_params_ref) {
+    fprintf(stream, "params_ref=");
+    if (!amduat_format_ref_write_text(stream,
+                                      result->params_ref,
+                                      ref_format)) {
+      return false;
+    }
+    fputc('\n', stream);
+  }
+
+  fprintf(stream, "has_trace_ref=%s\n",
+          result->has_trace_ref ? "true" : "false");
+  if (result->has_trace_ref) {
+    fprintf(stream, "trace_ref=");
+    if (!amduat_format_ref_write_text(stream,
+                                      result->trace_ref,
+                                      ref_format)) {
+      return false;
+    }
+    fputc('\n', stream);
+  }
+
+  fprintf(stream, "has_store_failure=%s\n",
+          result->has_store_failure ? "true" : "false");
+  if (result->has_store_failure) {
+    fprintf(stream, "store_failure.phase=%s(%u)\n",
+            amduat_format_pel_store_phase_name(result->store_failure.phase),
+            (unsigned int)result->store_failure.phase);
+    fprintf(stream, "store_failure.error_code=%s(%u)\n",
+            amduat_format_pel_store_error_name(
+                result->store_failure.error_code),
+            (unsigned int)result->store_failure.error_code);
+    fprintf(stream, "store_failure.failing_ref=");
+    if (!amduat_format_ref_write_text(
+            stream, result->store_failure.failing_ref, ref_format)) {
+      return false;
+    }
+    fputc('\n', stream);
+  }
+
+  return true;
+}
+
+static bool amduat_format_result_json(
+    FILE *stream,
+    const amduat_pel_surface_execution_result_t *result,
+    amduat_format_ref_format_t ref_format) {
+  size_t i;
+
+  fputs("{\"pel1_version\":", stream);
+  fprintf(stream, "%u", result->pel1_version);
+  fputs(",\"scheme_ref\":", stream);
+  if (!amduat_format_ref_write_json(stream, result->scheme_ref, ref_format)) {
+    return false;
+  }
+  fputs(",\"program_ref\":", stream);
+  if (!amduat_format_ref_write_json(stream, result->program_ref, ref_format)) {
+    return false;
+  }
+  fputs(",\"status\":", stream);
+  if (!amduat_format_json_escape(
+          stream,
+          amduat_octets(amduat_format_pel_status_name(
+                            result->core_result.status),
+                        strlen(amduat_format_pel_status_name(
+                            result->core_result.status))))) {
+    return false;
+  }
+  fprintf(stream, ",\"status_code\":%u",
+          (unsigned int)result->core_result.summary.status_code);
+  fputs(",\"error_kind\":", stream);
+  if (!amduat_format_json_escape(
+          stream,
+          amduat_octets(amduat_format_pel_error_kind_name(
+                            result->core_result.summary.kind),
+                        strlen(amduat_format_pel_error_kind_name(
+                            result->core_result.summary.kind))))) {
+    return false;
+  }
+  fprintf(stream, ",\"error_kind_code\":%u",
+          (unsigned int)result->core_result.summary.kind);
+  fputs(",\"diagnostics\":", stream);
+  if (!amduat_format_diagnostics_json(
+          stream,
+          result->core_result.diagnostics,
+          result->core_result.diagnostics_len)) {
+    return false;
+  }
+
+  fputs(",\"input_refs\":[", stream);
+  for (i = 0; i < result->input_refs_len; ++i) {
+    if (i != 0) {
+      fputc(',', stream);
+    }
+    if (!amduat_format_ref_write_json(stream,
+                                      result->input_refs[i],
+                                      ref_format)) {
+      return false;
+    }
+  }
+  fputs("]", stream);
+
+  fputs(",\"output_refs\":[", stream);
+  for (i = 0; i < result->output_refs_len; ++i) {
+    if (i != 0) {
+      fputc(',', stream);
+    }
+    if (!amduat_format_ref_write_json(stream,
+                                      result->output_refs[i],
+                                      ref_format)) {
+      return false;
+    }
+  }
+  fputs("]", stream);
+
+  fputs(",\"has_params_ref\":", stream);
+  fputs(result->has_params_ref ? "true" : "false", stream);
+  fputs(",\"params_ref\":", stream);
+  if (result->has_params_ref) {
+    if (!amduat_format_ref_write_json(stream,
+                                      result->params_ref,
+                                      ref_format)) {
+      return false;
+    }
+  } else {
+    fputs("null", stream);
+  }
+
+  fputs(",\"has_trace_ref\":", stream);
+  fputs(result->has_trace_ref ? "true" : "false", stream);
+  fputs(",\"trace_ref\":", stream);
+  if (result->has_trace_ref) {
+    if (!amduat_format_ref_write_json(stream,
+                                      result->trace_ref,
+                                      ref_format)) {
+      return false;
+    }
+  } else {
+    fputs("null", stream);
+  }
+
+  fputs(",\"has_store_failure\":", stream);
+  fputs(result->has_store_failure ? "true" : "false", stream);
+  fputs(",\"store_failure\":", stream);
+  if (result->has_store_failure) {
+    fputs("{\"phase\":", stream);
+    if (!amduat_format_json_escape(
+            stream,
+            amduat_octets(amduat_format_pel_store_phase_name(
+                              result->store_failure.phase),
+                          strlen(amduat_format_pel_store_phase_name(
+                              result->store_failure.phase))))) {
+      return false;
+    }
+    fprintf(stream, ",\"phase_code\":%u",
+            (unsigned int)result->store_failure.phase);
+    fputs(",\"error_code\":", stream);
+    if (!amduat_format_json_escape(
+            stream,
+            amduat_octets(amduat_format_pel_store_error_name(
+                              result->store_failure.error_code),
+                          strlen(amduat_format_pel_store_error_name(
+                              result->store_failure.error_code))))) {
+      return false;
+    }
+    fprintf(stream, ",\"error_code_id\":%u",
+            (unsigned int)result->store_failure.error_code);
+    fputs(",\"failing_ref\":", stream);
+    if (!amduat_format_ref_write_json(stream,
+                                      result->store_failure.failing_ref,
+                                      ref_format)) {
+      return false;
+    }
+    fputs("}", stream);
+  } else {
+    fputs("null", stream);
+  }
+
+  fputs("}", stream);
+  return true;
+}
+
+bool amduat_format_pel_result(FILE *stream,
+                              const amduat_pel_surface_execution_result_t *result,
+                              amduat_format_output_t format,
+                              amduat_format_ref_format_t ref_format) {
+  if (stream == NULL || result == NULL) {
+    return false;
+  }
+  if (format == AMDUAT_FORMAT_OUTPUT_TEXT) {
+    return amduat_format_result_text(stream, result, ref_format);
+  }
+  return amduat_format_result_json(stream, result, ref_format);
+}

src/near_core/format/ref.c

@@ -0,0 +1,72 @@
+#include "amduat/format/ref.h"
+
+#include "amduat/asl/ref_text.h"
+#include "amduat/enc/asl1_core_codec.h"
+#include "amduat/format/json.h"
+#include "amduat/util/hex.h"
+
+#include <stdlib.h>
+#include <string.h>
+
+bool amduat_format_ref_to_text(amduat_reference_t ref,
+                               amduat_format_ref_format_t fmt,
+                               char **out_text) {
+  if (out_text == NULL) {
+    return false;
+  }
+  *out_text = NULL;
+
+  if (fmt == AMDUAT_FORMAT_REF_HEX) {
+    return amduat_asl_ref_encode_hex(ref, out_text);
+  }
+
+  {
+    amduat_octets_t encoded;
+    char *hex = NULL;
+    if (!amduat_enc_asl1_core_encode_reference_v1(ref, &encoded)) {
+      return false;
+    }
+    if (!amduat_hex_encode_alloc(encoded.data, encoded.len, &hex)) {
+      free((void *)encoded.data);
+      return false;
+    }
+    free((void *)encoded.data);
+    *out_text = hex;
+    return true;
+  }
+}
+
+bool amduat_format_ref_write_text(FILE *stream,
+                                  amduat_reference_t ref,
+                                  amduat_format_ref_format_t fmt) {
+  char *ref_text = NULL;
+  bool ok;
+
+  if (stream == NULL) {
+    return false;
+  }
+  if (!amduat_format_ref_to_text(ref, fmt, &ref_text)) {
+    return false;
+  }
+  ok = fputs(ref_text, stream) >= 0;
+  free(ref_text);
+  return ok;
+}
+
+bool amduat_format_ref_write_json(FILE *stream,
+                                  amduat_reference_t ref,
+                                  amduat_format_ref_format_t fmt) {
+  char *ref_text = NULL;
+  bool ok;
+
+  if (stream == NULL) {
+    return false;
+  }
+  if (!amduat_format_ref_to_text(ref, fmt, &ref_text)) {
+    return false;
+  }
+  ok = amduat_format_json_escape(
+      stream, amduat_octets(ref_text, strlen(ref_text)));
+  free(ref_text);
+  return ok;
+}

src/pel_stack/opreg/kernel.c

@@ -22,36 +22,35 @@ static bool amduat_name_eq(amduat_octets_t name, const char *literal) {
          memcmp(name.data, literal, len) == 0;
 }
 
-static const amduat_pel_kernel_op_desc_t k_concat_desc = {
-    AMDUAT_PEL_KERNEL_OP_CONCAT,
-    AMDUAT_PEL_KERNEL_OP_CODE_CONCAT,
-    1,
-    SIZE_MAX,
-    1
-};
-
-static const amduat_pel_kernel_op_desc_t k_slice_desc = {
-    AMDUAT_PEL_KERNEL_OP_SLICE,
-    AMDUAT_PEL_KERNEL_OP_CODE_SLICE,
-    1,
-    1,
-    1
-};
-
-static const amduat_pel_kernel_op_desc_t k_const_desc = {
-    AMDUAT_PEL_KERNEL_OP_CONST,
-    AMDUAT_PEL_KERNEL_OP_CODE_CONST,
-    0,
-    0,
-    1
-};
-
-static const amduat_pel_kernel_op_desc_t k_hash_desc = {
-    AMDUAT_PEL_KERNEL_OP_HASH_ASL1,
-    AMDUAT_PEL_KERNEL_OP_CODE_HASH_ASL1,
-    1,
-    1,
-    1
+static const amduat_pel_kernel_op_desc_t k_kernel_descs[] = {
+    {
+        AMDUAT_PEL_KERNEL_OP_CONCAT,
+        AMDUAT_PEL_KERNEL_OP_CODE_CONCAT,
+        1,
+        SIZE_MAX,
+        1
+    },
+    {
+        AMDUAT_PEL_KERNEL_OP_SLICE,
+        AMDUAT_PEL_KERNEL_OP_CODE_SLICE,
+        1,
+        1,
+        1
+    },
+    {
+        AMDUAT_PEL_KERNEL_OP_CONST,
+        AMDUAT_PEL_KERNEL_OP_CODE_CONST,
+        0,
+        0,
+        1
+    },
+    {
+        AMDUAT_PEL_KERNEL_OP_HASH_ASL1,
+        AMDUAT_PEL_KERNEL_OP_CODE_HASH_ASL1,
+        1,
+        1,
+        1
+    },
 };
 
 const amduat_pel_kernel_op_desc_t *amduat_pel_kernel_op_lookup(
@@ -61,20 +60,43 @@ const amduat_pel_kernel_op_desc_t *amduat_pel_kernel_op_lookup(
     return NULL;
   }
   if (amduat_name_eq(name, AMDUAT_PEL_KERNEL_OP_CONCAT_NAME)) {
-    return &k_concat_desc;
+    return &k_kernel_descs[0];
   }
   if (amduat_name_eq(name, AMDUAT_PEL_KERNEL_OP_SLICE_NAME)) {
-    return &k_slice_desc;
+    return &k_kernel_descs[1];
   }
   if (amduat_name_eq(name, AMDUAT_PEL_KERNEL_OP_CONST_NAME)) {
-    return &k_const_desc;
+    return &k_kernel_descs[2];
   }
   if (amduat_name_eq(name, AMDUAT_PEL_KERNEL_OP_HASH_ASL1_NAME)) {
-    return &k_hash_desc;
+    return &k_kernel_descs[3];
   }
   return NULL;
 }
 
+const amduat_pel_kernel_op_desc_t *amduat_pel_kernel_op_descs(
+    size_t *out_len) {
+  if (out_len != NULL) {
+    *out_len = sizeof(k_kernel_descs) / sizeof(k_kernel_descs[0]);
+  }
+  return k_kernel_descs;
+}
+
+const char *amduat_pel_kernel_op_name(amduat_pel_kernel_op_kind_t kind) {
+  switch (kind) {
+    case AMDUAT_PEL_KERNEL_OP_CONCAT:
+      return AMDUAT_PEL_KERNEL_OP_CONCAT_NAME;
+    case AMDUAT_PEL_KERNEL_OP_SLICE:
+      return AMDUAT_PEL_KERNEL_OP_SLICE_NAME;
+    case AMDUAT_PEL_KERNEL_OP_CONST:
+      return AMDUAT_PEL_KERNEL_OP_CONST_NAME;
+    case AMDUAT_PEL_KERNEL_OP_HASH_ASL1:
+      return AMDUAT_PEL_KERNEL_OP_HASH_ASL1_NAME;
+    default:
+      return NULL;
+  }
+}
+
 static bool amduat_type_tags_match(const amduat_artifact_t *a,
                                    const amduat_artifact_t *b) {
   if (a->has_type_tag != b->has_type_tag) {