Architecture

Source layout

src/
  lib.rs          crate root: public re-exports, #![forbid(unsafe_code)]
  error.rs        MattenError + DataFormat (RFC-005)
  shape.rs        validate_shape, strides, coord↔flat helpers (RFC-003)
  tensor.rs       Tensor struct, constructors, accessors, arange
  tensor/
    ops.rs        shape ops, slicing, boundary APIs (split per 300-ELOC rule)
  limits.rs       MattenLimits — single source of truth for allocation budgets
  convert.rs      From/TryFrom trait impls (RFC-004)
  reshape.rs      permute_axes, reshape helpers (RFC-007)
  slice.rs        SliceSpec, SliceBuilder, slice_str parser (RFC-008)
  ops.rs          ops/ module root
  ops/
    broadcast.rs  broadcast_shape, BroadcastCtx, apply_binary (RFC-006)
    broadcast/
      tests.rs    BroadcastCtx unit tests
    tensor_ops.rs Add/Sub/Mul/Div for &Tensor pairs
    scalar_ops.rs &Tensor op f64, f64 op &Tensor
    unary_ops.rs  Neg
  tests.rs        test module root
  tests/
    tensor.rs     construction, shape validation, fill ctors, arange, limits
    convert.rs    From/TryFrom
    error.rs      MattenError / DataFormat model
    shape.rs      row-major index helpers
    ops.rs        broadcasting, scalar ops
    reshape.rs    reshape/flatten/transpose/swap_axes/get
    slice.rs      SliceBuilder, slice_str
    math.rs       reductions, axis reductions, matmul, NaN policy
    dynamic.rs    dynamic test dispatcher
    dynamic/
      element.rs  Element model tests
      tensor.rs   dynamic construction, JSON, CSV
      lifecycle.rs storage, utility, is_none_mask, lifecycle
      guards.rs   accessor guards, diagnostics
      policy.rs   NumericPolicy, inspection helpers

Module style: foo.rs + foo/ coexistence (Rust 2018+). No mod.rs files.

Public re-exports

#![allow(unused)]
fn main() {
// Numeric core — always available:
pub use crate::error::{DataFormat, MattenError};
pub use crate::limits::MattenLimits;
pub use crate::slice::SliceBuilder;
pub use crate::tensor::Tensor;

// Dynamic on-ramp — under #[cfg(feature = "dynamic")]:
pub use crate::dynamic::Element;
pub use crate::dynamic::NumericPolicy;

// Hidden compiler-visibility plumbing (sealed trait chain):
#[doc(hidden)] pub use crate::slice::{IntoSliceRange, SliceConvert, SliceSpecRepr};
}

Cargo feature matrix

[features]
default = ["serde", "json", "csv"]
serde   = ["dep:serde"]
json    = ["serde", "dep:serde_json"]
csv     = ["dep:csv"]
dynamic = []

Lean build: matten = { version = "0.28", default-features = false }. The strict compile-time baseline (< 15 s on a modern laptop) applies to the lean profile. The default profile is the convenient PoC baseline; dynamic is off by default.

Design invariants

1. One primary user type. Every user workflow starts with use matten::Tensor.
2. No public lifetimes. All numeric-core methods that take or return tensors use owned values. Internal helpers may borrow, but lifetimes never appear in the public API signature of a method that returns a Tensor.
3. No public generics on Tensor. The type is Tensor, not Tensor<T> or Tensor<T, D>. Generic dtype and dimension support belongs to the dynamic path (dynamic).
4. #![forbid(unsafe_code)]. Any future exception requires a dedicated RFC.
5. Panic zone / Result zone split. Convenience APIs for trusted local code may panic. Every external boundary returns Result<_, MattenError>.
6. Checked arithmetic everywhere. Shape products and allocation counts use checked_mul; overflow surfaces as MattenError::Allocation, never wraps.
7. Row-major canonical order. All operations that produce a new tensor materialise it in row-major contiguous order.

Milestone sequence