# Algebra Ecosystem Integration

The `algebra` package is for mathematical capabilities of whole vector and
matrix objects. External libraries should implement only the traits whose
operation meaning, closure, and ownership behavior match their types.

## Choose an Algebra Level

Vector and matrix traits form separate capability paths:

| Path | Trait | Prerequisites | Mathematical commitment |
|---|---|---|---|
| Shape | `VectorShape` | None | Reports a vector length |
| Vector 1 | `AdditiveVector` | `VectorShape + Add + Neg + Sub` | Closed vector addition, negation, and subtraction |
| Vector 2 | `VecMulVector` | `AdditiveVector + Mul` | `Mul` means element-wise/Hadamard multiplication |
| Shape | `MatrixShape` | None | Reports matrix dimensions |
| Matrix 1 | `TransposeMatrix` | `MatrixShape` | Transpose returns the same matrix type |
| Matrix 2 | `AdditiveMatrix` | `TransposeMatrix + Add + Neg + Sub` | Closed matrix addition, negation, and subtraction |
| Matrix 3 | `MatMulMatrix` | `AdditiveMatrix + Mul` | `Mul` means matrix multiplication |

Stop at the smallest level required by downstream algorithms. Shape traits do
not imply element access. `TransposeMatrix` does not imply matrix
multiplication. `AdditiveVector` does not imply dot product, norm, scalar
action, or element-wise multiplication.

## Important Operator Boundary

The stronger traits reuse MoonBit operators and return `Self`, not `Result`.
Before implementing one, confirm all of the following:

- The operator already has the documented meaning for the type. In particular,
  `Mul` must not mean Hadamard multiplication on a `MatMulMatrix`.
- Results remain in the same concrete type.
- Runtime shape preconditions and failure behavior are clearly documented.
- The operation does not silently switch storage backends or ownership models.

Dynamic rectangular matrix multiplication may be invalid for some shape pairs.
`MatMulMatrix` does not standardize a checked error channel for that case. A
backend that needs a checked public operation should retain its checked method
and implement `MatMulMatrix` only when its operator contract is acceptable.

## Algebra and Container Are Independent

| Need | Use |
|---|---|
| Observe elements or convert storage | `container` read/build dictionaries |
| Express closed whole-object mathematics | `algebra` traits |
| Do both | Implement the relevant algebra traits and publish container dictionaries |

`MatrixShape` is a semantic shape capability; it is not checked element access.
`MatrixReadOps` includes shape plus checked indexed reads. Algebra transpose is
same-type and closed; container transpose may build a different target type.

Do not implement broad scalar traits merely to make a container type appear
more algebraic. Import `Luna-Flow/luna-generic` and `Luna-Flow/arithmetic`
directly only for scalar laws and operations the backend genuinely supports.

## Where Implementations Belong

Public operator and algebra implementations should normally live in the package
that owns the concrete type. This keeps method/trait resolution predictable and
lets the type owner define the operation semantics.

If a separate interoperability package is necessary, prefer an owned wrapper
type in that package and implement the algebra traits for the wrapper. Do not
assume a bridge package can safely redefine the meaning of operators on an
unowned external type.

## Complete Same-Type Example

This is deliberately a `1x1` matrix type, not a scalar pretending to be an
arbitrary dynamic matrix. For `1x1` matrices, transpose is the identity,
entry-wise addition is matrix addition, and multiplying the single entries is
exactly standard matrix multiplication. The fixed shape makes every operation
closed and removes runtime shape failure from the example.

```moonbit check
///|
struct EcosystemScalarMatrix {
  value : Int
}

///|
impl @algebra.MatrixShape for EcosystemScalarMatrix with fn shape(_) {
  (1, 1)
}

///|
impl @algebra.TransposeMatrix for EcosystemScalarMatrix with fn transpose(self) {
  self
}

///|
impl Add for EcosystemScalarMatrix with fn add(left, right) {
  { value: left.value + right.value }
}

///|
impl Neg for EcosystemScalarMatrix with fn neg(value) {
  { value: -value.value }
}

///|
impl Sub for EcosystemScalarMatrix with fn sub(left, right) {
  left + -right
}

///|
impl Mul for EcosystemScalarMatrix with fn mul(left, right) {
  { value: left.value * right.value }
}

///|
impl @algebra.AdditiveMatrix for EcosystemScalarMatrix

///|
impl @algebra.MatMulMatrix for EcosystemScalarMatrix

///|
fn[M : @algebra.MatMulMatrix] ecosystem_gram(matrix : M) -> M {
  matrix.transpose() * matrix
}

///|
test "external algebra type participates by capability" {
  let matrix : EcosystemScalarMatrix = { value: 3 }
  let other : EcosystemScalarMatrix = { value: 4 }
  inspect((matrix + other).value, content="7")
  inspect(matrix.transpose().value, content="3")
  inspect(ecosystem_gram(matrix).value, content="9")
}
```

An external library may stop after `MatrixShape`, `TransposeMatrix`, or
`AdditiveMatrix`; the final two implementations are not mandatory. A dynamic
matrix backend must additionally define what its operators do for incompatible
shapes rather than copying the fixed-shape assumptions from this example.

## Integration Checklist

- Select the smallest trait that matches the algorithm and the type.
- Confirm the existing `Add`, `Neg`, `Sub`, or `Mul` meaning matches the algebra
  trait before declaring conformance.
- Test closure, shape behavior, transpose shape reversal, and representative
  algebraic laws supported by the type.
- Test invalid dynamic shape behavior wherever an operator has runtime
  preconditions.
- Document whether operations allocate, share storage, or mutate hidden state.
- Keep dot product, norm, scalar action, decomposition, and solvers outside
  these traits unless a future dedicated capability defines them.
- Add container dictionaries separately when element-level interoperability is
  also required.