amduat-api/registry/amduatd-api-contract.v1.json

{
  "contract": "AMDUATD/API/1",
  "base_path": "/v1",
  "endpoints": [
    {"method": "GET", "path": "/v1/ui"},
    {"method": "GET", "path": "/v1/meta"},
    {"method": "HEAD", "path": "/v1/meta"},
    {"method": "GET", "path": "/v1/contract"},
    {"method": "GET", "path": "/v1/fed/records"},
    {"method": "GET", "path": "/v1/fed/artifacts/{ref}"},
    {"method": "GET", "path": "/v1/fed/status"},
    {"method": "POST", "path": "/v1/concepts"},
    {"method": "GET", "path": "/v1/concepts"},
    {"method": "GET", "path": "/v1/concepts/{name}"},
    {"method": "POST", "path": "/v1/concepts/{name}/publish"},
    {"method": "GET", "path": "/v1/resolve/{name}"},
    {"method": "POST", "path": "/v1/artifacts"},
    {"method": "GET", "path": "/v1/relations"},
    {"method": "GET", "path": "/v1/artifacts/{ref}"},
    {"method": "HEAD", "path": "/v1/artifacts/{ref}"},
    {"method": "GET", "path": "/v1/artifacts/{ref}?format=info"},
    {"method": "POST", "path": "/v1/pel/run"},
    {"method": "POST", "path": "/v1/pel/programs"},
    {"method": "POST", "path": "/v1/context_frames"}
  ],
  "schemas": {
    "pel_run_request": {
      "type": "object",
      "required": ["program_ref", "input_refs"],
      "properties": {
        "program_ref": {"type": "string", "description": "hex ref or concept name"},
        "input_refs": {"type": "array", "items": {"type": "string", "description": "hex ref or concept name"}},
        "params_ref": {"type": "string", "description": "hex ref or concept name"},
        "scheme_ref": {"type": "string", "description": "hex ref or 'dag'"},
        "receipt": {
          "type": "object",
          "required": ["input_manifest_ref", "environment_ref", "evaluator_id", "executor_ref", "started_at", "completed_at"],
          "properties": {
            "input_manifest_ref": {"type": "string", "description": "hex ref or concept name"},
            "environment_ref": {"type": "string", "description": "hex ref or concept name"},
            "evaluator_id": {"type": "string", "description": "opaque evaluator bytes (utf-8)"},
            "executor_ref": {"type": "string", "description": "hex ref or concept name"},
            "sbom_ref": {"type": "string", "description": "hex ref or concept name"},
            "parity_digest_hex": {"type": "string", "description": "hex bytes"},
            "executor_fingerprint_ref": {"type": "string", "description": "hex ref or concept name"},
            "run_id_hex": {"type": "string", "description": "hex bytes"},
            "limits": {
              "type": "object",
              "required": ["cpu_ms", "wall_ms", "max_rss_kib", "io_reads", "io_writes"],
              "properties": {
                "cpu_ms": {"type": "integer"},
                "wall_ms": {"type": "integer"},
                "max_rss_kib": {"type": "integer"},
                "io_reads": {"type": "integer"},
                "io_writes": {"type": "integer"}
              }
            },
            "logs": {
              "type": "array",
              "items": {
                "type": "object",
                "required": ["kind", "log_ref", "sha256_hex"],
                "properties": {
                  "kind": {"type": "integer"},
                  "log_ref": {"type": "string", "description": "hex ref or concept name"},
                  "sha256_hex": {"type": "string", "description": "hex bytes"}
                }
              }
            },
            "determinism_level": {"type": "integer", "description": "0-255"},
            "rng_seed_hex": {"type": "string", "description": "hex bytes"},
            "signature_hex": {"type": "string", "description": "hex bytes"},
            "started_at": {"type": "integer"},
            "completed_at": {"type": "integer"}
          }
        }
      }
    },
    "pel_run_response": {
      "type": "object",
      "required": ["result_ref", "output_refs", "status"],
      "properties": {
        "result_ref": {"type": "string", "description": "hex ref"},
        "trace_ref": {"type": "string", "description": "hex ref"},
        "receipt_ref": {"type": "string", "description": "hex ref"},
        "output_refs": {"type": "array", "items": {"type": "string", "description": "hex ref"}},
        "status": {"type": "string"}
      }
    },
    "fed_records_response": {
      "type": "object",
      "required": ["domain_id", "snapshot_id", "log_prefix", "next_logseq", "records"],
      "properties": {
        "domain_id": {"type": "integer"},
        "snapshot_id": {"type": "integer"},
        "log_prefix": {"type": "integer"},
        "next_logseq": {"type": "integer", "description": "Paging cursor; last emitted logseq + 1, or from_logseq if no records emitted."},
        "records": {
          "type": "array",
          "items": {
            "type": "object",
            "required": ["domain_id", "type", "ref", "logseq", "snapshot_id", "log_prefix"],
            "properties": {
              "domain_id": {"type": "integer"},
              "type": {"type": "integer"},
              "ref": {"type": "string"},
              "logseq": {"type": "integer"},
              "snapshot_id": {"type": "integer"},
              "log_prefix": {"type": "integer"},
              "visibility": {"type": "integer"},
              "has_source": {"type": "boolean"},
              "source_domain": {"type": "integer"},
              "notes": {"type": "string", "description": "Type mapping: ARTIFACT_PUBLISH -> ARTIFACT, PER when type_tag=FER1_RECEIPT_1, TGK_EDGE when type_tag=TGK1_EDGE_V1; ARTIFACT_UNPUBLISH -> TOMBSTONE."}
            }
          }
        }
      }
    },
    "fed_status_response": {
      "type": "object",
      "required": ["status", "domain_id", "registry_ref", "last_tick_ms"],
      "properties": {
        "status": {"type": "string"},
        "domain_id": {"type": "integer"},
        "registry_ref": {"type": ["string", "null"]},
        "last_tick_ms": {"type": "integer"}
      }
    },
    "context_frame_request": {
      "type": "object",
      "required": ["bindings"],
      "properties": {
        "bindings": {
          "type": "array",
          "items": {
            "type": "object",
            "required": ["key"],
            "properties": {
              "key": {"type": "string", "description": "concept name or hex ref"},
              "value": {"type": "string", "description": "hex ref or concept name"},
              "value_ref": {"type": "string", "description": "hex ref or concept name"},
              "value_scalar": {
                "type": "object",
                "properties": {
                  "int": {"type": "integer"},
                  "enum": {"type": "string", "description": "concept name or hex ref"}
                }
              }
            }
          }
        }
      }
    },
    "pel_program_author_request": {
      "type": "object",
      "required": ["nodes", "roots"],
      "properties": {
        "nodes": {"type": "array"},
        "roots": {"type": "array"}
      }
    },
    "concept_create_request": {
      "type": "object",
      "required": ["name"],
      "properties": {
        "name": {"type": "string"},
        "ref": {"type": "string", "description": "hex ref"}
      }
    },
    "artifact_info_response": {
      "type": "object",
      "required": ["len", "has_type_tag", "type_tag"],
      "properties": {
        "len": {"type": "integer"},
        "has_type_tag": {"type": "boolean"},
        "type_tag": {"type": "string"}
      }
    }
  }
}