# NraayTensor Hardware Implementation Layer

**Rust hardware layer** for NraayTensor with explicit state transitions, generation-based safety, and fail-closed validation.

## Overview

This crate implements the core hardware tensor primitives for the NraayTensor system:
- **Buffer management** with generation counters and Arc-based ownership
- **Ownership state machine** (B_layout, B_own) with explicit transitions
- **Memory address calculation** with stride handling for multi-dimensional indexing
- **Tensor views and slicing** (zero-copy Arc::clone, never copy data)
- **Materialization barrier** (transactional copy-on-write with source preservation)
- **Hardware-safe C-compatible descriptors** (#[repr(C)] for FFI)
- **Governance state engine** with fail-closed validation gates
- **Sparse work-stealing scheduler** (RAW_ROUTE with memory locality heuristic)

## Core Principles

### 1. Explicit State Transitions
Every operation transitions ownership and governance state through a documented state machine:
- VIEW → (shared, canonical or non-canonical)
- SLICE → (shared, non-canonical)
- MATERIALIZE → (exclusive, canonical) with new buffer
- TRANSPOSE → (non-canonical strides)

### 2. Generation Counter Safety
Each buffer has a generation counter that increments on allocation/materialization:
- Prevents use-after-free via stale descriptor detection
- Every view holds buffer_id + generation
- Operations validate generation match before access

### 3. Fail-Closed Validation
All operations validate preconditions before modifying state:
- Bounds checking on all indices
- Mutability checks (exclusive owner only)
- Stale generation rejection
- No partial state application on error

### 4. No Hidden Ownership Changes
All ownership transitions are explicit:
- VIEW always returns shared (B_own: 1 → 0)
- Arc::clone is transparent (no hidden increments)
- Refcount checked to enforce exclusivity

## Architecture

### Modules

| Module | Purpose | LOC |
|--------|---------|-----|
| **buffer.rs** | Buffer allocation, generation counters, Arc ownership | 180 |
| **ownership.rs** | State machine (B_layout, B_own) with transitions | 240 |
| **memory.rs** | Address calculation, stride handling, MemoryLayout | 310 |
| **view.rs** | Tensor views, slicing, transpose, reshape (zero-copy) | 320 |
| **materialize.rs** | Transactional materialization (read→alloc→copy→install) | 290 |
| **descriptor.rs** | C-compatible #[repr(C)] TensorDescriptor | 280 |
| **governance.rs** | Validation gates for all operations | 310 |
| **routing.rs** | RAW_ROUTE sparse work-stealing scheduler | 380 |
| **error.rs** | Fail-closed error types | 50 |
| **lib.rs** | Core TensorHardware API & integration | 200 |
| **Total** | | **2,560** |

## API Reference

### Tensor Hardware Context

```rust
pub struct TensorHardware {
    validator: GovernanceValidator,
    materializer: MaterializationBarrier,
    router: SparseRouter,
}

impl TensorHardware {
    pub fn allocate(&mut self, shape: Vec<usize>) -> Result<(Buffer, TensorView)>;
    pub fn create_view(&mut self, view: &TensorView, buffer: &Buffer) -> Result<TensorView>;
    pub fn slice(&mut self, view: &TensorView, buffer: &Buffer, 
                 ranges: &[(usize, usize, usize)]) -> Result<TensorView>;
    pub fn transpose(&mut self, view: &TensorView, buffer: &Buffer, 
                     permutation: &[usize]) -> Result<TensorView>;
    pub fn reshape(&mut self, view: &TensorView, buffer: &Buffer, 
                   new_shape: Vec<usize>) -> Result<TensorView>;
    pub fn materialize(&mut self, view: &TensorView, 
                       buffer: &Buffer) -> Result<MaterializationResult>;
    pub fn get(&mut self, view: &TensorView, buffer: &Buffer, 
               indices: &[usize]) -> Result<f32>;
    pub fn set(&mut self, view: &TensorView, buffer: &Buffer, 
               indices: &[usize], value: f32) -> Result<()>;
    pub fn release(&mut self, view: &TensorView, buffer: &Buffer) -> Result<()>;
}
```

### Buffer Management

```rust
pub struct Buffer {
    data: Arc<Vec<f32>>,
    generation: u64,
    id: u64,
    is_owner: bool,
}

impl Buffer {
    pub fn allocate(id: u64, size: usize) -> Result<Self>;
    pub fn strong_count(&self) -> usize;
    pub fn is_exclusive(&self) -> bool;
    pub fn validate_generation(&self, gen: u64) -> Result<()>;
    pub fn check_mutable(&self) -> Result<()>;
}
```

### Ownership State Machine

```rust
pub struct OwnershipToken {
    pub is_owner: bool,      // B_own: 1 = exclusive, 0 = shared
    pub is_canonical: bool,  // B_layout: 1 = canonical, 0 = non-canonical
    pub version: u32,        // State transition counter
}

impl OwnershipToken {
    pub fn new_exclusive() -> Self;
    pub fn transition_to_shared(&self) -> Result<Self>;
    pub fn transition_to_non_canonical(&self) -> Result<Self>;
    pub fn transition_to_materialized(&self) -> Result<Self>;
    pub fn can_mutate_directly(&self) -> bool;
    pub fn needs_materialization(&self) -> bool;
}
```

### Tensor Views

```rust
pub struct TensorView {
    buffer_handle: BufferHandle,
    shape: Vec<usize>,
    strides: Vec<usize>,
    offset: usize,
    ownership: OwnershipToken,
}

impl TensorView {
    pub fn from_buffer(buffer: &Buffer, layout: MemoryLayout) -> Self;
    pub fn share(&self) -> Result<Self>;
    pub fn slice(&self, ranges: &[(usize, usize, usize)]) -> Result<Self>;
    pub fn transpose(&self, permutation: &[usize]) -> Result<Self>;
    pub fn reshape(&self, new_shape: Vec<usize>) -> Result<Self>;
    pub fn address_for(&self, indices: &[usize]) -> Result<usize>;
}
```

### Materialization

```rust
pub struct MaterializationBarrier;

impl MaterializationBarrier {
    pub fn materialize(&mut self, view: &TensorView, 
                       buffer: &Buffer) -> Result<MaterializationResult>;
}

pub struct MaterializationResult {
    pub new_buffer: Buffer,
    pub new_view: TensorView,
    pub source_buffer_id: u64,
}
```

### Hardware Descriptor

```rust
#[repr(C)]
pub struct TensorDescriptor {
    pub buffer_id: u64,
    pub offset: u64,
    pub rank: u32,
    pub element_count: u64,
    pub shape_ptr: u64,
    pub stride_ptr: u64,
    pub ownership: u8,      // OwnershipCode
    pub governance: u8,     // GovernanceCode
    pub materialization: u8, // MaterializationCode
    pub generation: u64,
}
```

### Governance Validation

```rust
pub struct GovernanceValidator;

impl GovernanceValidator {
    pub fn validate_view(&mut self, view: &TensorView, buffer: &Buffer) -> Result<()>;
    pub fn validate_access(&mut self, view: &TensorView, buffer: &Buffer, 
                          indices: &[usize], is_write: bool) -> Result<()>;
    pub fn validate_slice(&mut self, view: &TensorView, 
                         ranges: &[(usize, usize, usize)]) -> Result<()>;
    pub fn validate_materialize(&mut self, view: &TensorView, 
                                buffer: &Buffer) -> Result<()>;
}
```

### Work-Stealing Router

```rust
pub struct SparseRouter;

impl SparseRouter {
    pub fn new() -> Self;
    pub fn register_worker(&mut self, id: WorkerId, locality_distance: f32);
    pub fn route(&mut self, task: &Task) -> WorkerId;
    pub fn region_owner(&self, region: RegionId) -> Option<WorkerId>;
}

pub struct Task {
    pub id: u64,
    pub region: RegionId,
    pub size: usize,
}
```

## Usage Examples

### Allocate and Access Elements

```rust
let mut hw = TensorHardware::new();

// Allocate exclusive, canonical 10x10 tensor
let (buffer, view) = hw.allocate(vec![10, 10])?;

// Set element (requires exclusive ownership)
hw.set(&view, &buffer, &[2, 3], 42.0)?;

// Get element (read-only, allowed on shared too)
let val = hw.get(&view, &buffer, &[2, 3])?;
assert_eq!(val, 42.0);
```

### Create Shared Views (Zero-Copy)

```rust
// Create shared view (Arc::clone, no data copy)
let shared = hw.create_view(&view, &buffer)?;

// Can read from shared
let val = hw.get(&shared, &buffer, &[2, 3])?;

// Cannot write to shared
hw.set(&shared, &buffer, &[2, 3], 50.0)?; // ❌ Err(SharedTensorMutation)
```

### Slicing (Non-Destructive)

```rust
// Slice [2:5, 3:7] (creates shared view with new shape)
let sliced = hw.slice(&view, &buffer, &[(2, 5, 1), (3, 7, 1)])?;

// New shape, same data
assert_eq!(sliced.shape, vec![3, 4]);

// Source tensor unchanged
assert!(view.is_exclusive());
```

### Transpose (Non-Canonical Strides)

```rust
// Transpose swaps dimensions → non-canonical strides
let transposed = hw.transpose(&view, &buffer, &[1, 0])?;

// Cannot directly access (non-canonical)
assert!(!transposed.is_contiguous());

// Needs materialization to make canonical
```

### Materialization (Transactional Copy-On-Write)

```rust
// Materialize non-canonical to contiguous buffer
let result = hw.materialize(&transposed, &buffer)?;

// New buffer is exclusive and canonical
assert!(result.new_view.is_exclusive());
assert!(result.new_view.is_contiguous());

// Original buffer still valid
assert!(buffer.is_exclusive());
```

### Governance Validation

```rust
let mut validator = GovernanceValidator::new();

// Validate view against buffer
validator.validate_view(&view, &buffer)?;

// Validate element access
validator.validate_access(&view, &buffer, &[0, 0], true)?;

// Get operation sequence
let ops = validator.sequence();
```

### Work-Stealing Scheduling

```rust
let mut router = SparseRouter::new();

// Register workers
router.register_worker(WorkerId(0), 0.5);  // close
router.register_worker(WorkerId(1), 1.5);  // far

// Route task to best worker
let task = Task {
    id: 1,
    region: RegionId(100),
    size: 1024,
};

let worker = router.route(&task);

// Same region tasks go to same worker (locality)
let task2 = Task { id: 2, region: RegionId(100), size: 512 };
assert_eq!(router.route(&task2), worker);
```

## Testing

All 49 unit tests pass:

```bash
cargo test --lib
```

**Test coverage:**
- Buffer allocation and generation
- Ownership state transitions
- Memory address calculation
- View creation and slicing
- Materialization workflow
- Governance validation
- Error handling (fail-closed)
- Routing and scheduling

## Performance Characteristics

- **Allocation**: O(n) where n = element count
- **View/Slice**: O(rank) - no data copy
- **Address calculation**: O(rank)
- **Materialize**: O(n) - single sequential pass
- **Element access**: O(1) after bounds validation

## Safety Model

1. **Generation Counter**: Stale descriptor detection
2. **Arc Reference Counting**: Exclusive ownership enforcement
3. **Bounds Checking**: All indices validated before access
4. **Fail-Closed Validation**: No partial state on error
5. **Type Safety**: Rust's type system + explicit ownership tokens

## FFI Compatibility

The descriptor (#[repr(C)]) is compatible with:
- Pascal (Free Pascal FFI)
- C/C++ bindings
- Hardware interfaces (DMA, registers)

Size: 72 bytes (64-bit aligned)

## Dependencies

- `thiserror` — Error type derivation
- `parking_lot` — Parking lot mutex (optional)
- `atomic` — Atomic types

## License

Sovereign Leviathan covenant (`LicenseRef-Sovereign-Leviathan-SL-AGPL3-001`), AGPL-3.0 based

## References

- **Architecture**: Design Phase NraayTensor specification
- **Formal Verification**: Kani proofs in `ffi/sparse_router_kani.rs`
- **FFI Contract**: `FFI_CONTRACT.md`
- **Example Usage**: `examples/core_operations.rs`