axiom_engine 0.5.0

Axiom-TTT Inference Engine – Rust implementation using candle
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97

//! CP/1 — the Cognitive Protocol, version 1.
//!
//! AXIOM is the normative owner of CP/1: the specification, JSON Schema, golden
//! fixtures and vendoring manifest live in `protocol/cp1/` at the repository
//! root, and this module is the reference Rust binding for them.
//!
//! # What lives here, and what deliberately does not
//!
//! AXIOM authors exactly one canonical type, [`types::Context`], and emits two
//! events, `ContextCompressed` and `GroundingFailed`. This module therefore
//! ships:
//!
//! - [`canonical`] — the byte-exact encoding every document hashes over. Shared
//!   by all three components and the reason they can agree on a hash at all.
//! - [`types`] — `Context` plus the primitives every document needs.
//! - [`event`] — the closed event set and the sink trait subsystems emit through.
//! - [`envelope`] — signed transport, reusing [`crate::provenance`]'s crypto.
//! - [`conformance`] — the shared suite each binding runs against the corpus.
//!
//! It does **not** ship structs for `Genome`, `Skill`, `Belief` and the rest.
//! Authorship of each canonical type is exclusive (see `protocol/cp1/SPEC.md`
//! section 3), so those are types AXIOM may never mint or model as owned
//! bindings. AXIOM does still *read* several of them at the boundary — it draws
//! on ADAM's memories and beliefs to assemble a `Context` — but a struct for
//! each would be a dead abstraction requiring perpetual maintenance against a
//! schema it never exercises. Cross-binding agreement on those types
//! is established structurally, over the fixture corpus, by [`conformance`] —
//! which tests the encoding, the thing that actually has to match.
//!
//! # Example
//!
//! ```
//! use axiom_engine::cp1::{canonical, envelope::SignedEnvelope, types::*};
//!
//! let context = Context::assemble(
//!     "dddddddd-dddd-4ddd-8ddd-dddddddddddd",
//!     "answer a question about the organism's goals",
//!     4096,
//!     31_500,
//!     3_780,
//!     vec![ContextSegment {
//!         role: SegmentRole::Memory,
//!         content: "Amendments to goals require an approving fitness result.".into(),
//!         source_id: Some("66666666-6666-4666-8666-666666666666".into()),
//!     }],
//!     Provenance::now(Component::Axiom, "axiom:context/compress"),
//! );
//!
//! assert!(context.grounded);
//! assert_eq!(context.compression_ratio_bp.raw(), 1_200);
//!
//! let wire = SignedEnvelope::seal(&context.seal().unwrap(), None).unwrap();
//! let received = wire.open(None).unwrap();
//! assert!(canonical::verify_seal(&received).unwrap());
//! ```

pub mod canonical;
pub mod conformance;
pub mod envelope;
pub mod event;
pub mod types;

/// The protocol identifier carried by every CP/1 document.
pub const CP: &str = "cp1";

/// The revision of the normative source this binding implements.
///
/// Kept in step with `protocol/cp1/VERSION` by
/// [`tests::version_matches_the_normative_source`].
pub const VERSION: &str = "1.0.0";

pub use canonical::{content_hash, seal, to_canonical, verify_seal, CanonicalError};
pub use envelope::{EnvelopeError, SignedEnvelope};
pub use event::{
    Event, EventError, EventKind, EventSink, PayloadValue, RecordingSink, SubjectType,
};
pub use types::{
    BasisPoints, Component, Context, ContextSegment, Provenance, SegmentRole, Timestamp,
};

#[cfg(test)]
mod tests {
    use super::*;

    #[test]
    fn version_matches_the_normative_source() {
        let path = concat!(env!("CARGO_MANIFEST_DIR"), "/../protocol/cp1/VERSION");
        let declared = std::fs::read_to_string(path)
            .unwrap_or_else(|err| panic!("cannot read {path}: {err}"));
        assert_eq!(
            declared.trim(),
            VERSION,
            "this binding claims CP/1 {VERSION} but the normative source is at {}",
            declared.trim()
        );
    }
}