# AEPs

#### Appendix D. Example AEPs, Indices & Event Formats

This appendix provides **illustrative, non-normative** examples of how **Assurance & Evidence Packs (AEPs)**, **indices**, and **event messages** are represented on the Nexus Rail.

The goals are to show:

* How AEPs carry **structured evidence** (GRIx-based) with EQL/CL, provenance, and uncertainty.
* How indices are emitted as **streaming events** and stored in catalogs.
* How **alerts, triggers, and episodes** are encoded for RailOps, agents, and external systems.

All examples are simplified for exposition; real deployments would be backed by **JSON Schema/OpenAPI**, **GRIx ontologies**, and **NXSS validation rules**.

***

### D.1 Example AEPs

#### D.1.1 Planning AEP (EQL3) — Drought & Food Security

This AEP supports **seasonal planning** (not direct capital triggers) on the East Africa Drought & Food Security Rail. It is issued at **EQL3** with mixed observation–model basis and GRF peer review.

```yaml
api_version: aep.v1
kind: AEP

metadata:
  aep_id: "aep.eaf.drought-food.seasonal.2026M03.v1"
  title: "Horn of Africa Seasonal Drought & Food Security Assessment — March 2026"
  rail_id: "nxsr.eaf.drought-food.v1"
  nrm_profile_id: "nrm.drought.food.household"
  eql_level: "EQL3"
  cl_target: "CL2"
  chronotope_scope_id: "chrono.eaf.drought-food.season.MAM2026"
  int_modules_used:
    - "CLIMATEINT"
    - "GEOINT"
    - "AGROINT"
    - "SOCINT"
  sd z_tags:
    - "sdz.sov.national"
    - "sdz.reg.regional"
  language: "en"
  status: "issued"

data_sources:
  - source_id: "ds.climate.reanalysis.horn.v3"
    provider: "GCRI/ClimateLab"
    sdz_class: "sdz.reg.regional"
    licence: "CC-BY-4.0"
  - source_id: "ds.ndvi.sentinel2.africa.v2"
    provider: "GCRI/EO-Lab"
    sdz_class: "sdz.reg.regional"
    licence: "CC-BY-4.0"
  - source_id: "ds.fsms.household.surveys.2024-2025"
    provider: "National Statistics + WFP"
    sdz_class: "sdz.sov.national"
    licence: "restricted-statistical"
  - source_id: "ds.pastoralist_knowledge.panels.v1"
    provider: "Pastoralist Councils"
    sdz_class: "sdz.sens.indigenous"
    licence: "custom-community-licence"

models_used:
  - model_id: "mdl.drought_spi.v2"
    version: "2.1.3"
    model_card_ref: "https://example.org/modelcards/mdl.drought_spi.v2"
  - model_id: "mdl.livelihood_response.v1"
    version: "1.0.4"
    model_card_ref: "https://example.org/modelcards/mdl.livelihood_response.v1"
  - model_id: "mdl.food_insecurity_projection.v1"
    version: "1.3.0"
    model_card_ref: "https://example.org/modelcards/mdl.food_insecurity_projection.v1"

indices_produced:
  - index_id: "idx.eaf.spi.seasonal.v3"
    index_type: "risk"
    scale: "subnational"
  - index_id: "idx.eaf.food_insecurity_rate.v2"
    index_type: "risk"
    scale: "subnational"
  - index_id: "idx.eaf.humanitarian_need.v1"
    index_type: "systemic_stress"
    scale: "national"

uncertainty_characterisation:
  narrative: >
    Projections of food insecurity carry high uncertainty in conflict-affected
    districts and in areas with sparse NDVI observations due to cloud cover.
    Household survey under-sampling of nomadic populations introduces additional
    structural uncertainty in pastoralist zones.
  structured:
    parameter_uncertainty: "moderate"
    structural_uncertainty: "moderate_high"
    data_gaps:
      - "pastoralist mobility patterns in cross-border clusters"
    sensitivity_to_assumptions:
      - assumption_id: "asmp.humanitarian_response_timeliness"
        qualitative_level: "high"

co_authorship:
  - actor_type: "NCC"
    actor_id: "ncc.univNairobi.risklab"
    role: "lead_modelling_and_analysis"
  - actor_type: "agency"
    actor_id: "ndma.kenya"
    role: "national_drought_expert_review"
  - actor_type: "community"
    actor_id: "council.pastoralist_north_kenya"
    role: "indigenous_knowledge_contributor"
  - actor_type: "rnc"
    actor_id: "rnc.kenya-nexus"
    role: "coordination"

grf_assurance_status:
  status: "peer_reviewed"
  grf_review_id: "grf.rev.aep.eaf.2026-03-15"
  reviewers:
    - "GRF/EastAfrica-Panel-1"
    - "GRF/FoodSecurity-Panel-2"

intended_use:
  decision_classes:
    - "seasonal_planning"
    - "humanitarian_prioritisation"
    - "contingency_budget_discussion"
  exclusions:
    - "no_direct_capital_triggers"
    - "no_parametric_payout_valuation"

issued_at: "2026-03-15T10:00:00Z"
valid_until: "2026-06-30T23:59:59Z"
signatures:
  - signer_id: "did:nexus:ncc.univNairobi"
    signature_type: "ed25519"
    signature_value: "base64..."
  - signer_id: "did:nexus:grf.eaf.panel1"
    signature_type: "ed25519"
    signature_value: "base64..."
```

***

#### D.1.2 Capital-Linked AEP (EQL4) — Drought Facility Trigger

This AEP is prepared for **sovereign risk finance**; it reaches **EQL4**, is linked to a specific facility, and is formally anchored via `nxproto.aep-anchor`.

```yaml
api_version: aep.v1
kind: AEP

metadata:
  aep_id: "aep.eaf.drought-food.trigger.2026M04.v1"
  title: "Trigger Assessment — East Africa Drought Contingent Credit Window 1"
  rail_id: "nxsr.eaf.drought-food.v1"
  nrm_profile_id: "nrm.drought.food.sovereign_fiscal"
  eql_level: "EQL4"
  cl_target: "CL3"
  chronotope_scope_id: "chrono.eaf.drought-food.season.MAM2026"
  int_modules_used:
    - "CLIMATEINT"
    - "AGROINT"
    - "MACROINT"
  facility_ref:
    facility_id: "drf.eaf.drought.window1"
    facility_type: "contingent_credit"
  status: "issued"

indices_evaluated:
  - index_id: "idx.eaf.drought_veg_index.v3"
    observed_value: 0.76
    trigger_threshold: 0.70
    trigger_condition_met: true
  - index_id: "idx.eaf.food_insecurity_rate.v2"
    observed_value: 0.19
    trigger_threshold: 0.15
    trigger_condition_met: true

trigger_summary:
  trigger_decision: "TRIGGER_RECOMMENDED"
  rationale: >
    Both the vegetative drought index and projected severe food insecurity
    exceed trigger thresholds for at least 3 of 5 monitored livelihood zones,
    with consistent patterns across independent data sources.
  recommended_disbursement_share: 0.8
  uncertainty_note: >
    While projections in conflict-affected districts are more uncertain,
    trigger conditions are robust to plausible model perturbations.

assurance:
  cross_checks:
    - "independent satellite-based NDVI anomaly products"
    - "alternative drought index (SPEI)"
    - "macro-fiscal impact simulations"
  sampling_and_verification:
    household_survey_validation: "conducted_in_3_focus_districts"
    third_party_verification: "done_by_international_partner"
  grf_assurance_status:
    status: "grf_certified"
    grf_certification_id: "grf.cert.aep.eaf.drought.trigger.2026M04.v1"

nvm_authorisation:
  decision_class: "capital_trigger"
  nvm_quorum_profile: "nvm.4of6.gov-fin-infra-community.v1"
  quorum_participants:
    - "did:nexus:treasury.kenya"
    - "did:nexus:treasury.ethiopia"
    - "did:nexus:centralbank.regional"
    - "did:nexus:community.council.pastoralist_north_kenya"
  quorum_result: "APPROVED"
  decision_time: "2026-04-05T16:00:00Z"

issued_at: "2026-04-05T16:05:00Z"
valid_until: "2026-05-31T23:59:59Z"

anchor:
  ledger_tx_id: "ledger.eaf.aepanchor.0xabc123..."
  chain: "nexus-main"
  hash_alg: "sha3-256"
  content_hash: "base64..."
```

***

### D.2 Example Index Event Formats

Indices are typically emitted as **streaming events** (e.g., over Kafka/NATS/MQTT via NXCOMMS) and logged to the **Index Catalog** for each rail.

We show examples as **JSON** using a CloudEvents-inspired structure.

#### D.2.1 Risk Index Event — Seasonal Drought Index

```json
{
  "specversion": "1.0",
  "type": "nexus.index.risk",
  "source": "nxobs://nxobs.eaf.climate-drought",
  "id": "evt.idx.eaf.spi.seasonal.2026M03.adminKE-23",
  "time": "2026-03-10T09:00:00Z",
  "subject": "idx.eaf.spi.seasonal.v3",
  "datacontenttype": "application/json",
  "nexus": {
    "rail_id": "nxsr.eaf.drought-food.v1",
    "index_id": "idx.eaf.spi.seasonal.v3",
    "index_type": "risk",
    "eql_level": "EQL3",
    "cl_context": "CL2",
    "chronotope_scope_id": "chrono.eaf.drought-food.MAM2026.adminKE-23",
    "sdz_tag": "sdz.reg.regional",
    "int_modules_used": ["CLIMATEINT", "GEOINT"],
    "method_ref": "https://example.org/methods/idx.eaf.spi.seasonal.v3"
  },
  "data": {
    "value": -1.8,
    "value_unit": "standardised_precipitation_index",
    "category": "severe_drought",
    "uncertainty": {
      "std_error": 0.15,
      "confidence_interval_95": [-2.1, -1.5]
    },
    "aggregation": {
      "level": "admin2",
      "admin_code": "KE-23",
      "population_weighted": true
    },
    "provenance": {
      "input_datasets": [
        "ds.climate.reanalysis.horn.v3",
        "ds.gauge_network.kenya.v2"
      ],
      "models_used": [
        "mdl.drought_spi.v2"
      ]
    }
  },
  "extensions": {
    "trace_id": "trace-12345",
    "signature": "base64...",
    "sdz_class": "sdz.reg.regional"
  }
}
```

***

#### D.2.2 Resilience Index Event — Urban Service Resilience

```json
{
  "specversion": "1.0",
  "type": "nexus.index.resilience",
  "source": "nxobs://nxobs.eu.urban-resilience",
  "id": "evt.idx.eu.urban.service_resilience.2027Q1.city123",
  "time": "2027-03-31T23:59:59Z",
  "subject": "idx.urban.service_resilience.v1",
  "datacontenttype": "application/json",
  "nexus": {
    "rail_id": "nxsr.eu.coastal-urban.v1",
    "index_id": "idx.urban.service_resilience.v1",
    "index_type": "resilience",
    "eql_level": "EQL3",
    "cl_context": "CL2",
    "chronotope_scope_id": "chrono.eu.city123.2027Q1",
    "sdz_tag": "sdz.sov.national",
    "int_modules_used": ["INFRAINT", "SOCINT"],
    "method_ref": "https://example.org/methods/idx.urban.service_resilience.v1"
  },
  "data": {
    "value": 0.68,
    "scale": "city",
    "sector_breakdown": {
      "electricity": 0.74,
      "water": 0.61,
      "healthcare": 0.72,
      "transport": 0.65
    },
    "interpretation": "moderate_resilience",
    "thresholds": {
      "low": 0.4,
      "medium": 0.6,
      "high": 0.8
    }
  },
  "extensions": {
    "trace_id": "trace-eu-city123-q1",
    "signature": "base64..."
  }
}
```

***

#### D.2.3 Systemic Stress Index Event — Climate–Macro Stress

```json
{
  "specversion": "1.0",
  "type": "nexus.index.systemic_stress",
  "source": "nxobs://nxobs.global.climate-macro",
  "id": "evt.idx.global.climate_macro_stress.2028Q2.countryXYZ",
  "time": "2028-06-30T23:59:59Z",
  "subject": "idx.global.climate_macro_stress.v2",
  "datacontenttype": "application/json",
  "nexus": {
    "rail_id": "nxsr.global.climate-macro.v1",
    "index_id": "idx.global.climate_macro_stress.v2",
    "index_type": "systemic_stress",
    "eql_level": "EQL4",
    "cl_context": "CL3",
    "chronotope_scope_id": "chrono.countryXYZ.2028Q2",
    "sdz_tag": "sdz.reg.regional",
    "int_modules_used": ["CLIMATEINT", "MACROINT", "FININT"],
    "method_ref": "https://example.org/methods/idx.global.climate_macro_stress.v2"
  },
  "data": {
    "value": 0.81,
    "scale": "national",
    "component_scores": {
      "hazard_intensity": 0.77,
      "exposure": 0.88,
      "vulnerability": 0.79,
      "financial_buffer": 0.46
    },
    "risk_of_debt_distress_category": "high",
    "scenario_id": "scen.climate_scenario_4.5_2030"
  },
  "extensions": {
    "trace_id": "trace-global-xyz-2028Q2",
    "signature": "base64...",
    "sdz_class": "sdz.reg.regional"
  }
}
```

***

### D.3 Example Alert & Trigger Event Formats

#### D.3.1 Early Warning Alert Event

```json
{
  "specversion": "1.0",
  "type": "nexus.alert.early_warning",
  "source": "nxobs://nxobs.eaf.climate-drought",
  "id": "evt.alert.ew.drought.phase2.2026M03.adminKE-23",
  "time": "2026-03-05T06:00:00Z",
  "subject": "ew.drought.phase2",
  "datacontenttype": "application/json",
  "nexus": {
    "rail_id": "nxsr.eaf.drought-food.v1",
    "alert_severity": "warning",
    "alert_confidence": "high",
    "chronotope_scope_id": "chrono.eaf.drought-food.MAM2026.adminKE-23",
    "sdz_tag": "sdz.sov.national",
    "eql_level": "EQL2",
    "derived_from_indices": [
      "idx.eaf.spi.seasonal.v3",
      "idx.eaf.food_insecurity_rate.v2"
    ]
  },
  "data": {
    "message": "Elevated risk of severe drought and food insecurity in Admin KE-23 for the coming season.",
    "recommended_actions_refs": [
      "aap.drought_cash_preposition.v1",
      "aap.livestock_support.v1"
    ],
    "lead_time_days": 45,
    "contact_points": [
      "ndma.kenya",
      "ministry_agriculture.ke"
    ]
  },
  "extensions": {
    "channel_tags": ["internal", "humanitarian_partners"],
    "signature": "base64..."
  }
}
```

***

#### D.3.2 Capital Trigger Candidate Event

```json
{
  "specversion": "1.0",
  "type": "nexus.alert.capital_trigger_candidate",
  "source": "nxstudio://nxstudio.eaf.drought-food.primary",
  "id": "evt.alert.capital_trigger_candidate.drf.eaf.drought.window1.2026M04",
  "time": "2026-04-02T10:00:00Z",
  "subject": "drf.eaf.drought.window1",
  "datacontenttype": "application/json",
  "nexus": {
    "rail_id": "nxsr.eaf.drought-food.v1",
    "facility_id": "drf.eaf.drought.window1",
    "nrm_profile_id": "nrm.drought.food.sovereign_fiscal",
    "eql_candidate": "EQL4",
    "cl_context": "CL3",
    "sdz_tag": "sdz.reg.regional"
  },
  "data": {
    "indices_snapshot": [
      {
        "index_id": "idx.eaf.drought_veg_index.v3",
        "value": 0.74,
        "trigger_threshold": 0.70,
        "condition_met": true
      },
      {
        "index_id": "idx.eaf.food_insecurity_rate.v2",
        "value": 0.18,
        "trigger_threshold": 0.15,
        "condition_met": true
      }
    ],
    "auto_generated_aep_id": "aep.eaf.drought-food.trigger.2026M04.draft",
    "recommended_next_step": "NVM_REVIEW",
    "recommended_quorum_profile": "nvm.4of6.gov-fin-infra-community.v1"
  },
  "extensions": {
    "trace_id": "trace-capital-candidate-2026M04",
    "safety_tier": "tier2",
    "signature": "base64..."
  }
}
```

***

#### D.3.3 Data Quality / Evidence Degradation Alert

```json
{
  "specversion": "1.0",
  "type": "nexus.alert.data_quality",
  "source": "nxstudio://nxstudio.eaf.drought-food.primary",
  "id": "evt.alert.dq.spi.missing_gauges.2026M02",
  "time": "2026-02-10T12:00:00Z",
  "subject": "idx.eaf.spi.seasonal.v3",
  "datacontenttype": "application/json",
  "nexus": {
    "rail_id": "nxsr.eaf.drought-food.v1",
    "affected_index_id": "idx.eaf.spi.seasonal.v3",
    "severity": "moderate",
    "sdz_tag": "sdz.reg.regional"
  },
  "data": {
    "dq_issue_type": "missing_observations",
    "description": "Precipitation gauge data missing for 30% of stations in Admin KE-23.",
    "affected_period": {
      "start": "2025-12-01T00:00:00Z",
      "end": "2026-01-31T23:59:59Z"
    },
    "fallback_used": "satellite_only",
    "implications": "Index uncertainty increased; EQL downgraded from EQL3 to EQL2 for this period."
  },
  "extensions": {
    "recommended_actions": [
      "flag_indices_in_aep",
      "notify_ndma_kenya",
      "prioritise_station_maintenance"
    ]
  }
}
```

***

### D.4 Episode & Decision Event Formats

#### D.4.1 Episode Event

```json
{
  "specversion": "1.0",
  "type": "nexus.episode.record",
  "source": "nxstudio://nxstudio.eaf.drought-food.primary",
  "id": "evt.episode.eaf.drought.2026M05.adminKE-23",
  "time": "2026-07-01T00:00:00Z",
  "subject": "episode.eaf.drought.2026M05",
  "datacontenttype": "application/json",
  "nexus": {
    "rail_id": "nxsr.eaf.drought-food.v1",
    "episode_id": "episode.eaf.drought.2026M05.adminKE-23",
    "episode_type": "shock",
    "chronotope_scope_id": "chrono.eaf.drought-food.MAM2026.adminKE-23",
    "sdz_tag": "sdz.sov.national"
  },
  "data": {
    "triggering_signals": [
      "evt.idx.eaf.spi.seasonal.2026M03.adminKE-23",
      "evt.alert.ew.drought.phase2.2026M03.adminKE-23"
    ],
    "aep_ids": [
      "aep.eaf.drought-food.seasonal.2026M03.v1",
      "aep.eaf.drought-food.trigger.2026M04.v1"
    ],
    "decisions_ids": [
      "dec.eaf.treasury.reallocate_budget.2026M04.01",
      "dec.eaf.drf.trigger.2026M04.window1"
    ],
    "actions_ids": [
      "act.eaf.cash_transfers.round1",
      "act.eaf.livestock_support.round1"
    ],
    "outcome_metrics": {
      "people_assisted": 850000,
      "median_assistance_delay_days": 16,
      "livestock_mortality_rate_pct": 8.5
    },
    "equity_distribution_metrics": {
      "share_assistance_women_headed_households_pct": 55.0,
      "share_assistance_pastoralist_households_pct": 62.0,
      "regional_coverage_variance_index": 0.18
    },
    "lessons_learned_refs": [
      "ll.eaf.drought.2026.after_action_report",
      "ll.eaf.drought.2026.community_feedback"
    ]
  },
  "extensions": {
    "grf_review_status": "pending",
    "nxacademy_case_flag": true
  }
}
```

***

#### D.4.2 Decision Event

```json
{
  "specversion": "1.0",
  "type": "nexus.decision.record",
  "source": "nxhive://dao.eaf.drought-food",
  "id": "dec.eaf.drf.trigger.2026M04.window1",
  "time": "2026-04-05T16:00:00Z",
  "subject": "capital_trigger.drf.eaf.drought.window1",
  "datacontenttype": "application/json",
  "nexus": {
    "rail_id": "nxsr.eaf.drought-food.v1",
    "decision_id": "dec.eaf.drf.trigger.2026M04.window1",
    "decision_type": "capital_trigger",
    "nrm_profile_id": "nrm.drought.food.sovereign_fiscal",
    "aep_id": "aep.eaf.drought-food.trigger.2026M04.v1",
    "nvm_quorum_profile": "nvm.4of6.gov-fin-infra-community.v1",
    "sdz_tag": "sdz.reg.regional"
  },
  "data": {
    "facility_id": "drf.eaf.drought.window1",
    "trigger_outcome": "TRIGGER_APPROVED",
    "approved_disbursement_amount_usd": 85000000,
    "approved_disbursement_share": 0.8,
    "decision_body": "RailDAO.eaf.drought-food",
    "jurisdiction": ["KE", "ET", "SO"],
    "voting_record": [
      {"member": "treasury.kenya", "vote": "yes"},
      {"member": "treasury.ethiopia", "vote": "yes"},
      {"member": "centralbank.regional", "vote": "yes"},
      {"member": "community.council.pastoralist_north_kenya", "vote": "yes"},
      {"member": "ndma.kenya", "vote": "abstain"},
      {"member": "independent_observer", "vote": "nonvoting"}
    ]
  },
  "extensions": {
    "legal_link": "contract://drf.eaf.drought.window1/section7.3",
    "ledger_anchor_tx_id": "ledger.eaf.decision.0xdeadbeef...",
    "signature": "base64..."
  }
}
```

***

### D.5 Common Event Envelope & Headers

Across **indices, alerts, AEP anchors, episodes, decisions, and agent actions**, Nexus recommends a **common event envelope**, with:

* `specversion`, `type`, `source`, `id`, `time`, `subject`, `datacontenttype` (CloudEvents-style).
* A `nexus` section carrying **rail\_id, sd z tag, EQL/CL context, profile/chronotope IDs**.
* A `data` section carrying **payload** aligned with GRIx & NXSS.
* An `extensions` section for **signatures, trace IDs, safety tiers, governance hints**.

In practice, these envelopes are hardened by:

* Machine-readable **JSON Schemas** and conformance tests (NXSS §3.9).
* **SDZ-aware routing** and policy tags via NXCOMMS.
* **Agent safety checks** and audit hooks in NXSOS and NXHIVE.

Together with the ontologies in Appendix C and configuration examples in Appendix B, these event formats show how NRM’s semantic, technical, and governance requirements converge into a **coherent, machine-verifiable event grammar** for the Nexus Rail.


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.therisk.global/organization/standardization/nexus-rail/nexus-based-risk-management-nrm/technology/appendices/aeps.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.