feat: type permanent log discontinuities (#3)

Co-authored-by: RoyLin <roylin@RoyLindeMacBook-Pro.local>

Author: ZhiXiao-Lin

README.md

@@ -50,7 +50,8 @@ their owning applications.
 - **Durable Local State**: Persist owner-only records atomically under
   cross-process locks without following symbolic-link state boundaries
 - **Logs and Exec**: Expose generation-bound log and exec surfaces only when a
-  provider reports the corresponding capability
+  provider reports the corresponding capability, with typed cursor-loss and
+  source-disconnect discontinuities
 - **Capability-Driven Conformance**: Always run complete Base and Recovery
   profiles, automatically activate advertised optional profiles, and reject
   missing fixtures, incomplete evidence, or provider inventory leaks
@@ -108,7 +109,7 @@ The `RuntimeClient` contract exposes:
 | `inspect` | Return the latest observation or a generation-aware absence |
 | `stop` | Stop the active generation without deleting durable identity |
 | `remove` | Remove the provider resource and persist an absence tombstone |
-| `logs` | Read strictly ordered, cursor-addressed log chunks |
+| `logs` | Read strictly ordered, cursor-addressed log chunks or return a typed permanent discontinuity |
 | `exec` | Execute a bounded command against the exact active generation |
 
 Each mutating request carries its own request ID and optional absolute deadline.
@@ -122,6 +123,14 @@ optional caller deadline. `RuntimeDriver::exec` receives that effective
 absolute deadline in `deadline_at_ms`, and every pending replay receives the
 same value, so retrying cannot restart or extend the execution window.
 
+Log transport or provider availability failures remain retryable errors. A
+provider that can prove the requested cursor was lost, or that the durable unit
+survives after its log source disappeared, instead returns
+`RuntimeError::LogDiscontinuity` with the exact unit, generation, requested
+cursor, and typed reason. Callers can durably project that boundary before
+resuming from the earliest currently available record without parsing error
+text.
+
 ## Capabilities
 
 Providers report supported unit classes, artifact media types, isolation

src/contract/mod.rs

@@ -17,7 +17,8 @@ pub use observation::{
 pub use process::{RuntimeProcessSpec, SecretReference, SecretTarget};
 pub use protocol::{
     RuntimeActionRequest, RuntimeApplyRequest, RuntimeExecRequest, RuntimeExecResult,
-    RuntimeLogChunk, RuntimeLogQuery, RuntimeLogStream, RuntimeRemoval,
+    RuntimeLogChunk, RuntimeLogDiscontinuityReason, RuntimeLogQuery, RuntimeLogStream,
+    RuntimeRemoval,
 };
 pub use resource::{IsolationLevel, ResourceLimits};
 pub use unit::{

src/contract/protocol.rs

@@ -103,6 +103,13 @@ pub enum RuntimeLogStream {
     Stderr,
 }
 
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
+#[serde(rename_all = "snake_case")]
+pub enum RuntimeLogDiscontinuityReason {
+    CursorLost,
+    SourceDisconnected,
+}
+
 #[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
 #[serde(deny_unknown_fields)]
 pub struct RuntimeLogQuery {
@@ -249,3 +256,22 @@ fn canonical_digest<T: Serialize>(value: &T, valid: Result<(), String>) -> Resul
         .map_err(|error| format!("could not encode Runtime request: {error}"))?;
     Ok(format!("sha256:{:x}", Sha256::digest(bytes)))
 }
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn log_discontinuity_reasons_have_stable_wire_names() {
+        assert_eq!(
+            serde_json::to_string(&RuntimeLogDiscontinuityReason::CursorLost)
+                .expect("serialize cursor loss"),
+            "\"cursor_lost\""
+        );
+        assert_eq!(
+            serde_json::to_string(&RuntimeLogDiscontinuityReason::SourceDisconnected)
+                .expect("serialize source disconnect"),
+            "\"source_disconnected\""
+        );
+    }
+}

src/error.rs

@@ -1,3 +1,4 @@
+use crate::contract::RuntimeLogDiscontinuityReason;
 use thiserror::Error;
 
 pub type RuntimeResult<T> = Result<T, RuntimeError>;
@@ -30,6 +31,15 @@ pub enum RuntimeError {
     ProviderUnavailable(String),
     #[error("Runtime transport failed: {0}")]
     Transport(String),
+    #[error(
+        "Runtime log source for unit {unit_id:?} generation {generation} is discontinuous: {reason:?}"
+    )]
+    LogDiscontinuity {
+        unit_id: String,
+        generation: u64,
+        cursor: Option<String>,
+        reason: RuntimeLogDiscontinuityReason,
+    },
     #[error("Runtime protocol failed: {0}")]
     Protocol(String),
 }