Trait OmsSubstrate 

pub trait OmsSubstrate: SubstrateRead {
    // Required methods
    fn put_grain(&mut self, spec: &GrainSpec) -> Result<String>;
    fn supersede(
        &mut self,
        target_hash: &str,
        spec: &GrainSpec,
        justification: &str,
    ) -> Result<String>;
    fn execute_cal(&mut self, cal: &str) -> Result<Vec<Value>>;
    fn validate_cal(&self, cal: &str) -> Result<()>;
    fn load_state(&self) -> Result<Value>;
    fn store_state(&mut self, state: &Value) -> Result<()>;

    // Provided methods
    fn retract(&mut self, hash: &str, reason: &str) -> Result<()> { ... }
    fn put_blob(&mut self, bytes: &[u8]) -> Result<String> { ... }
    fn get_blob(&mut self, address: &str) -> Result<Vec<u8>> { ... }
    fn definition_inverse(&self, _statement: &str) -> Result<Option<String>> { ... }
}

The full store protocol the engine binds to: reads (via the supertrait) plus governed writes, CAL, and state persistence. All methods are fallible; a substrate fault surfaces as crate::error::Error::Substrate.

Required Methods

fn put_grain(&mut self, spec: &GrainSpec) -> Result<String>

Append a new grain; returns its content address.

fn supersede( &mut self, target_hash: &str, spec: &GrainSpec, justification: &str, ) -> Result<String>

Supersede target_hash with a new grain carrying justification; returns the new grain’s address. Atomic and distinct from put (OMS §28.4).

fn execute_cal(&mut self, cal: &str) -> Result<Vec<Value>>

Execute CAL text, returning result rows as JSON. Used to regenerate evidence sets (evidence_query) and to apply proposal_cal. A substrate MAY reject CAL it cannot run with Error::CalUnsupported.

fn validate_cal(&self, cal: &str) -> Result<()>

Validate a CAL batch without executing it (statement classification, destructive-op detection). Delegated to the substrate — the engine contains a CAL writer, never a parser.

fn load_state(&self) -> Result<Value>

Load the persisted loop state blob (config + watermarks/cooldowns). Returns Value::Null when nothing has been stored yet.

fn store_state(&mut self, state: &Value) -> Result<()>

Persist the loop state blob (a file-truth, so it travels with the file on sync).

Provided Methods

fn retract(&mut self, hash: &str, reason: &str) -> Result<()>

Index-layer retraction (verification_status = retracted) — the inverse of an applied ADD, used by rollback. Not destructive (the grain stays content-addressed; only the index marks it retracted). The default reports it unsupported so substrates opt in.

fn put_blob(&mut self, bytes: &[u8]) -> Result<String>

Store an opaque blob (candidate tool CODE, evalset payloads) in the substrate’s CAS, returning its address. §7.4’s blob seam — CAPABILITY-GATED: the default refuses, so a loop can only carry code on substrates that explicitly opt in. Code enters the substrate only through this seam or an authored add — never from a git mirror.

fn get_blob(&mut self, address: &str) -> Result<Vec<u8>>

Fetch a blob by the address put_blob returned. Same capability gate.

fn definition_inverse(&self, _statement: &str) -> Result<Option<String>>

The CAL that would restore the CURRENT definition named by a DEFINE QUERY / DEFINE TEMPLATE statement — the rollback inverse, captured before the definition is replaced.

Returns Ok(None) when the substrate cannot produce one, which the engine treats as “this definition rewrite is not applicable”: a definition change with no recorded inverse is one that ROLLBACK would silently fail to undo, and a rollback that reports success without restoring anything is worse than a refusal.

The default implementation returns None, so a substrate that does not model saved definitions simply cannot execute definition rewrites — fail closed, no opt-out needed.

Dyn Compatibility

This trait is dyn compatible.

In older versions of Rust, dyn compatibility was called "object safety".

Implementors

impl OmsSubstrate for ReferenceSubstrate