chore: establish phase 0 baseline

2026-07-18 18:20:34 -04:00
commit b38da7d53f
42 changed files with 2618 additions and 0 deletions
@@ -0,0 +1,11 @@
+[package]
+name = "kiln-core"
+version.workspace = true
+edition.workspace = true
+rust-version.workspace = true
+license.workspace = true
+publish.workspace = true
+
+[lints]
+workspace = true
+
@@ -0,0 +1,107 @@
+//! Shared, provider-independent contracts for Project Kiln.
+
+use std::fmt;
+use std::str::FromStr;
+
+/// Schema version emitted by the initial private machine-readable smoke path.
+pub const CONTRACT_SCHEMA_VERSION: u32 = 1;
+
+/// A store-qualified game identity such as `steam:620` or `native:supertuxkart`.
+#[derive(Clone, Debug, Eq, Hash, PartialEq)]
+pub struct GameId {
+    namespace: String,
+    value: String,
+}
+
+impl GameId {
+    /// Returns the provider/store namespace.
+    #[must_use]
+    pub fn namespace(&self) -> &str {
+        &self.namespace
+    }
+
+    /// Returns the provider-owned identity value.
+    #[must_use]
+    pub fn value(&self) -> &str {
+        &self.value
+    }
+}
+
+impl fmt::Display for GameId {
+    fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
+        write!(formatter, "{}:{}", self.namespace, self.value)
+    }
+}
+
+/// Why a game identity could not be parsed.
+#[derive(Clone, Debug, Eq, PartialEq)]
+pub enum GameIdError {
+    /// The `namespace:value` separator is absent.
+    MissingSeparator,
+    /// The namespace is empty or contains unsupported characters.
+    InvalidNamespace,
+    /// The provider-owned value is empty or contains control characters.
+    InvalidValue,
+}
+
+impl fmt::Display for GameIdError {
+    fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
+        let message = match self {
+            Self::MissingSeparator => "game ID must contain a ':' separator",
+            Self::InvalidNamespace => "game ID namespace must be lowercase ASCII",
+            Self::InvalidValue => {
+                "game ID value must be non-empty and contain no control characters"
+            }
+        };
+        formatter.write_str(message)
+    }
+}
+
+impl std::error::Error for GameIdError {}
+
+impl FromStr for GameId {
+    type Err = GameIdError;
+
+    fn from_str(raw: &str) -> Result<Self, Self::Err> {
+        let (namespace, value) = raw.split_once(':').ok_or(GameIdError::MissingSeparator)?;
+        if namespace.is_empty()
+            || !namespace
+                .bytes()
+                .all(|byte| byte.is_ascii_lowercase() || byte.is_ascii_digit() || byte == b'-')
+        {
+            return Err(GameIdError::InvalidNamespace);
+        }
+        if value.is_empty() || value.chars().any(char::is_control) {
+            return Err(GameIdError::InvalidValue);
+        }
+        Ok(Self {
+            namespace: namespace.to_owned(),
+            value: value.to_owned(),
+        })
+    }
+}
+#[cfg(test)]
+mod tests {
+    use super::{GameId, GameIdError};
+
+    #[test]
+    fn accepts_store_qualified_identity() {
+        let id: GameId = "steam:620".parse().expect("valid ID");
+        assert_eq!(id.namespace(), "steam");
+        assert_eq!(id.value(), "620");
+        assert_eq!(id.to_string(), "steam:620");
+    }
+
+    #[test]
+    fn rejects_unqualified_identity() {
+        assert_eq!("620".parse::<GameId>(), Err(GameIdError::MissingSeparator));
+    }
+
+    #[test]
+    fn rejects_shell_hostile_namespace() {
+        assert_eq!(
+            "steam;touch:620".parse::<GameId>(),
+            Err(GameIdError::InvalidNamespace)
+        );
+    }
+}