Build a Watchlist Source Provenance and Historical Version Diff Engine — implementation

## Build
Audit entity changes across sequential versions of sanctions watchlists using FollowTheMoney diffing structures. Map source citation modifications to identify stealth delistings and identifier updates.

## User
Sanctions Quality Assurance Analyst

## Workflow
1. Ingest consecutive snapshot packages of FollowTheMoney entity records from simulated watchlist feeds.
2. Compute property-level diffs detecting modified legal names, added aliases, and altered registration numbers.
3. Extract upstream source citations and publishing agency markers to document entity modification provenance.
4. Compile a delta audit register highlighting material changes that require investigator portfolio re-screening.

## Interface
Interactive version-diff viewer with visual property highlight chips and exportable provenance change tables.

## Data
Use mock yente snapshot dumps containing simulated versioned FollowTheMoney JSON entities.
Starter examples below are synthetic. They are not downloaded records.

## Source
[OpenSanctions data toolkit](https://raw.githubusercontent.com/opensanctions/yente/main/README.md)
Leverage FollowTheMoney entity schemas, properties, and change tracking conventions from the yente framework.

## Tools
dspy, pydantic, fastapi.
DSPy compiles precise extraction assertions to classify property mutation categories systematically.
Local or hosted LLM supported by DSPy with structured output capabilities.

## Deliverables
Submit runnable source, pinned dependencies, setup commands, a working interface, example outputs, and a recorded end-to-end demo. Include tests and an action log.

## Acceptance
- Detects 100% of property diffs across name, jurisdiction, and identifier fields between revisions.
- Correctly categorizes modifications into addition, modification, or removal events.
- Attaches source timestamp and dataset origin ID to every identified change record.
- Emits an alert flag whenever an entity identifier changes without an explicit legal rationale.

## Starter Examples
```json
[
  {
    "input": {
      "entity_id": "ftm-ent-501",
      "v1": {
        "schema": "Company",
        "properties": {
          "name": [
            "Zenith Holdings Ltd"
          ],
          "jurisdiction": [
            "gb"
          ],
          "registrationNumber": [
            "01234567"
          ]
        }
      },
      "v2": {
        "schema": "Company",
        "properties": {
          "name": [
            "Zenith Global Holdings Ltd"
          ],
          "jurisdiction": [
            "gb"
          ],
          "registrationNumber": [
            "01234567"
          ],
          "alias": [
            "ZGH Limited"
          ]
        }
      },
      "snapshot_metadata": {
        "v1_date": "2024-01-01",
        "v2_date": "2024-02-01",
        "source_id": "uk-ofsi-mock"
      }
    },
    "expected_output": {
      "entity_id": "ftm-ent-501",
      "source_id": "uk-ofsi-mock",
      "changes_detected": [
        {
          "field": "name",
          "change_type": "modified",
          "old_value": [
            "Zenith Holdings Ltd"
          ],
          "new_value": [
            "Zenith Global Holdings Ltd"
          ]
        },
        {
          "field": "alias",
          "change_type": "added",
          "old_value": [],
          "new_value": [
            "ZGH Limited"
          ]
        }
      ],
      "rescreening_required": true,
      "provenance_summary": "Entity name modified and alias added in uk-ofsi-mock snapshot between 2024-01-01 and 2024-02-01."
    }
  },
  {
    "input": {
      "entity_id": "ftm-ent-502",
      "v1": {
        "schema": "Company",
        "properties": {
          "name": [
            "Static Trade Co"
          ],
          "jurisdiction": [
            "de"
          ]
        }
      },
      "v2": {
        "schema": "Company",
        "properties": {
          "name": [
            "Static Trade Co"
          ],
          "jurisdiction": [
            "de"
          ]
        }
      },
      "snapshot_metadata": {
        "v1_date": "2024-01-01",
        "v2_date": "2024-02-01",
        "source_id": "eu-fsf-mock"
      }
    },
    "expected_output": {
      "entity_id": "ftm-ent-502",
      "source_id": "eu-fsf-mock",
      "changes_detected": [],
      "rescreening_required": false,
      "provenance_summary": "No changes detected across snapshots."
    }
  }
]
```

## Safety
Processes synthetic reference datasets; carries no legal or regulatory consequence and freezes no funds.
Use mock external writes. Require human review before any real deployment.