Crate helena 

helena — the core vocabulary

helena is a latent data-to-waveform generation platform (see docs/PRD.adoc); its engine is a trained causal continuous-latent VAE whose latent is a real-time control surface (PRD §9.2, resolved 2026-06-30). This crate holds the vocabulary every other crate speaks: the domain types that flow through the pipeline, the seams the swappable components implement, and the laws their implementations must obey. The design is docs/target_arch/refoundation.adoc; its axioms in one line: types carry axes, values carry numbers.

source data ──▶ SourceEncoder ──▶ Conditioning ──▶ LatentGenerator<K>
                                                         │
                                                    Latent<K>  (on a TimeBase)
                                                         │
                                             AudioDecoder<K> / StreamingDecoder<K>
                                                         ▼
                                                    Pcm / PcmBlock

use helena::{SourceBatch, SourceFingerprint, Tensor};

// The host-side vocabulary is serde-friendly and backend-free: assemble a
// batch of source features and stamp it with a typed provenance
// fingerprint (PRD NFR-010).
let batch = SourceBatch::new(vec![Tensor::vector([0.5, -0.5, 0.25])]);
let stamp = SourceFingerprint::of(&batch)?;
assert!(stamp.to_string().starts_with("sha256:"));

The axes the types carry

• Latent kind (latent): Latent<K> is generic over the sealed LatentKind markers Continuous / Tokens, so kind mismatches don’t type-check; the dynamic AnyLatent exists only at serialization edges with one checked gate back in.
• Time base (time): Pcm carries a nonzero SampleRate; every Latent<K> carries a TimeBase (rate over stride, exact). Frames and Samples are distinct counts.
• Causality (plan, stream): streaming decoders are built from a CausalPlan checked against a LatencyBudget before weights exist, and their sessions obey the bit-exactness law in laws.
• Lifecycle (manifest, config, latent_norm): raw deserialized documents and validated specs are different types.
• Provenance (provenance): fingerprints are typed and composed; sidecars travel in versioned envelopes.

The tensor backend is Burn. The core stays backend-agnostic by speaking Burn’s host-side TensorData at its boundaries: Tensor is the raw serde-friendly carrier, and the domain newtypes (Pcm, FrameSeq, the Conditioning slots) own rank, finiteness, and axis semantics. Models in the outer crates are generic over B: Backend and convert at their edges.

Crate map

• time — clocks (SampleRate, TimeBase) and counts.
• signal — time-domain audio (Pcm, PcmBlock).
• tensor — the raw host-side carrier over TensorData.
• latent — kinds, payloads (FrameSeq, TokenGrid), Latent<K>, AnyLatent, and the Conditioning bundle.
• seams — the component contracts (PRD §13) and generation parameters (SeedPolicy).
• stream — the streaming contract (PRD NFR-004).
• plan — causal topology arithmetic, checked at construction.
• laws — the conformance laws implementations instantiate as tests.
• provenance — typed fingerprints and versioned sidecar envelopes.
• latent_norm — per-dimension standardization (GEN-8), fitted by construction.
• diffusion — the variance-preserving v-prediction kernel and levers (the §16.4 baseline posture’s objective core).
• eval — dependency-free diagnostics and the feature-gated meta-evaluation arm.
• stats — streaming moment accumulation.
• config / manifest / artifact — the raw→validated document boundary and stamped artifact metadata.
• error — the shared Error / Result.

Re-exports

pub use artifact::CodecInfo;

pub use artifact::GeneratedArtifact;

pub use artifact::GenerationRecord;

pub use artifact::Stamp;

pub use config::ConfigFingerprint;

pub use config::ExperimentSpec;

pub use config::RawExperimentConfig;

pub use config::Recipe;

pub use config::RecipeFingerprint;

pub use error::Error;

pub use error::Result;

pub use latent::AnyLatent;

pub use latent::Conditioning;

pub use latent::Continuous;

pub use latent::FrameSeq;

pub use latent::Framed;

pub use latent::GlobalLatent;

pub use latent::KindTag;

pub use latent::Latent;

pub use latent::LatentBlock;

pub use latent::LatentKind;

pub use latent::Mask;

pub use latent::Metadata;

pub use latent::TemporalLatent;

pub use latent::TokenGrid;

pub use latent::Tokens;

pub use latent_norm::LatentNorm;

pub use latent_norm::NormFitter;

pub use manifest::ItemPath;

pub use manifest::Manifest;

pub use manifest::ManifestItem;

pub use manifest::RawDatasetManifest;

pub use manifest::SourceKind;

pub use plan::CausalLayer;

pub use plan::CausalPlan;

pub use plan::CheckedPlan;

pub use plan::LatencyBudget;

pub use plan::MORPH_BAND_MAX_SECONDS;

pub use probe::Formant;

pub use probe::Layer;

pub use probe::Partial;

pub use probe::Probe;

pub use probe::Stratum;

pub use probe::Vibrato;

pub use provenance::Fingerprint;

pub use provenance::SchemaVersion;

pub use provenance::SidecarEnvelope;

pub use provenance::SourceFingerprint;

pub use seams::AudioCodec;

pub use seams::AudioDecoder;

pub use seams::AudioEncoder;

pub use seams::ClipDuration;

pub use seams::Clocked;

pub use seams::GenerationParams;

pub use seams::GuidanceScale;

pub use seams::LatentGenerator;

pub use seams::Seed;

pub use seams::SeedPolicy;

pub use seams::SourceBatch;

pub use seams::SourceEncoder;

pub use seams::Temperature;

pub use signal::ChannelLayout;

pub use signal::Pcm;

pub use signal::PcmBlock;

pub use stream::StreamSession;

pub use stream::StreamSpec;

pub use stream::StreamingDecoder;

pub use tensor::Tensor;

pub use time::Frames;

pub use time::SampleRate;

pub use time::Samples;

pub use time::TimeBase;

Modules

artifact

Stamped generated-artifact metadata (PRD §18.2, NFR-010).

config

Versioned experiment configuration: raw documents to validated specs.

diffusion

Variance-preserving diffusion parameterization for continuous latents.

error

Shared error taxonomy for helena.

eval

Generator-output diagnostics and dependency-free audio-quality metrics.

latent

Latent representations: the audio-side values the pipeline generates and decodes, and the conditioning bundle that drives generation.

latent_norm

Per-dimension standardization for continuous latents (GEN-8).

laws

Conformance laws (A3): the contracts the type system cannot carry, stated once, generically, and instantiated as tests by every implementation.

manifest

Dataset manifests: raw documents to validated, path-confined manifests.

plan

Causality settled at construction (A4).

probe

Analytic acoustic probes: typed, fingerprintable capability targets.

provenance

Provenance as structure (A6, PRD NFR-010).

seams

The swappable component contracts (PRD §13, NFR-020).

signal

Time-domain audio — the final output of the pipeline (PRD §8, space Y).

stats

Streaming summary statistics shared across the boundary.

stream

Streaming synthesis — the hard constraint (PRD NFR-004), as a contract.

tensor

The host-side tensor: a thin wrapper over Burn’s TensorData.

time

Clocks and counts: the time vocabulary every framed value carries.

Structs

TensorData

Data structure for tensors.

Enums

Value

The Metadata value type, re-exported so the whole public API is nameable without a direct serde_json dependency. Represents any valid JSON value.