af_context/

ids.rs

//! Branded identifiers shared by every Factory crate.
//!
//! Each id is a distinct newtype over a non-empty string so a `SessionId` can
//! never be passed where a `RunId` is expected. Serialization, `Display`,
//! ordering and hashing behave like the underlying string; store adapters bind
//! [`as_str`](TenantId::as_str) and wire adapters convert with `TryFrom<String>`
//! / [`FromStr`], which reject empty or whitespace-only input. UUID-backed
//! stores may use infallible `From<uuid::Uuid>`; there is no `Default`.

use std::borrow::Borrow;
use std::fmt;
use std::str::FromStr;

/// The value given to an id constructor was empty or whitespace.
#[derive(Debug, Clone, PartialEq, Eq, thiserror::Error)]
#[error("{0} must not be empty")]
pub struct EmptyId(pub &'static str);

macro_rules! define_id {
    ($(#[$doc:meta])* $name:ident) => {
        $(#[$doc])*
        #[derive(Clone, PartialEq, Eq, PartialOrd, Ord, Hash, serde::Serialize, serde::Deserialize)]
        #[cfg_attr(feature = "sqlx", derive(sqlx::Type), sqlx(transparent))]
        #[serde(try_from = "String", into = "String")]
        pub struct $name(String);

        impl $name {
            /// Wraps a non-empty string; the only constructor, also used by
            /// `TryFrom`, `FromStr` and `Deserialize`.
            pub fn parse(value: impl Into<String>) -> Result<Self, EmptyId> {
                let value = value.into();
                if value.trim().is_empty() {
                    return Err(EmptyId(stringify!($name)));
                }
                Ok(Self(value))
            }

            /// Borrows the identifier as a string slice.
            pub fn as_str(&self) -> &str {
                &self.0
            }

            /// Consumes the identifier and returns the owned string.
            pub fn into_string(self) -> String {
                self.0
            }
        }

        impl fmt::Debug for $name {
            fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
                write!(f, "{}({:?})", stringify!($name), self.0)
            }
        }

        impl fmt::Display for $name {
            fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
                f.write_str(&self.0)
            }
        }

        impl FromStr for $name {
            type Err = EmptyId;
            fn from_str(value: &str) -> Result<Self, EmptyId> {
                Self::parse(value)
            }
        }

        impl TryFrom<String> for $name {
            type Error = EmptyId;
            fn try_from(value: String) -> Result<Self, EmptyId> {
                Self::parse(value)
            }
        }

        impl TryFrom<&str> for $name {
            type Error = EmptyId;
            fn try_from(value: &str) -> Result<Self, EmptyId> {
                Self::parse(value)
            }
        }

        impl TryFrom<&String> for $name {
            type Error = EmptyId;
            fn try_from(value: &String) -> Result<Self, EmptyId> {
                Self::parse(value.as_str())
            }
        }

        impl From<&$name> for $name {
            fn from(value: &$name) -> Self {
                value.clone()
            }
        }

        impl From<uuid::Uuid> for $name {
            fn from(value: uuid::Uuid) -> Self {
                Self(value.to_string())
            }
        }

        impl From<$name> for String {
            fn from(value: $name) -> Self {
                value.0
            }
        }

        impl AsRef<str> for $name {
            fn as_ref(&self) -> &str {
                &self.0
            }
        }

        impl Borrow<str> for $name {
            fn borrow(&self) -> &str {
                &self.0
            }
        }

        impl std::ops::Deref for $name {
            type Target = str;
            fn deref(&self) -> &str {
                &self.0
            }
        }

        impl PartialEq<str> for $name {
            fn eq(&self, other: &str) -> bool {
                self.0 == other
            }
        }

        impl PartialEq<&str> for $name {
            fn eq(&self, other: &&str) -> bool {
                self.0 == *other
            }
        }

        impl PartialEq<String> for $name {
            fn eq(&self, other: &String) -> bool {
                &self.0 == other
            }
        }

        impl PartialEq<$name> for String {
            fn eq(&self, other: &$name) -> bool {
                self == &other.0
            }
        }

        impl PartialEq<$name> for &str {
            fn eq(&self, other: &$name) -> bool {
                *self == other.0
            }
        }
    };
}

define_id!(
    /// Tenant that owns every durable record.
    TenantId
);
define_id!(
    /// Authenticated subject acting inside a tenant.
    SubjectId
);
define_id!(
    /// Transport request identity used for tracing and idempotency.
    RequestId
);
define_id!(
    /// Append-only Agent Session identity.
    SessionId
);
define_id!(
    /// One Run inside a Session.
    RunId
);
define_id!(
    /// One queued input inside a Session inbox.
    InputId
);
define_id!(
    /// Correlates a tool call with its result.
    ToolCallId
);
define_id!(
    /// One interaction (approval or question) awaiting resolution.
    InteractionId
);
define_id!(
    /// Stable identity of an installable capability definition.
    CapabilityId
);
define_id!(
    /// Immutable Agent Profile revision pinned by a Session.
    ProfileRevisionId
);
define_id!(
    /// Durable workflow instance identity.
    InstanceId
);
define_id!(
    /// Tenant-scoped immutable workflow definition identity.
    WorkflowDefinitionId
);
define_id!(
    /// Durable workflow action intent identity.
    ActionIntentId
);
define_id!(
    /// Immutable workflow proposal and decision identity.
    WorkflowDraftId
);
define_id!(
    /// One durable workflow step fact.
    WorkflowStepId
);
define_id!(
    /// Docs tree node (folder or document) identity.
    NodeId
);
define_id!(
    /// Docs Space identity.
    SpaceId
);
define_id!(
    /// Durable notification identity.
    NotificationId
);
define_id!(
    /// Append-only notification delivery-attempt event identity.
    NotificationAttemptId
);
define_id!(
    /// Durable dead-letter identity exposed to operators.
    DeadLetterId
);
define_id!(
    /// Stable identity of one normalized content item.
    NewsItemId
);
define_id!(
    /// Tenant-owned binding between a content source and Docs.
    NewsSourceBindingId
);
define_id!(
    /// Durable content-ingestion run identity.
    NewsIngestRunId
);
define_id!(
    /// Durable deterministic replay definition identity.
    BacktestDefinitionId
);
define_id!(
    /// Durable deterministic replay run identity.
    BacktestRunId
);
define_id!(
    /// Product-owned usage reservation identity.
    UsageReservationId
);
define_id!(
    /// Product action awaiting authorization.
    ActionCandidateId
);
define_id!(
    /// Immutable Docs revision identity.
    RevisionId
);
define_id!(
    /// Docs asset identity.
    AssetId
);
define_id!(
    /// Immutable Docs release identity.
    ReleaseId
);
define_id!(
    /// Durable Docs translation request identity.
    TranslationRequestId
);
define_id!(
    /// Docs invitation identity.
    InviteId
);
define_id!(
    /// Authenticated live-editing session for one Docs node.
    DocsCollaborationSessionId
);
define_id!(
    /// Idempotency identity for a durable command.
    CommandId
);
define_id!(
    /// One controlled consumer migration split into bounded batches.
    MigrationId
);
define_id!(
    /// Stable source identity of one normalized migration record.
    MigrationRecordId
);

define_id!(
    /// Immutable Agent Session sharing snapshot identity.
    SessionSnapshotId
);

#[cfg(test)]
mod tests {
    use super::*;

    #[test]
    fn ids_are_distinct_types_with_string_behaviour() {
        let session = SessionId::try_from("s1").unwrap();
        assert_eq!(session, "s1");
        assert_eq!(session.to_string(), "s1");
        assert_eq!(serde_json::to_string(&session).unwrap(), "\"s1\"");
        let parsed: SessionId = serde_json::from_str("\"s2\"").unwrap();
        assert_eq!(parsed.as_str(), "s2");
        assert_eq!(format!("{session:?}"), "SessionId(\"s1\")");
        assert_eq!(SessionId::parse("  "), Err(EmptyId("SessionId")));
        assert!("".parse::<RunId>().is_err());
        let mut set = std::collections::BTreeSet::new();
        set.insert(RunId::try_from(String::from("r")).unwrap());
        assert!(set.contains("r"));
    }

    #[test]
    fn every_constructor_rejects_empty_and_whitespace() {
        for blank in ["", "  ", "\t\n"] {
            assert_eq!(TenantId::try_from(blank), Err(EmptyId("TenantId")));
            assert_eq!(
                TenantId::try_from(blank.to_owned()),
                Err(EmptyId("TenantId"))
            );
            assert_eq!(
                TenantId::try_from(&blank.to_owned()),
                Err(EmptyId("TenantId"))
            );
            assert_eq!(blank.parse::<TenantId>(), Err(EmptyId("TenantId")));
            let json = serde_json::to_string(blank).unwrap();
            let rejected = serde_json::from_str::<TenantId>(&json).unwrap_err();
            assert!(
                rejected.to_string().contains("TenantId must not be empty"),
                "{rejected}"
            );
            #[derive(serde::Deserialize)]
            struct Envelope {
                #[allow(dead_code)]
                tenant_id: TenantId,
            }
            assert!(
                serde_json::from_str::<Envelope>(&format!("{{\"tenant_id\":{json}}}")).is_err()
            );
        }
    }
}

define_id! { /// Branch identity within a pinned workflow spec.
    BranchId
}

define_id! {
    /// Durable identity of one provider invocation.
    ProviderAttemptId
}

define_id! {
    /// Idempotency identity of a reported measurement correction.
    MeteringCorrectionId
}

define_id! {
    /// Immutable Profile proposal identity.
    ProfileDraftId
}

define_id! {
    /// Durable subject-owned Memory identity.
    MemoryId
}

define_id! {
    /// Host-defined workflow source identity.
    WorkflowSourceId
}
define_id! {
    /// Host-defined connection or external resource identity for workflow admission.
    WorkflowResourceId
}