From e11c020e6f76ae1d77fc8b40cf02f7a9862c0804 Mon Sep 17 00:00:00 2001
From: Emelie-Dev <godfatheremerie@gmail.com>
Date: Sat, 30 May 2026 21:50:11 +0100
Subject: [PATCH] Map context error subcodes

---
 crates/core/src/decode/mappings/context.rs | 36 ++++++++++++++++++++++
 crates/core/src/decode/mappings/mod.rs     |  3 ++
 crates/core/src/decode/mod.rs              |  1 +
 crates/core/src/taxonomy/data/context.toml | 29 ++++++++++++++++-
 4 files changed, 68 insertions(+), 1 deletion(-)
 create mode 100644 crates/core/src/decode/mappings/context.rs
 create mode 100644 crates/core/src/decode/mappings/mod.rs

diff --git a/crates/core/src/decode/mappings/context.rs b/crates/core/src/decode/mappings/context.rs
new file mode 100644
index 00000000..617a3988
--- /dev/null
+++ b/crates/core/src/decode/mappings/context.rs
@@ -0,0 +1,36 @@
+//! Context error subcode mappings.
+//!
+//! Context errors describe problems with the Soroban execution environment or
+//! with host functions being invoked from the wrong execution context.
+
+/// Human-readable detail for a Context category host error subcode.
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub struct ContextErrorDetail {
+    pub code: u32,
+    pub name: &'static str,
+    pub summary: &'static str,
+    pub severity: &'static str,
+}
+
+/// All Context category subcodes currently emitted by soroban-env-host.
+pub const CONTEXT_ERROR_DETAILS: &[ContextErrorDetail] = &[
+    ContextErrorDetail {
+        code: 6,
+        name: "InvalidAction",
+        summary: "A host function was called in an execution context where that action is not valid; this usually points to contract code using the environment at the wrong time.",
+        severity: "Error",
+    },
+    ContextErrorDetail {
+        code: 7,
+        name: "InternalError",
+        summary: "The Soroban host hit an unexpected internal state; this points to the execution environment rather than normal contract logic.",
+        severity: "Fatal",
+    },
+];
+
+/// Look up detail for a Context category host error subcode.
+pub fn lookup_context_error(code: u32) -> Option<&'static ContextErrorDetail> {
+    CONTEXT_ERROR_DETAILS
+        .iter()
+        .find(|detail| detail.code == code)
+}
diff --git a/crates/core/src/decode/mappings/mod.rs b/crates/core/src/decode/mappings/mod.rs
new file mode 100644
index 00000000..3e74f80d
--- /dev/null
+++ b/crates/core/src/decode/mappings/mod.rs
@@ -0,0 +1,3 @@
+//! Static host error subcode mappings used by the decode engine.
+
+pub mod context;
diff --git a/crates/core/src/decode/mod.rs b/crates/core/src/decode/mod.rs
index 5c6352d7..d5c3d11a 100644
--- a/crates/core/src/decode/mod.rs
+++ b/crates/core/src/decode/mod.rs
@@ -7,6 +7,7 @@ pub mod context;
 pub mod contract_error;
 pub mod diagnostic;
 pub mod host_error;
+pub mod mappings;
 pub mod report;
 
 use crate::error::PrismResult;
diff --git a/crates/core/src/taxonomy/data/context.toml b/crates/core/src/taxonomy/data/context.toml
index fc790eeb..5955e4a2 100644
--- a/crates/core/src/taxonomy/data/context.toml
+++ b/crates/core/src/taxonomy/data/context.toml
@@ -6,10 +6,37 @@ name = "Context"
 description = "Errors triggered by invalid execution context, such as calling host functions outside of a valid invocation or re-entrancy violations."
 source_module = "soroban-env-host/src/host.rs"
 
+[[errors]]
+id = "host.context.invalid_action"
+category = "context"
+code = 6
+name = "InvalidAction"
+severity = "Error"
+since_protocol = 20
+summary = "A host function was called in an execution context where that action is not valid."
+detailed_explanation = """
+InvalidAction means the contract or host integration attempted an operation from the wrong \
+execution context, such as using a host capability before the host is ready or outside the \
+allowed invocation lifecycle. This usually points to contract or caller behavior, not a broken \
+network environment.
+"""
+
+[[errors.common_causes]]
+description = "Contract code or a host integration called an environment action outside its valid lifecycle"
+likelihood = "high"
+
+[[errors.suggested_fixes]]
+description = "Review where the host function is called and move it into a valid contract invocation context"
+difficulty = "medium"
+requires_upgrade = false
+
+related_errors = []
+source_file = "soroban-env-host/src/host.rs"
+
 [[errors]]
 id = "host.context.internal_error"
 category = "context"
-code = 0
+code = 7
 name = "InternalError"
 severity = "Fatal"
 since_protocol = 20