0.0.1-alpha.3

crates/knowledge-sync-api/src/lib.rs

@@ -0,0 +1,57 @@
+// file: crates/knowledge-sync-api/src/lib.rs
+// version: 1
+
+//! Contracts for provider-neutral repository synchronization signals.
+//!
+//! A signal requests reconciliation of a source. It is not authoritative content and does not
+//! replace resolution of the target Git revision by the Git repository contract.
+
+/// Coarse origin of a synchronization request.
+#[derive(Clone, Copy, Debug, Eq, PartialEq)]
+pub enum RepositorySyncCause {
+    /// An explicit request from an operator or application use case.
+    Explicit,
+    /// A periodic reconciliation independent of external hooks.
+    Periodic,
+    /// A non-authoritative external signal such as a Git hook, webhook or filesystem watcher.
+    ExternalSignal,
+}
+
+/// Request to reconcile one logical content source.
+#[derive(Clone, Debug, Eq, PartialEq)]
+pub struct RepositorySyncSignal {
+    source_id: knowledge_domain_lib::SourceId,
+    cause: crate::RepositorySyncCause,
+}
+
+impl crate::RepositorySyncSignal {
+    /// Build a synchronization signal for one source.
+    pub fn new(source_id: knowledge_domain_lib::SourceId, cause: crate::RepositorySyncCause) -> crate::RepositorySyncSignal {
+        return crate::RepositorySyncSignal { source_id, cause };
+    }
+
+    /// Return the source that must be reconciled.
+    pub fn source_id(&self) -> &knowledge_domain_lib::SourceId {
+        return &self.source_id;
+    }
+
+    /// Return the coarse trigger origin.
+    pub fn cause(&self) -> crate::RepositorySyncCause {
+        return self.cause;
+    }
+}
+
+/// Producer of synchronization signals.
+///
+/// Concrete implementations may represent explicit queues, polling, hooks, webhooks or other
+/// event mechanisms. The scheduling/runtime model remains outside this passive contract.
+pub trait RepositoryEventSource {
+    /// Implementation-specific recoverable error.
+    type Error;
+
+    /// Return the next available signal, or `None` when no signal is currently available.
+    fn next_signal(&mut self) -> Result<Option<crate::RepositorySyncSignal>, Self::Error>;
+}
+
+#[cfg(test)]
+mod unit_tests;