Merge pull request #325 from flyingrobots/cycle/0012-witnessed-suffix-posture-canonicalization-red

Canonical witnessed suffix posture constructors

Author: flyingrobots

crates/warp-core/src/lib.rs

@@ -252,7 +252,8 @@ pub use warp_state::{WarpInstance, WarpState};
 pub use witnessed_suffix::{
     evaluate_witnessed_suffix_admission, WitnessedSuffixAdmissionContext,
     WitnessedSuffixAdmissionOutcome, WitnessedSuffixAdmissionRequest,
-    WitnessedSuffixAdmissionResponse, WitnessedSuffixLocalAdmissionPosture, WitnessedSuffixShell,
+    WitnessedSuffixAdmissionResponse, WitnessedSuffixLocalAdmissionPosture,
+    WitnessedSuffixLocalAdmissionPostureError, WitnessedSuffixShell,
 };
 pub use worldline::{
     ApplyError, AtomWrite, AtomWriteSet, HashTriplet, OutputFrameSet, WorldlineId,

crates/warp-core/src/witnessed_suffix.rs

@@ -8,6 +8,7 @@
 
 use blake3::Hasher;
 use echo_wasm_abi::{encode_cbor, kernel_port as abi};
+use thiserror::Error;
 
 use crate::attachment::{AttachmentOwner, AttachmentPlane};
 use crate::clock::WorldlineTick;
@@ -139,22 +140,48 @@ pub trait WitnessedSuffixAdmissionContext {
     ) -> WitnessedSuffixLocalAdmissionPosture;
 }
 
+/// Error returned when constructing a canonical local admission posture fails.
+#[derive(Clone, Copy, Debug, PartialEq, Eq, Error)]
+pub enum WitnessedSuffixLocalAdmissionPostureError {
+    /// A provenance coordinate appeared more than once in a posture vector.
+    #[error("duplicate witnessed suffix local admission provenance ref: {provenance_ref:?}")]
+    DuplicateProvenanceRef {
+        /// Duplicate provenance coordinate.
+        provenance_ref: ProvenanceRef,
+    },
+}
+
 /// Local posture reported by the read-only admission context.
+///
+/// Prefer [`Self::admissible`], [`Self::staged`], or [`Self::plural`] for
+/// ordinary construction so ref vectors are sorted canonically and duplicate
+/// provenance refs are rejected before reaching an ABI-visible response. Direct
+/// enum construction remains available for raw-shape tests and defensive
+/// evaluator inputs.
 #[derive(Clone, Debug, PartialEq, Eq)]
 pub enum WitnessedSuffixLocalAdmissionPosture {
     /// Local evidence says the suffix is admissible.
     Admissible {
         /// Target-local provenance coordinates produced or expected by admission.
+        ///
+        /// Use [`WitnessedSuffixLocalAdmissionPosture::admissible`] for normal
+        /// construction.
         admitted_refs: Vec<ProvenanceRef>,
     },
     /// Local evidence says the suffix should be retained for later judgment.
     Staged {
         /// Source or target coordinates retained while staged.
+        ///
+        /// Use [`WitnessedSuffixLocalAdmissionPosture::staged`] for normal
+        /// construction.
         staged_refs: Vec<ProvenanceRef>,
     },
     /// Local evidence preserves lawful plurality.
     Plural {
         /// Candidate coordinates that remain lawful plural outcomes.
+        ///
+        /// Use [`WitnessedSuffixLocalAdmissionPosture::plural`] for normal
+        /// construction.
         candidate_refs: Vec<ProvenanceRef>,
     },
     /// Local evidence reports deterministic adverse admission law.
@@ -170,6 +197,51 @@ pub enum WitnessedSuffixLocalAdmissionPosture {
     },
 }
 
+impl WitnessedSuffixLocalAdmissionPosture {
+    /// Builds an admissible posture with canonical admitted refs.
+    pub fn admissible(
+        admitted_refs: Vec<ProvenanceRef>,
+    ) -> Result<Self, WitnessedSuffixLocalAdmissionPostureError> {
+        Ok(Self::Admissible {
+            admitted_refs: canonical_unique_provenance_refs(admitted_refs)?,
+        })
+    }
+
+    /// Builds a staged posture with canonical staged refs.
+    pub fn staged(
+        staged_refs: Vec<ProvenanceRef>,
+    ) -> Result<Self, WitnessedSuffixLocalAdmissionPostureError> {
+        Ok(Self::Staged {
+            staged_refs: canonical_unique_provenance_refs(staged_refs)?,
+        })
+    }
+
+    /// Builds a plural posture with canonical candidate refs.
+    pub fn plural(
+        candidate_refs: Vec<ProvenanceRef>,
+    ) -> Result<Self, WitnessedSuffixLocalAdmissionPostureError> {
+        Ok(Self::Plural {
+            candidate_refs: canonical_unique_provenance_refs(candidate_refs)?,
+        })
+    }
+
+    /// Builds a conflict posture from named conflict evidence.
+    #[must_use]
+    pub fn conflict(
+        reason: ConflictReason,
+        source_ref: ProvenanceRef,
+        evidence_digest: Hash,
+        overlap_revalidation: Option<StrandOverlapRevalidation>,
+    ) -> Self {
+        Self::Conflict {
+            reason,
+            source_ref,
+            evidence_digest,
+            overlap_revalidation,
+        }
+    }
+}
+
 /// Evaluates one witnessed suffix admission request against local evidence.
 ///
 /// Performs deterministic local validation before returning the classified
@@ -374,6 +446,24 @@ fn canonical_provenance_refs(mut refs: Vec<ProvenanceRef>) -> Vec<ProvenanceRef>
     refs
 }
 
+fn canonical_unique_provenance_refs(
+    mut refs: Vec<ProvenanceRef>,
+) -> Result<Vec<ProvenanceRef>, WitnessedSuffixLocalAdmissionPostureError> {
+    refs.sort_unstable();
+
+    for window in refs.windows(2) {
+        if window[0] == window[1] {
+            return Err(
+                WitnessedSuffixLocalAdmissionPostureError::DuplicateProvenanceRef {
+                    provenance_ref: window[0],
+                },
+            );
+        }
+    }
+
+    Ok(refs)
+}
+
 fn obstructed_response(
     request: &WitnessedSuffixAdmissionRequest,
     source_shell_digest: Hash,