> ## Documentation Index
> Fetch the complete documentation index at: https://docs.aethis.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Versions, regression and pinned replay

> Compare reviewed cases, inspect a composed rulebook and replay an exact publication before integrating decisions into your application.

Start after [your first agent session](/agents/onboarding) and [reviewed ruleset publication](/getting-started/author-first-ruleset). Keep the approved source, complete test corpus, project ID and publication receipt.

## Compare two versions

Invoke the fourth skill in your host:

```text theme={null}
Use regression-compare with my two exact ruleset identities and the complete
reviewed test corpus from our authoring session. Show expected and actual outcomes
for every named case, including field errors and both content digests.
Do not change inputs or expectations to remove a difference.
Explain any changed outcome using the trace and source clause; ask me whether
that change is intended before recommending a new publication.
```

Supply both identities explicitly. A mutable slug or a newly generated candidate is not a substitute for the older publication. If the selected interface cannot address the required immutable identity, report that limitation and use the supported REST replay path below. Do not present a partial corpus as a complete regression comparison.

Expected result: one row per reviewed case for each version, with differences called out. Passing those cases establishes that corpus's behaviour, not every possible input.

## Inspect an existing composition

A rulebook combines member rulesets. Shared input names do not by themselves define how the members combine. Review the member identities, field definitions and composition logic together; then test the combined outcomes as well as each member's scenarios.

For this exercise, use an existing approved rulebook and synthetic case data. You need a key with access to its detail and decisions. No new authoring or model-provider call is required. [Section discovery](/authoring/section-discovery) explains the separate authoring workflow for creating sections and combining them.

```text theme={null}
Inspect the existing rulebook I identify, using the documented REST API.
Show its member identities, composition logic and current immutable release.
Review our source-derived combined cases before running them. Include alternative
routes, prerequisites, shared inputs and a deliberately invalid field.
Do not create or change the rulebook during this exercise.
```

The REST transport is explicit here: current MCP and CLI interfaces do not expose every immutable rulebook replay selector. Do not invent a `release_id` argument on a tool that does not accept it.

## Pin and replay through REST

Use the secure `api_request` helper from [the authoring tutorial](/getting-started/author-first-ruleset#before-you-start), with an ordinary key that can access the selected rulebook. Set `AETHIS_RULEBOOK_ID` to that existing rulebook's ID or slug. Save a reviewed `combined-cases.json` array containing `name`, `field_values` and `expected_outcome` for every case. Invalid-input cases also include an `error_fields` array naming the expected errors.

```bash theme={null}
: "${AETHIS_RULEBOOK_ID:?Choose an existing accessible rulebook}"
api_request ordinary "$API_BASE/rulebooks/$AETHIS_RULEBOOK_ID" > rulebook-detail.json
jq -e '.release.release_id and .release.content_identity and .release.members' rulebook-detail.json >/dev/null
jq -e 'type == "array" and length > 0 and all(.[]; .name and .field_values and .expected_outcome)' combined-cases.json >/dev/null

release_id="$(jq -er '.release.release_id' rulebook-detail.json)"
jq -c '.[]' combined-cases.json | while IFS= read -r test_case; do
  request="$(printf '%s' "$test_case" | jq \
    --arg rulebook "$AETHIS_RULEBOOK_ID" --arg release "$release_id" \
    '{rulebook_id:$rulebook, release_id:$release, field_values:.field_values}')"
  response="$(api_request ordinary -X POST "$API_BASE/decide" \
    -H 'Content-Type: application/json' --data "$request")"
  printf '%s\n' "$response" | jq
  expected="$(printf '%s' "$test_case" | jq -er '.expected_outcome')"
  printf '%s' "$response" | jq -e --arg expected "$expected" \
    --argjson test_case "$test_case" --slurpfile detail rulebook-detail.json '
    .decision == $expected
    and .rulebook_id == $detail[0].rulebook_id
    and .release == $detail[0].release
    and .content_identity == $detail[0].release.content_identity
    and .ruleset_version == ("v" + ($detail[0].release.version | tostring))
    and (if (($test_case.error_fields // []) | length) > 0
         then .decision == "undetermined"
              and (($test_case.error_fields - ((.field_errors // {}) | keys)) | length) == 0
         else ((.field_errors // {}) | length) == 0 end)' >/dev/null
 done
```

Retain every request and response alongside `rulebook-detail.json` and the reviewed cases. Check the returned rulebook identity, version and content identity against the pinned release; inspect `field_errors` for each case. For deliberately invalid input, require the expected error and `undetermined`, not only a matching decision string. Reject missing, skipped or duplicated cases in your regression report.

Repeat with the same `release_id` and identical inputs. Expected result: the same decisions and content identity. A changed current release should not silently change an explicitly pinned replay. If a pin is unavailable, fail visibly rather than falling back to the current release.

## Integrate and recover

Use [the Python SDK](/interfaces/python-sdk), [CLI](/interfaces/cli), [MCP](/mcp-server/overview) or [REST](/interfaces/rest-api) for the operations each documents. The TypeScript SDK is not released.

Store decision IDs, input hashes and immutable content/publication identities with the application event they explain. Check field errors before treating an outcome as terminal. Keep Aethis and provider credentials on the server or in secure host credential storage.

After a failed authoring test, repair the candidate using the source and rerun the complete reviewed suite. After a host timeout, inspect the retained project's generation status before retrying. A response lost during a test-suite replacement leaves an unknown outcome: do not automatically repeat a destructive write or recreate the project. See [troubleshooting](/getting-started/troubleshooting) and [the authoring recovery steps](/agents/onboarding#resume-after-a-tool-timeout).