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.

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.

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

{
  "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

{
  "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

{
  "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

{
  "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

{
  "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

{
  "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

{
  "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

{
  "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.

PreviousOntologies

NextDSL

Last updated 9 months ago

Was this helpful?