Crate systemprompt_identifiers

Expand description

Typed newtype identifiers for systemprompt.io.

Every entity in the platform is referenced through a wrapper newtype rather than a raw String.

This crate provides both the macros that generate those wrappers (define_id!, define_token!) and the canonical concrete types (UserId, AgentId, TaskId, TraceId, ContextId, SessionId, McpServerId, …).

Boundary types for talking to the database — DbValue, ToDbValue, FromDbValue, JsonRow — also live here so that identifier modules can interoperate without depending on the database crate.

§Construction

use systemprompt_identifiers::{TaskId, UserId};

// A value already known to be valid (a decoded DB row).
let task = TaskId::new("task_abc");

// A value from outside (header, path segment, JWT claim): validate it.
let user = UserId::try_new(raw_sub)?;

// Mint a fresh UUID-backed identifier.
let fresh = UserId::generate();

Validated identifiers (ContextId, Email, ProfileName, ValidatedUrl, ValidatedFilePath, RoleId, …) expose only the fallible try_new constructor returning error::IdValidationError; there is no infallible new that could panic on runtime input. Values minted by the platform itself (ContextId::generate, AgentName::system) come from dedicated constructors.

Checked identifiers (UserId, ServiceName, AgentName, McpServerId, McpToolName, PluginId, SkillId, …) have both: try_new validates input from outside, new accepts a value already known valid (a decoded row, a configuration key validated at load). They implement no From<String>, and their Deserialize/FromStr validate.

“Absent” is Option<Id>, never a sentinel value such as "unset", "unknown" or the empty string.

gateway_hash is the deterministic prefix hash that mints a GatewayConversationId identically on both sides of the bridge boundary.

§Feature flags

Feature	Effect
(default)	Pure-Rust types only.
`sqlx`	Derives `sqlx::Type` on every identifier, allowing direct binding in `query_as!` macros.

Copyright (c) systemprompt.io — Business Source License 1.1. See https://systemprompt.io for licensing details.

Re-exports§

pub use db_value::DbValue;
pub use db_value::FromDbValue;
pub use db_value::JsonRow;
pub use db_value::ToDbValue;
pub use db_value::parse_database_datetime;

Modules§

db_value: Database-value abstraction shared between repository code and the identifier crate.
error: Error types raised by identifier validation and database value conversion.
gateway_hash: Stable conversation-prefix hash used to mint deterministic GatewayConversationIds on both sides of the bridge boundary.
headers: Canonical HTTP header name constants used throughout the platform for propagating trace, session, and authorization context across services.
macros: Declarative macros that generate the typed identifier and token newtypes.