Store, list and reopen local XLS results

Use Altifigence CLI 0.1.9 on Linux to keep native XLS results in a local project. Each stored result is checked by replaying its embedded request on the CPU when it is stored, listed and reopened.

Store a result

Use an absolute path to your local project. This example uses $HOME/alti-projects/demo-project. Save a native operation request:

set -euo pipefail
PROJECT="$(cd "$HOME/alti-projects/demo-project" && pwd -P)"
WORK="$(mktemp -d)"
cat > "$WORK/eval.json" <<'JSON'
{
  "schema": "altifigence.xls.operation-request.v1",
  "operation": "eval",
  "input_kind": "dslx",
  "source": "fn compute(x: u8, y: u8) -> u8 { x + y }",
  "top": "compute",
  "backend": "cpu",
  "vectors": [["1", "2"]]
}
JSON
alti xls artifact store --project "$PROJECT" --request "$WORK/eval.json" > "$WORK/ref.json"
jq '{schema, result_schema, replay_verified}' "$WORK/ref.json"
ID="$(jq -r .id "$WORK/ref.json")"

store runs the operation named in the request, replays the result, and saves it. Require exit status 0. The selected reference fields are:

{
  "schema": "altifigence.xls.artifact-ref.v1",
  "result_schema": "altifigence.xls.operation-result.v1",
  "replay_verified": true
}

id and sha256 hold the same value: the SHA-256 of the stored result, 64 lowercase hexadecimal characters. The result is saved as .altifigence/xls/artifacts/<id>.json inside the folder given by --project. Without --project, the current folder is used. Optimize and codegen requests store altifigence.xls.operation-result.v2 results that include compilation. Storing the same request again returns the same id.

List stored results

alti xls artifact list --project "$PROJECT" > "$WORK/list.json"
jq '{schema, limit, replay_verified, ids}' "$WORK/list.json"

ids holds the stored IDs in sorted order. Before listing, every stored result is checked against its ID and replayed. The list covers up to 256 entries. A project without stored results returns an empty ids array. Results published by alti xls run are kept in the same store and appear in the same list.

Reopen a result

alti xls artifact show --project "$PROJECT" "$ID" > "$WORK/result.json"
jq '{schema, status, outputs}' "$WORK/result.json"

After exit status 0, the selected fields are:

{
  "schema": "altifigence.xls.operation-result.v1",
  "status": "succeeded",
  "outputs": [
    "bits[8]:0x3"
  ]
}

show returns the complete stored result, including request, source_sha256, request_sha256 and parameters. It first checks that the file's SHA-256 equals the ID and that the file is within 65536 bytes, then replays the embedded request and compares every field.

Recover from errors

When the XLS engine rejects a store operation, the command exits with status 2 and writes an altifigence.xls.error.v1 object to standard output. Read its code and message:

alti xls artifact show --project "$PROJECT" "$ID" > "$WORK/show.json" || true
jq -r '.error.code + ": " + .error.message' "$WORK/show.json"

The CLI reports XLS artifact id must be 64 lowercase hexadecimal characters on standard error with the prefix error: and exits with status 1 before running the engine. Read this message in standard error. Copy the id from store or from ids in list unchanged.

For artifact-not-found: XLS store does not exist, pass the same --project that you used with store.

For artifact-io: cannot access local XLS artifact store from show, run list with the same --project and use an ID from ids.

For resource-limit: store listing exceeds 256 entries; use artifact-show with a known id, reopen results with show and the IDs saved from store.

Check, evaluate and generate RTL with native XLS