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

# Change Monitoring

> Use pack versions, diffs, and change events to answer what changed since the last sync.

Compliance teams need to know what changed before anything becomes tenant work.
The Regulatory Pack API exposes source-traced change intelligence at the
canonical pack layer:

* pack version history
* deterministic fact diffs between versions
* change events with impacted fact IDs, materiality, confidence, and citation basis
* source-watch currentness, source-change events, and binding recompile candidates

Pack diff endpoints do not create tenant tasks. Customer applicability endpoints
can persist workspace-scoped obligation instances and change impacts after a
profile-specific review.

## List Versions

Select a pack explicitly. This example uses the UK Data Use and Access pack:

```bash theme={null}
export ESHERIA_PACK_ID="UK-DATA-USE-AND-ACCESS"
```

```bash curl theme={null}
curl --compressed -sS \
  "$ESHERIA_API_BASE_URL/api/v1/domain-packs/$ESHERIA_PACK_ID/versions?limit=10" \
  -H "x-api-key: $ESHERIA_API_KEY" | jq
```

Expected response shape:

```json theme={null}
{
  "status": "ok",
  "data": {
    "versions": [
      {
        "domain_pack_version": "recovery-20260709T1640Z",
        "is_current": true
      }
    ],
    "pagination": {
      "total": 1,
      "limit": 10,
      "offset": 0
    }
  },
  "trace_id": "..."
}
```

## Diff Versions

Set two versions from the version list:

```bash theme={null}
export FROM_VERSION="VERSION_FROM_THE_API"
export TO_VERSION="NEWER_VERSION_FROM_THE_API"
```

Then call the diff endpoint:

```bash curl theme={null}
curl --compressed -sS \
  "$ESHERIA_API_BASE_URL/api/v1/domain-packs/$ESHERIA_PACK_ID/diff?from_version=$FROM_VERSION&to_version=$TO_VERSION" \
  -H "x-api-key: $ESHERIA_API_KEY" | jq
```

Diff rows can include:

* `change_type`
* `fact_type`
* `fact_id`
* `impacted_fact_ids`
* `source_citation_basis`
* `materiality`
* `confidence`
* before/after hashes

## List Change Events

```bash curl theme={null}
curl --compressed -sS \
  "$ESHERIA_API_BASE_URL/api/v1/domain-packs/$ESHERIA_PACK_ID/change-events?from_version=$FROM_VERSION&to_version=$TO_VERSION&limit=25" \
  -H "x-api-key: $ESHERIA_API_KEY" | jq
```

Use change events to power a downstream change monitor:

| Change signal              | Downstream action                                    |
| -------------------------- | ---------------------------------------------------- |
| New obligation             | Review applicability, then instantiate if accepted   |
| Changed obligation         | Update the existing operating obligation if impacted |
| Removed or superseded fact | Mark the old operating record for review             |
| Filing changed             | Update due-date logic or filing workflow             |
| Evidence changed           | Request new evidence or update control mapping       |
| Citation changed           | Re-verify source trace and legal review posture      |

<Info>
  CLI and MCP wrappers are available for monitoring currentness, source checks,
  change events, graph coverage, customer applicability runs, obligation
  instances, and customer change impacts.
</Info>

## Monitor Source Currentness

Create source watches for validated public HTTP(S) or deployment-approved S3
sources, then run a bounded source check. These state-changing calls require `monitoring:write`; pack
version, diff, event, and currentness reads use `regulatory:read`:

```bash curl theme={null}
curl --compressed -sS -X POST \
  "$ESHERIA_API_BASE_URL/api/v1/regulatory-monitoring/source-watches" \
  -H "content-type: application/json" \
  -H "x-api-key: $ESHERIA_API_KEY" \
  -H "idempotency-key: $(uuidgen)" \
  -d '{
    "domain_pack_id": "UK-DATA-USE-AND-ACCESS",
    "source_asset_id": "uk_duaa_2025",
    "source_uri": "https://www.legislation.gov.uk/ukpga/2025/18/contents",
    "source_kind": "binding",
    "authority_type": "binding"
  }' | jq

curl --compressed -sS -X POST \
  "$ESHERIA_API_BASE_URL/api/v1/regulatory-monitoring/source-watches/check" \
  -H "content-type: application/json" \
  -H "x-api-key: $ESHERIA_API_KEY" \
  -H "idempotency-key: $(uuidgen)" \
  -d '{"domain_pack_id":"UK-DATA-USE-AND-ACCESS"}' | jq
```

Only binding source changes create recompile candidates. Guidance and watchlist
changes are currentness signals and do not become binding obligations without
binding source support.

```bash CLI theme={null}
esheria monitoring currentness --domain-pack-id UK-DATA-USE-AND-ACCESS --format json
esheria monitoring check --domain-pack-id UK-DATA-USE-AND-ACCESS --format json
esheria monitoring changes --domain-pack-id UK-DATA-USE-AND-ACCESS --format json
esheria monitoring recompile-candidates --domain-pack-id UK-DATA-USE-AND-ACCESS --format json
```