Build a Beneficial Ownership Sub-Threshold Equity Gap Auditor — implementation

## Build
Trace multi-tier shareholding structures to calculate unverified sub-threshold equity gaps. Generate targeted evidence requests for entities failing to aggregate to 100% control.

## User
Enhanced due diligence officer auditing complex multinational corporate registry filings.

## Workflow
1. Parse beneficial ownership declaration graphs and inspect declared voting or equity percentages.
2. Identify holding branches terminating in opaque corporate entities or sub-threshold gaps.
3. Generate a structured request-for-information document specifying missing intermediary documentation.
4. Render a JSON-driven ownership graph diagram highlighting unverified nodes for human sign-off.

## Interface
Interactive graph inspector showing verified ownership links alongside drafted evidence request letters.

## Data
Synthesize 40 BODS v0.4 ownership statements containing known parent-child breaks into a mock JSON file.
Starter examples below are synthetic. They are not downloaded records.

## Source
[Beneficial ownership modelling](https://standard.openownership.org/en/latest/standard/modelling/index.html)
Applies BODS v0.4 guidance on representing beneficial owners, interest shares, and entity relationships.

## Tools
mastra-ai, fastapi, graphviz.
Orchestrates multi-step workflow graphs connecting schema analysis with evidence request document drafting.
Fast hosted model capable of parsing graph structures and drafting professional compliance correspondence.

## 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 intermediary holding entities where ownership percentages fail to reach 100%.
- Generates formal evidence request letters referencing specific missing intermediary entity IDs.
- Outputs node-link diagram descriptions with verified and unverified status classifications.

## Starter Examples
```json
[
  {
    "input": {
      "target_entity": "ent-holdings-xyz",
      "statements": [
        {
          "id": "s1",
          "subject": "ent-holdings-xyz",
          "owner": "ent-overseas-1",
          "share": 0.45
        },
        {
          "id": "s2",
          "subject": "ent-holdings-xyz",
          "owner": "ent-overseas-2",
          "share": 0.35
        }
      ]
    },
    "expected_output": {
      "unresolved_share": 0.2,
      "evidence_required_for": [
        "ent-overseas-1",
        "ent-overseas-2",
        "undisclosed_remainder"
      ],
      "diagram_nodes": [
        {
          "id": "ent-holdings-xyz",
          "type": "target",
          "status": "resolved"
        },
        {
          "id": "ent-overseas-1",
          "type": "intermediary",
          "status": "unverified"
        },
        {
          "id": "ent-overseas-2",
          "type": "intermediary",
          "status": "unverified"
        }
      ],
      "request_letter_generated": true
    }
  },
  {
    "input": {
      "target_entity": "ent-single-owner",
      "statements": [
        {
          "id": "s3",
          "subject": "ent-single-owner",
          "owner": "person-frank",
          "share": 1
        }
      ]
    },
    "expected_output": {
      "unresolved_share": 0,
      "evidence_required_for": [],
      "diagram_nodes": [
        {
          "id": "ent-single-owner",
          "type": "target",
          "status": "resolved"
        },
        {
          "id": "person-frank",
          "type": "person",
          "status": "resolved"
        }
      ],
      "request_letter_generated": false
    }
  }
]
```

## Safety
Processes synthetic corporate declarations. Does not submit real requests for information or freeze commercial entities.
Use mock external writes. Require human review before any real deployment.