Crate active_infinity

Expand description

Active Infinity (Active ∞) — the canonical binary form of Active modules.

Active Infinity is a graph-native, unit-aware, secret-safe, canonical, content-addressed binary data language for the Active ecosystem. It is the runtime, storage, network and agent-to-agent exchange format for Active modules: safer and faster than JSON for configuration and data, deterministic by construction, and designed so that an untrusted buffer can be validated in one bounded pass before any of it is trusted.

§Quick start

use active_infinity::{Inode, InfinityModule, encode, decode, content_hash};

let mut module = InfinityModule::new();
let hello = module.push(Inode::Str("hello".into()));
let number = module.push(Inode::Int(42));
let table = module.push(Inode::Table {
    fields: vec![("greeting".into(), hello), ("answer".into(), number)],
});
module.set_root(Some(table));

let bytes = encode(&module).unwrap();
let decoded = decode(&bytes).unwrap();
assert_eq!(decoded, module);
assert_eq!(encode(&decoded).unwrap(), bytes);
assert_eq!(content_hash(&bytes).unwrap(), content_hash(&encode(&decoded).unwrap()).unwrap());

§The four guarantees

Canonical identity. Logically equal modules encode to identical bytes, and the Blake3 content hash covers the whole canonical payload, so content addressing is a real identity (canonical, encode).
Fail-closed validation. Wrong magic/version, truncation, out-of-range offsets and counts, invalid UTF-8, unknown unit discriminants, cycles, unreachable nodes, non-canonical slack and size bombs are rejected with stable machine-readable codes before allocation (validate, error).
Secrets stay secrets. Secret material is a structural kind, never equals anything (no oracle), carries no Debug/Display/Serialize path, and is absent from every export path (ir::SecretBytes).
Zero-copy and streaming. A validated buffer can be read through view::InfinityView without copying strings or blobs, and a module can be shipped as ordered frames that reassemble to the identical canonical bytes and hash, including incremental deltas (stream).

§Feature flags

active-core (default): interop with the Active text language IR (interop::from_active_core, to_active_core).
json (default): the redacted JSON projection (interop::to_redacted_json).

Both can be disabled for a dependency-free wire codec.

Re-exports§

pub use decode::decode;
pub use decode::decode_with;
pub use encode::encode;
pub use encode::encode_with;
pub use encode::hash_image;
pub use error::Error;
pub use error::Result;
pub use ir::Annotation;
pub use ir::AnnotationKind;
pub use ir::BinOp;
pub use ir::Constraint;
pub use ir::InfinityModule;
pub use ir::Inode;
pub use ir::InterpPart;
pub use ir::ModuleBuilder;
pub use ir::NodeId;
pub use ir::PatchOp;
pub use ir::ProvEntry;
pub use ir::ProvKind;
pub use ir::ProvValue;
pub use ir::Provenance;
pub use ir::SchemaFieldSpec;
pub use ir::SecretBytes;
pub use ir::SemanticTag;
pub use ir::SerializedKind;
pub use ir::TypeSpec;
pub use ir::UnOp;
pub use layout::dialect_hash;
pub use layout::DecodeOpts;
pub use layout::EncodeOpts;
pub use layout::Limits;
pub use layout::Meta;
pub use layout::Section;
pub use layout::FLAG_CANONICAL;
pub use layout::FORMAT_MAJOR;
pub use layout::FORMAT_MINOR;
pub use layout::HEADER_SIZE;
pub use stream::Frame;
pub use stream::FrameKind;
pub use stream::StreamDecoder;
pub use stream::StreamEncoder;
pub use unit::UnitTag;
pub use validate::validate;
pub use validate::validate_canonical;
pub use validate::validate_with;
pub use validate::Validated;
pub use view::InfinityView;
pub use view::NodeView;

Modules§

canonical: Canonicalization: the deterministic normal form of a module.
decode: Decoder: AINF bytes → canonical InfinityModule.
encode: Encoder: canonical module → AINF bytes.
error: Stable, machine-readable error surface.
interop: Interoperability with the Active text language and with legacy consumers.
ir: Active Infinity’s in-memory module model.
layout: Wire layout primitives: the fixed header, node records, section table and the limits that bound untrusted input.
stream: Streaming / Infinity mode: ordered frames that reassemble into exactly the canonical image.
unit: Unit discriminants for Quantity values.
validate: Structural validation of untrusted images.
view: Zero-copy views over a validated image.

Constants§

MAGIC: Magic bytes at the start of every Active Infinity module.
VERSION: Crate version.

Functions§

content_hash: Compute the Blake3-256 content hash of a validated image.
content_hash_hex: Hex form of content_hash.
encode_hashed: Encode a module and return (bytes, hash).