0.0.2-alpha.4

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

@@ -1,84 +1,24 @@
 // file: crates/knowledge-git-api/src/lib.rs
-// version: 3
+// version: 4
 
 //! Provider-neutral contracts for Git-backed Knowledge sources.
 //!
 //! This crate deliberately contains no forge API, process runner, filesystem checkout or database
 //! implementation. Concrete Git backends depend on this contract, not the reverse.
 
+mod reference;
+mod repository;
+mod revision;
+mod snapshot;
+
 /// Opaque Git reference requested by a caller, such as a branch, tag or object expression.
-#[derive(Clone, Debug, Eq, Hash, PartialEq)]
-pub struct GitReference(String);
-
-impl crate::GitReference {
-    /// Create an opaque Git reference without imposing one provider's reference grammar.
-    pub fn new(value: &str) -> crate::GitReference {
-        return crate::GitReference(value.to_owned());
-    }
-
-    /// Return the reference text.
-    pub fn as_str(&self) -> &str {
-        return self.0.as_str();
-    }
-}
-
-/// Resolved authoritative Git revision identity.
-#[derive(Clone, Debug, Eq, Hash, PartialEq)]
-pub struct GitRevision(String);
-
-impl crate::GitRevision {
-    /// Create a revision identity returned by a concrete Git implementation.
-    pub fn new(value: &str) -> crate::GitRevision {
-        return crate::GitRevision(value.to_owned());
-    }
-
-    /// Return the revision identity as text.
-    pub fn as_str(&self) -> &str {
-        return self.0.as_str();
-    }
-}
-
-/// Read-only local materialization of one authoritative Git revision.
-#[derive(Clone, Debug, Eq, PartialEq)]
-pub struct GitSnapshot {
-    path: std::path::PathBuf,
-    revision: crate::GitRevision,
-}
-
-impl crate::GitSnapshot {
-    /// Build a snapshot contract from a resolved revision and its local read root.
-    pub fn new(revision: crate::GitRevision, path: std::path::PathBuf) -> crate::GitSnapshot {
-        return crate::GitSnapshot { path, revision };
-    }
-
-    /// Return the local root containing the materialized repository content.
-    pub fn path(&self) -> &std::path::Path {
-        return self.path.as_path();
-    }
-
-    /// Return the authoritative revision represented by the snapshot.
-    pub fn revision(&self) -> &crate::GitRevision {
-        return &self.revision;
-    }
-}
-
+pub use self::reference::GitReference;
 /// Provider-neutral operations required from a Git repository backend.
-///
-/// Implementations may use a local Git executable, a Rust Git library or another generic Git
-/// mechanism. Forge-only capabilities do not belong to this trait.
-pub trait GitRepository {
-    /// Implementation-specific recoverable error.
-    type Error;
-
-    /// Refresh the local view of one configured source when the backend requires it.
-    fn refresh(&mut self, source_id: &knowledge_domain_lib::SourceId) -> Result<(), Self::Error>;
-
-    /// Resolve one opaque reference to the authoritative revision used by synchronization.
-    fn resolve_revision(&self, source_id: &knowledge_domain_lib::SourceId, reference: &crate::GitReference) -> Result<crate::GitRevision, Self::Error>;
-
-    /// Prepare or validate a read-only local snapshot for one resolved revision.
-    fn prepare_snapshot(&self, source_id: &knowledge_domain_lib::SourceId, revision: &crate::GitRevision) -> Result<crate::GitSnapshot, Self::Error>;
-}
+pub use self::repository::GitRepository;
+/// Resolved authoritative Git revision identity.
+pub use self::revision::GitRevision;
+/// Read-only local materialization of one authoritative Git revision.
+pub use self::snapshot::GitSnapshot;
 
 #[cfg(test)]
 #[path = "../unit_tests/lib.rs"]

crates/knowledge-git-api/src/reference.rs

@@ -0,0 +1,18 @@
+// file: crates/knowledge-git-api/src/reference.rs
+// version: 1
+
+/// Opaque Git reference requested by a caller, such as a branch, tag or object expression.
+#[derive(Clone, Debug, Eq, Hash, PartialEq)]
+pub struct GitReference(String);
+
+impl crate::GitReference {
+    /// Create an opaque Git reference without imposing one provider's reference grammar.
+    pub fn new(value: &str) -> crate::GitReference {
+        return crate::GitReference(value.to_owned());
+    }
+
+    /// Return the reference text.
+    pub fn as_str(&self) -> &str {
+        return self.0.as_str();
+    }
+}

crates/knowledge-git-api/src/repository.rs

@@ -0,0 +1,20 @@
+// file: crates/knowledge-git-api/src/repository.rs
+// version: 1
+
+/// Provider-neutral operations required from a Git repository backend.
+///
+/// Implementations may use a local Git executable, a Rust Git library or another generic Git
+/// mechanism. Forge-only capabilities do not belong to this trait.
+pub trait GitRepository {
+    /// Implementation-specific recoverable error.
+    type Error;
+
+    /// Refresh the local view of one configured source when the backend requires it.
+    fn refresh(&mut self, source_id: &knowledge_domain_lib::SourceId) -> Result<(), Self::Error>;
+
+    /// Resolve one opaque reference to the authoritative revision used by synchronization.
+    fn resolve_revision(&self, source_id: &knowledge_domain_lib::SourceId, reference: &crate::GitReference) -> Result<crate::GitRevision, Self::Error>;
+
+    /// Prepare or validate a read-only local snapshot for one resolved revision.
+    fn prepare_snapshot(&self, source_id: &knowledge_domain_lib::SourceId, revision: &crate::GitRevision) -> Result<crate::GitSnapshot, Self::Error>;
+}

crates/knowledge-git-api/src/revision.rs

@@ -0,0 +1,18 @@
+// file: crates/knowledge-git-api/src/revision.rs
+// version: 1
+
+/// Resolved authoritative Git revision identity.
+#[derive(Clone, Debug, Eq, Hash, PartialEq)]
+pub struct GitRevision(String);
+
+impl crate::GitRevision {
+    /// Create a revision identity returned by a concrete Git implementation.
+    pub fn new(value: &str) -> crate::GitRevision {
+        return crate::GitRevision(value.to_owned());
+    }
+
+    /// Return the revision identity as text.
+    pub fn as_str(&self) -> &str {
+        return self.0.as_str();
+    }
+}

crates/knowledge-git-api/src/snapshot.rs

@@ -0,0 +1,26 @@
+// file: crates/knowledge-git-api/src/snapshot.rs
+// version: 1
+
+/// Read-only local materialization of one authoritative Git revision.
+#[derive(Clone, Debug, Eq, PartialEq)]
+pub struct GitSnapshot {
+    path: std::path::PathBuf,
+    revision: crate::GitRevision,
+}
+
+impl crate::GitSnapshot {
+    /// Build a snapshot contract from a resolved revision and its local read root.
+    pub fn new(revision: crate::GitRevision, path: std::path::PathBuf) -> crate::GitSnapshot {
+        return crate::GitSnapshot { path, revision };
+    }
+
+    /// Return the local root containing the materialized repository content.
+    pub fn path(&self) -> &std::path::Path {
+        return self.path.as_path();
+    }
+
+    /// Return the authoritative revision represented by the snapshot.
+    pub fn revision(&self) -> &crate::GitRevision {
+        return &self.revision;
+    }
+}

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

@@ -0,0 +1,14 @@
+// file: crates/knowledge-sync-api/src/event_source.rs
+// version: 1
+
+/// 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>;
+}

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

@@ -1,57 +1,20 @@
 // file: crates/knowledge-sync-api/src/lib.rs
-// version: 2
+// version: 3
 
 //! 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;
-    }
-}
+mod event_source;
+mod signal;
 
 /// 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>;
-}
+pub use self::event_source::RepositoryEventSource;
+/// Coarse origin of a synchronization request.
+pub use self::signal::RepositorySyncCause;
+/// Request to reconcile one logical content source.
+pub use self::signal::RepositorySyncSignal;
 
 #[cfg(test)]
 #[path = "../unit_tests/lib.rs"]

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

@@ -0,0 +1,37 @@
+// file: crates/knowledge-sync-api/src/signal.rs
+// version: 1
+
+/// 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;
+    }
+}