Skip to content
OpenFirma OpenFirma
Blog

envelope

Module: envelope

Section titled “Module: envelope”

Contents

Section titled “Contents”

Structs

Enums

  • ActionParams - Typed action parameters (maps to the proto oneof params).
  • HttpMethod - HTTP methods that can appear in an outbound request.

firma_core::envelope::ActionParams

Section titled “firma_core::envelope::ActionParams”

Enum

Typed action parameters (maps to the proto oneof params).

Uses an enum with typed variants to prevent injection via untyped maps.

Variants:

  • Http(HttpParams) - Outbound HTTP request.
  • DbQuery(DbQueryParams) - Database query.
  • ToolUse(ToolUseParams) - Tool/function invocation.

Traits: Eq

Trait Implementations:

  • Deserialize
    • fn deserialize<__D>(__deserializer: __D) -> _serde::__private228::Result<Self, <__D as >::Error>
  • Clone
    • fn clone(self: &Self) -> ActionParams
  • PartialEq
    • fn eq(self: &Self, other: &ActionParams) -> bool
  • Serialize
    • fn serialize<__S>(self: &Self, __serializer: __S) -> _serde::__private228::Result<<__S as >::Ok, <__S as >::Error>
  • Debug
    • fn fmt(self: &Self, f: & mut $crate::fmt::Formatter) -> $crate::fmt::Result

firma_core::envelope::DbQueryParams

Section titled “firma_core::envelope::DbQueryParams”

Struct

Parameters for a database query.

Uses a named query plus bindings instead of a raw SQL statement, aligning with the intent-003 proto definition and preventing raw SQL injection at the type level.

Fields:

  • query_name: String - Registered query name (looked up in a query registry).
  • bindings: std::collections::HashMap<String, String> - Bound parameters — scalar values only, keyed by placeholder name.
  • db_name: String - Target database name.
  • read_only: bool - Hint for policy: is this a read-only query?

Traits: Eq

Trait Implementations:

  • Serialize
    • fn serialize<__S>(self: &Self, __serializer: __S) -> _serde::__private228::Result<<__S as >::Ok, <__S as >::Error>
  • Debug
    • fn fmt(self: &Self, f: & mut $crate::fmt::Formatter) -> $crate::fmt::Result
  • Deserialize
    • fn deserialize<__D>(__deserializer: __D) -> _serde::__private228::Result<Self, <__D as >::Error>
  • Clone
    • fn clone(self: &Self) -> DbQueryParams
  • PartialEq
    • fn eq(self: &Self, other: &DbQueryParams) -> bool

firma_core::envelope::ExecutionContext

Section titled “firma_core::envelope::ExecutionContext”

Struct

Flattened attribute set consumed by policy evaluation (Stage 2).

Built from ExecutionEnvelope fields plus Sidecar-local state. The derivation of action and resource from the envelope’s intent is Sidecar-specific logic (added in intent 006).

Traits: Eq

Trait Implementations:

  • Serialize
    • fn serialize<__S>(self: &Self, __serializer: __S) -> _serde::__private228::Result<<__S as >::Ok, <__S as >::Error>
  • Debug
    • fn fmt(self: &Self, f: & mut $crate::fmt::Formatter) -> $crate::fmt::Result
  • Deserialize
    • fn deserialize<__D>(__deserializer: __D) -> _serde::__private228::Result<Self, <__D as >::Error>
  • Clone
    • fn clone(self: &Self) -> ExecutionContext
  • PartialEq
    • fn eq(self: &Self, other: &ExecutionContext) -> bool

firma_core::envelope::ExecutionEnvelope

Section titled “firma_core::envelope::ExecutionEnvelope”

Struct

The core protocol unit wrapping each outbound agent call.

Built by the Sidecar when intercepting an agent’s request. Contains the typed action intent, the raw capability token, metadata, and provenance. Immutable once created — any enrichment produces a derived structure.

Fields:

  • intent: ExecutionIntent - Typed action parameters describing what the agent wants to do.

Methods:

  • fn new(intent: ExecutionIntent, capability: String, metadata: ExecutionMetadata, provenance: Option<String>) -> Self - Constructs a new ExecutionEnvelope.
  • fn intent(self: &Self) -> &ExecutionIntent - Gets the typed action parameters describing what the agent wants to do.
  • fn capability(self: &Self) -> &str - Gets the raw signed token string.
  • fn metadata(self: &Self) -> &ExecutionMetadata - Gets the session and runtime metadata for correlation and audit.
  • fn provenance(self: &Self) -> Option<&str> - Gets the schema-reserved provenance field.

Trait Implementations:

  • Serialize
    • fn serialize<__S>(self: &Self, __serializer: __S) -> _serde::__private228::Result<<__S as >::Ok, <__S as >::Error>
  • Clone
    • fn clone(self: &Self) -> ExecutionEnvelope
  • Deserialize
    • fn deserialize<__D>(__deserializer: __D) -> _serde::__private228::Result<Self, <__D as >::Error>
  • PartialEq
    • fn eq(self: &Self, other: &ExecutionEnvelope) -> bool
  • Debug
    • fn fmt(self: &Self, f: & mut $crate::fmt::Formatter) -> $crate::fmt::Result

firma_core::envelope::ExecutionIntent

Section titled “firma_core::envelope::ExecutionIntent”

Struct

Typed description of the action an agent intends to perform.

Contains five canonical intent sub-fields: action_class, resource, params, raw_transport, and raw_action_ref. The action_class is the canonical class from the v0.1 Action Class Registry, set by the Sidecar’s intent normalizer after mapping the raw intercepted request.

Fields:

  • action_class: String - Canonical action class from the v0.1 registry (e.g.,
  • resource: std::collections::BTreeMap<String, String> - Target resource identifier as a structured attribute map.
  • params: ActionParams - Typed action parameters — exactly one action kind per intent.
  • raw_transport: String - Original transport protocol (e.g., "http", "https").
  • raw_action_ref: String - Original request signature for traceability (e.g., "POST /v1/chat/completions").

Methods:

  • fn policy_resource_display(self: &Self) -> String - Derive the logical resource used for policy and audit.
  • fn resource_display(self: &Self) -> String - Derive a display / scope-check string from the resource map.
  • fn resource_map_from(host_path: &str) -> BTreeMap<String, String> - Build a resource map from a display-form string host[/path].

Traits: Eq

Trait Implementations:

  • PartialEq
    • fn eq(self: &Self, other: &ExecutionIntent) -> bool
  • Serialize
    • fn serialize<__S>(self: &Self, __serializer: __S) -> _serde::__private228::Result<<__S as >::Ok, <__S as >::Error>
  • Debug
    • fn fmt(self: &Self, f: & mut $crate::fmt::Formatter) -> $crate::fmt::Result
  • Deserialize
    • fn deserialize<__D>(__deserializer: __D) -> _serde::__private228::Result<Self, <__D as >::Error>
  • Clone
    • fn clone(self: &Self) -> ExecutionIntent

firma_core::envelope::ExecutionMetadata

Section titled “firma_core::envelope::ExecutionMetadata”

Struct

Session and runtime context attached to every execution envelope.

Fields:

  • session_id: firma_identifiers::SessionId - Session this request belongs to.
  • agent_id: firma_identifiers::AgentId - Agent that initiated this request.
  • timestamp: chrono::DateTime<chrono::Utc> - When the request was intercepted.
  • trace_id: Option<String> - Optional distributed tracing correlation ID.
  • risk_score: Option<f64> - Static or pre-computed risk attribute. Defaults to None.
  • thread_id: Option<String> - Server-derived conversation thread identity (AARM R2 G2). Groups
  • parent_action_id: Option<String> - Server-derived parent action identity (AARM R2 G2). The provenance

Trait Implementations:

  • PartialEq
    • fn eq(self: &Self, other: &ExecutionMetadata) -> bool
  • Debug
    • fn fmt(self: &Self, f: & mut $crate::fmt::Formatter) -> $crate::fmt::Result
  • Serialize
    • fn serialize<__S>(self: &Self, __serializer: __S) -> _serde::__private228::Result<<__S as >::Ok, <__S as >::Error>
  • Clone
    • fn clone(self: &Self) -> ExecutionMetadata
  • Deserialize
    • fn deserialize<__D>(__deserializer: __D) -> _serde::__private228::Result<Self, <__D as >::Error>

firma_core::envelope::HttpMethod

Section titled “firma_core::envelope::HttpMethod”

Enum

HTTP methods that can appear in an outbound request.

Restricts the method to known values so that invalid strings (e.g., "WHATEVER") are rejected at the type level.

Variants:

  • GET
  • POST
  • PUT
  • DELETE
  • PATCH
  • HEAD
  • OPTIONS
  • CONNECT

Methods:

  • fn as_str(self: Self) -> &'static str - Stable static label used by structured logs and metrics.

Traits: Eq, Copy

Trait Implementations:

  • Debug
    • fn fmt(self: &Self, f: & mut $crate::fmt::Formatter) -> $crate::fmt::Result
  • Deserialize
    • fn deserialize<__D>(__deserializer: __D) -> _serde::__private228::Result<Self, <__D as >::Error>
  • Display
    • fn fmt(self: &Self, f: & mut fmt::Formatter) -> fmt::Result
  • PartialEq
    • fn eq(self: &Self, other: &HttpMethod) -> bool
  • Clone
    • fn clone(self: &Self) -> HttpMethod
  • Serialize
    • fn serialize<__S>(self: &Self, __serializer: __S) -> _serde::__private228::Result<<__S as >::Ok, <__S as >::Error>
  • TryFrom
    • fn try_from(value: &'a Method) -> Result<Self, <Self as >::Error>

firma_core::envelope::HttpParams

Section titled “firma_core::envelope::HttpParams”

Struct

Parameters for an outbound HTTP request.

The target URL lives on ExecutionIntent.resource, not here — matching the proto where HttpParams carries method, headers, body, and query.

Fields:

  • method: HttpMethod - HTTP method.
  • headers: firma_http::HeaderMap - HTTP headers — allowlisted keys only.
  • body: Option<Vec<u8>> - Request body as raw bytes (empty for GET/DELETE).
  • query: std::collections::HashMap<String, String> - Query parameters.

Traits: Eq

Trait Implementations:

  • PartialEq
    • fn eq(self: &Self, other: &HttpParams) -> bool
  • Serialize
    • fn serialize<__S>(self: &Self, __serializer: __S) -> _serde::__private228::Result<<__S as >::Ok, <__S as >::Error>
  • Debug
    • fn fmt(self: &Self, f: & mut $crate::fmt::Formatter) -> $crate::fmt::Result
  • Deserialize
    • fn deserialize<__D>(__deserializer: __D) -> _serde::__private228::Result<Self, <__D as >::Error>
  • Clone
    • fn clone(self: &Self) -> HttpParams

firma_core::envelope::InvalidMethod

Section titled “firma_core::envelope::InvalidMethod”

Struct

Generic Parameters:

  • ‘a

Tuple Struct: ()

Traits: Error

Trait Implementations:

  • Debug
    • fn fmt(self: &Self, f: & mut $crate::fmt::Formatter) -> $crate::fmt::Result
  • Display
    • fn fmt(self: &Self, __formatter: & mut ::core::fmt::Formatter) -> ::core::fmt::Result

firma_core::envelope::ToolUseParams

Section titled “firma_core::envelope::ToolUseParams”

Struct

Parameters for a tool/function invocation.

Input is a flat String → String map (scalar values only), schema-validated against the tool registry. Aligns with the intent-003 proto definition and keeps the core→proto conversion trivial.

Fields:

  • tool_name: String - Name of the tool to invoke.
  • input: std::collections::HashMap<String, String> - Scalar tool inputs, validated against the tool registry schema.

Traits: Eq

Trait Implementations:

  • Serialize
    • fn serialize<__S>(self: &Self, __serializer: __S) -> _serde::__private228::Result<<__S as >::Ok, <__S as >::Error>
  • Debug
    • fn fmt(self: &Self, f: & mut $crate::fmt::Formatter) -> $crate::fmt::Result
  • Deserialize
    • fn deserialize<__D>(__deserializer: __D) -> _serde::__private228::Result<Self, <__D as >::Error>
  • Clone
    • fn clone(self: &Self) -> ToolUseParams
  • PartialEq
    • fn eq(self: &Self, other: &ToolUseParams) -> bool