A Hexarc program is a user-created definition comprising:

  • A definition of the triggers, inputs, and outputs of the program.
  • One or more pieces of code defining how to handle the triggers.
  • Optional static resources.

For example, an AI2 console command could be implemented as a program. The trigger is the user invoking the command, the input is the parameters on the command line, the code defines how to handle the command.

Core Concepts

The program record is an entry in the Arc.programs table that defines the program. Every program is assigned an 8-character unique program ID (unique in the arcology) at create time. The program record contains all the information for how and when to run the program.

The actual program files, including code, are stored as binary objects in the Arc.files table, under the path /programs/{progID}/. A program may have any number of program files in a hierarchical folder structure.

Note: The program ID is generally not exposed to the user and should not need to be referenced. It should be possible for someone to clone a project (copy and assign a new program ID) without breaking the program.

At runtime, we instantiate a process which tracks the running of the program. A single program might be instantiated multiple times, resulting in multiple processes. The Hexe engine tracks running processes in memory.

The program record contains all settings for the program, including access rights, inputs and triggers, resources used, etc.

The program record defines one or more ports through which the program interacts with the world. For example, a console program might define an input port (containing the command line parameters) and an output port (to return to the user). A web app could define a port for every entrypoint (or a port that handles a range of URLs).

We also use ports to persist data. For example, a program might define a per-user storage location.

When running a program, we bind required ports to specific resources. Often this can be an automatic process (e.g., AI2 binds a standard input and output), but it might be possible for the user to bind ports themselves. In some cases the program record might specify a binding (or at least a default). In other cases, a user might bind at invocation time, e.g., to bind an input port to the output of a different program. It should also be possible for a program to invoke other programs and do the appropriate binding.

NOTE: It would be great to maintain the one-file program concept. Perhaps the program record is always extracted from the program itself (sort of as a cache of program properties). Things like security (who can run program, etc.) should be settings in Arc.programs and should be directly modifiable (via a UI).

NOTE: We should store a compiled version of the program. We may need a path like, Arc.files/code/{progID}/... (or something). We should define the namespace at some point.


We use ports to communicate between program components (e.g., between program and UI) and between programs (or programs and system).

  • A port is defined by a port definition structure (a CDatum structure).
  • A port implements a well-known protocol which defines how the two sides of the port communicate.

Implementation Plan

  1. Simple Alchemy UI to create and edit single-file programs and store in Arc.files.
  2. Add appropriate APIs to Hexe to create a program (get an ID) record in Arc.programs and connect to Arc.files.
  3. Add appropriate API to compile code. Result will be metadata in Arc.programs and code in Arc.files/code.
  4. Iterate on syntax with goal of implementing AI2 commands.
  5. Implement simple input port and simple output port.
  6. Implement run-time architecture. Running process has n bits of code, tied to different events. Once loaded, we invoke an event, then poll for intermediate results and completion (all via the port).

See Also