spacecore 0.3.1__tar.gz → 0.3.2__tar.gz

{spacecore-0.3.1 → spacecore-0.3.2}/CHANGELOG.md

@@ -5,7 +5,15 @@ All notable changes to SpaceCore are documented in this file.
 The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and the project adheres to [Semantic Versioning](https://semver.org/).
 
-## [0.3.1]
+## [Unreleased]
+
+### Fixed
+
+- Corrected the matrix-free adjoint contract so `MatrixFreeLinOp` and its
+  adjoint view use user-supplied forward and reverse callables directly, without
+  applying matrix-backed Riesz-map adjoint corrections.
+
+## [0.3.1] — 2026-06-10
 
 SpaceCore 0.3.1 is a release-candidate stabilization release for the `0.3.x`
 API. It focuses on documentation consistency, tutorial execution, release
@@ -302,5 +310,6 @@ iterative solvers and structured result types.
 - The CuPy backend is provided as a preview. Coverage of non-standard
   operations and sparse handling may evolve in a subsequent release.
 
+[0.3.1]: https://github.com/Pavlo3P/SpaceCore/releases/tag/v0.3.1
 [0.3.0]: https://github.com/Pavlo3P/SpaceCore/releases/tag/v0.3.0
 [0.2.0]: https://github.com/Pavlo3P/SpaceCore/releases/tag/v0.2.0

spacecore-0.3.2/CONTRIBUTING.md

@@ -0,0 +1,55 @@
+# Contributing
+
+SpaceCore is a mathematical software library for typed vector spaces, operators,
+functionals, backend-independent array code, and geometry-aware algorithms. It
+gives mathematical structure to objects; it does not hide problem-specific
+mathematics from contributors.
+
+## Setup
+
+Use [docs/dev/contributing/setup.md](docs/dev/contributing/setup.md) for the
+full environment setup. The minimal contributor workflow is:
+
+```bash
+pip install -e ".[dev]"
+pytest --co -q
+pytest tests/ -x -q
+ruff check .
+```
+
+Optional JAX, Torch, and CuPy backend instructions live in the detailed setup
+guide.
+
+## Architecture
+
+Read [docs/dev/contributing/architecture.md](docs/dev/contributing/architecture.md)
+before changing core behavior. It explains the backend, context, space, LinOp,
+functional, linalg, batching, and cross-cutting infrastructure layers.
+
+## Prerequisites
+
+Read [docs/dev/contributing/prerequisites.md](docs/dev/contributing/prerequisites.md)
+to judge the mathematical background needed for a change. Docstring and test
+fixes may need little background; geometry, adjoint, spectral-method, and linalg
+changes require mathematical review. Mathematical correctness is part of
+contribution review even when tests pass.
+
+## Process
+
+Follow [docs/dev/contributing/process.md](docs/dev/contributing/process.md) for
+branch, PR, and review expectations. PRs should include tests, updated docs or
+docstrings when relevant, a changelog entry under `[Unreleased]`, and a
+mathematical invariant statement for changes touching geometry, adjoints,
+spectral methods, fields, or batching.
+
+## Beginner-Safe Issues
+
+Start with
+[good-first-issue](https://github.com/Pavlo3P/SpaceCore/labels/good-first-issue).
+That label is reserved for issues with a specific file to change, an example to
+follow, and a concrete done condition.
+
+## Current Project State
+
+Check [docs/dev/current.md](docs/dev/current.md) before opening design-heavy
+PRs. Unsettled questions should not be implemented without maintainer agreement.

{spacecore-0.3.1 → spacecore-0.3.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: spacecore
-Version: 0.3.1
+Version: 0.3.2
 Summary: Backend-agnostic vector spaces and linear operators.
 Author: Pavlo Pelikh
 License-Expression: Apache-2.0

spacecore-0.3.2/docs/dev/adr/001_backend_layer.md

@@ -0,0 +1,38 @@
+# ADR-001: Backend layer
+
+## Status
+
+Accepted
+
+## Context
+
+SpaceCore supports multiple array ecosystems while exposing one contributor-facing numerical contract. The backend layer must hide routine namespace differences without pretending all libraries have identical sparse, dtype, device, mutation, or control-flow semantics.
+
+## Current design
+
+`BackendOps` is the public backend contract. Concrete implementations currently cover NumPy/SciPy by default and optionally JAX, Torch, and CuPy when their packages are importable. A backend has a family name, dense and optional sparse array type predicates, dtype normalization, dense Array API style operations through `xp`, sparse conversion, control-flow primitives, vectorization, indexing mutation, and linear algebra helpers.
+
+Backend detection is conservative. Context inference first uses `.ctx` on SpaceCore objects and then tests registered backend array predicates. Optional backend classes are registered only if import succeeds, and unknown names raise a typed backend error.
+
+## Decision
+
+SpaceCore code should call `BackendOps` methods for portable behavior. Direct `ops.xp` or backend-specific handles are escape hatches, not the stable SpaceCore API. Behavior that depends on mathematical spaces, validation, conversion, batching, adjoints, or geometry belongs in SpaceCore. Backend libraries own raw array semantics such as broadcasting, device placement, autograd, memory layout, and low-level dtype promotion.
+
+## Rationale
+
+One explicit contract keeps spaces, LinOps, functionals, and solvers backend-agnostic while still allowing each backend to implement sparse formats, tracing, and mutation idioms correctly.
+
+## Alternatives considered
+
+Using array libraries directly throughout the code was rejected because it spreads backend conditionals across mathematical code. Requiring all optional backends at install time was rejected because NumPy/SciPy should remain the baseline dependency set. Treating `xp` as the public contract was rejected because sparse, loops, dtype sanitization, and indexing semantics are not fully covered by the Array API.
+
+## Consequences
+
+New backend behavior must be added through `BackendOps` or an explicit backend-specific escape hatch. Tests for new backend methods must cover unavailable optional dependencies and avoid silently importing packages that are not installed. See [ADR-002](002_context_and_conversion.md) for context ownership and [ADR-011](011_linalg_contract.md) for solver delegation.
+
+## Contributor invariants
+
+- `BackendOps` methods expose stable SpaceCore behavior without silently depending on unavailable optional packages.
+- Optional backend imports must fail closed: unavailable packages should omit that backend, not break NumPy usage.
+- Portable core code should prefer `ops.method(...)` over `ops.xp.method(...)`.
+- Backend detection must remain conservative and reject ambiguous array ownership.

spacecore-0.3.2/docs/dev/adr/002_context_and_conversion.md

@@ -0,0 +1,40 @@
+# ADR-002: Context and conversion
+
+## Status
+
+Accepted
+
+## Context
+
+Spaces, operators, and functionals need a common execution context for backend operations, default dtype, and validation behavior. Conversion must be predictable because hidden array movement or casting can change performance, autograd behavior, and numerical results.
+
+## Current design
+
+`Context` stores `ops`, `dtype`, and `enable_checks`. It does not own arrays, devices, sparse storage, or gradient state. Context normalization accepts a concrete `Context`, backend family/name, or `None`. Concrete contexts are copied with sanitized dtype. Backend names create a new context through the registered backend. `None` resolves to the process default.
+
+`Context.asarray` and `Context.assparse` convert explicit values into the context. `Context.convert` dispatches dense and sparse inputs through those constructors. `ContextBound.convert(new_ctx)` rebuilds a context-bound object in a target context through `_convert`; it returns `self` when the normalized context is equal. Constructors resolve explicit context first, then compatible inferred contexts from operands, then the default context.
+
+The current design has no separate conversion policy object. Conversion policy lives in explicit `convert(...)`, `Context.asarray(...)`, `Context.assparse(...)`, and constructor resolution.
+
+## Decision
+
+Conversion is explicit and target-context driven. User values passed to operations such as `apply`, `add`, or `inner` are validated when checks are enabled but are not silently converted. Object conversion rebuilds spaces, geometries, stored matrices, and algebraic operands in the requested context; matrix-free callables are preserved and must already be valid for the target backend.
+
+## Rationale
+
+Explicit conversion avoids hidden device transfers, sparse format changes, dtype casts, and backend-specific callable failures. Keeping context small also makes equality and algebra compatibility checks straightforward.
+
+## Alternatives considered
+
+Implicitly converting every operation input was rejected because it hides expensive transfers and can mask caller bugs. A separate conversion policy hierarchy was rejected for now because current behavior is simpler and has only one public mode: explicit target conversion.
+
+## Consequences
+
+New context-bound classes must implement `_convert` when they store context-owned data. Conversions may fail when the target backend lacks sparse support, dtype support, or callable compatibility. Dtype defaults are representation defaults, not mathematical fields; see [ADR-015](015_dtype_default_vs_scalar_field.md).
+
+## Contributor invariants
+
+- Context conversion must be explicit and predictable.
+- `Context` owns backend, dtype default, and validation flag only.
+- Constructors may convert their owned storage, but runtime operation arguments must not be silently converted.
+- Conversion must preserve mathematical structure while rebuilding backend-owned representation.

spacecore-0.3.2/docs/dev/adr/003_space_hierarchy.md

@@ -0,0 +1,38 @@
+# ADR-003: Space hierarchy
+
+## Status
+
+Accepted
+
+## Context
+
+SpaceCore represents mathematical spaces separately from raw array containers. Contributors need to know which layer owns linear operations, coordinates, membership, and element construction.
+
+## Current design
+
+`Space` owns context and membership checks. `VectorSpace` adds abstract `zeros`, `add`, `scale`, and `axpy`. `CoordinateSpace` adds finite coordinate `shape`, `size`, `flatten`, `unflatten`, batch flattening, and `stacked`. `InnerProductSpace`, `StarSpace`, `JordanAlgebraSpace`, and `EuclideanJordanAlgebraSpace` add optional mathematical capabilities.
+
+Concrete dense coordinate spaces construct zeros through their context, validate backend/shape/dtype, and flatten to a dense coordinate vector. `DenseVectorSpace` specializes one-dimensional dense coordinates. `ProductSpace` is a coordinate space whose elements are structured component containers, tuple by default or a registered pytree structure. `StackedSpace` represents a fixed leading-axis stack as one mathematical element.
+
+## Decision
+
+A space defines valid elements and operations on those elements; it is not just an array shape. Coordinate representation is exposed through `flatten`/`unflatten` for operators and linalg, while mathematical operations use `zeros`, `add`, `scale`, and capability methods.
+
+## Rationale
+
+Separating mathematical spaces from coordinate arrays lets product and pytree-structured elements participate in the same operator and solver contracts as dense vectors.
+
+## Alternatives considered
+
+Using only array shapes was rejected because it cannot represent product structure, custom geometry, Hermitian membership, or future tree spaces. Making all spaces dense arrays was rejected because product and structured elements need non-array containers.
+
+## Consequences
+
+New spaces must decide which capabilities they implement and must provide coordinate flattening if they are `CoordinateSpace`s. LinOps and solvers should depend on space methods, not on raw container assumptions. See [ADR-005](005_space_subclasses_and_capabilities.md) and [ADR-006](006_current_batching_model.md).
+
+## Contributor invariants
+
+- `Space` membership is the source of truth for valid elements.
+- `VectorSpace` linear operations must preserve membership.
+- `CoordinateSpace.flatten` and `unflatten` must be inverse coordinate representations for one element.
+- Product element structure must be handled through its `ProductStructure`, not by assuming tuples everywhere.

spacecore-0.3.2/docs/dev/adr/004_inner_product_and_geometry.md

@@ -0,0 +1,38 @@
+# ADR-004: Inner product and geometry
+
+## Status
+
+Accepted
+
+## Context
+
+Adjoints, gradients, norms, and solver correctness depend on the chosen inner product. Treating geometry as a hidden implementation detail would make non-Euclidean spaces incorrect.
+
+## Current design
+
+`InnerProduct` is a separate geometry object with `inner`, `riesz`, `riesz_inverse`, `convert`, `validate_for`, and `is_euclidean`. `InnerProductSpace` delegates `inner`, `norm`, and Riesz maps to this geometry. Built-in geometries include Euclidean coordinate geometry and weighted diagonal geometry.
+
+Spaces own a geometry instance. The same geometry type can be reused by different coordinate spaces and converted with the space context. Metric adjoints use Riesz maps, and linalg uses space inner products and norms. Euclidean spaces use identity Riesz maps; weighted spaces use multiplication/division by validated positive finite weights.
+
+## Decision
+
+Geometry remains a separate object instead of only methods on `Space`. It is part of the mathematical contract of a space and must be validated, converted, and preserved by spaces and operators.
+
+## Rationale
+
+A separate geometry object avoids duplicating inner-product implementations across space subclasses and makes metric changes explicit. It also lets matrix-backed operators implement the correct adjoint formula without guessing from concrete space types.
+
+## Alternatives considered
+
+Putting all inner-product code directly on each space was rejected because it couples geometry to storage classes and makes reuse harder. Treating non-Euclidean geometry as a solver option was rejected because adjoints and gradients would already be wrong before the solver sees them.
+
+## Consequences
+
+New geometries must provide Riesz maps if they are used with matrix-backed operators. Riesz maps should broadcast over leading batch axes for efficient batched adjoints. See [ADR-009](009_metric_adjoint.md) for adjoint details and [ADR-011](011_linalg_contract.md) for solver assumptions.
+
+## Contributor invariants
+
+- Geometry is part of mathematical correctness, not just implementation detail.
+- `InnerProduct.validate_for(space)` must reject incompatible geometry/storage pairs.
+- Non-Euclidean geometry used by coordinate-backed LinOps must provide usable Riesz maps.
+- `norm(x)` must be induced by `inner(x, x)` and return a real magnitude.

spacecore-0.3.2/docs/dev/adr/005_space_subclasses_and_capabilities.md

@@ -0,0 +1,38 @@
+# ADR-005: Space subclasses and capabilities
+
+## Status
+
+Accepted
+
+## Context
+
+Concrete spaces expose different mathematical operations. Contributors need a stable way to reason about which operations are present and how conversion affects them.
+
+## Current design
+
+Public concrete spaces include `DenseCoordinateSpace`, `DenseVectorSpace`, `ElementwiseJordanSpace`, `EuclideanElementwiseJordanSpace`, `HermitianSpace`, `ProductSpace`, and `StackedSpace`. Capability classes include `InnerProductSpace`, `StarSpace`, `JordanAlgebraSpace`, and `EuclideanJordanAlgebraSpace`.
+
+`DenseCoordinateSpace` has inner-product geometry but no star operation. `DenseVectorSpace` adds elementwise conjugation. `ElementwiseJordanSpace` adds elementwise Jordan and spectral operations; when context and geometry are real Euclidean, construction dispatches to `EuclideanElementwiseJordanSpace`. `HermitianSpace` represents dense Hermitian matrices with Frobenius geometry and spectral calculus. `ProductSpace` and `StackedSpace` dynamically choose internal subclasses that preserve only capabilities shared by their components or base.
+
+## Decision
+
+Capabilities are represented by Python class membership, not by flags. Geometry belongs to inner-product-capable spaces. Product and stacked conversion rebuilds converted components and then recomputes the capability-specific class.
+
+## Rationale
+
+Class-based capabilities make missing operations fail naturally and keep capability composition explicit. Recomputing on conversion prevents stale capability promises after dtype or geometry changes.
+
+## Alternatives considered
+
+Single concrete classes with runtime feature flags were rejected because they make unsupported operations harder to detect. Forcing every dense space to expose star or Jordan operations was rejected because those operations are not always mathematically valid.
+
+## Consequences
+
+Code should test capabilities with `isinstance`, not with name checks or ad hoc attributes. New concrete spaces must be explicit about which capabilities they provide. Spectral operations belong only to Jordan-capable spaces; see [ADR-012](012_jordan_spectrum.md).
+
+## Contributor invariants
+
+- Public capabilities must match actual implemented methods.
+- `convert()` must recompute product and stacked capabilities in the target context.
+- Geometry conversion must convert stored geometry arrays such as weights.
+- Missing capabilities must remain absent rather than becoming no-op placeholders.

spacecore-0.3.2/docs/dev/adr/006_current_batching_model.md

@@ -0,0 +1,38 @@
+# ADR-006: Current batching model
+
+## Status
+
+Accepted
+
+## Context
+
+Batching is current SpaceCore behavior. It must be documented before 0.4.0 tests are generated so contributors do not accidentally remove or misstate it.
+
+## Current design
+
+A space describes one mathematical element. Batched evaluation is represented by leading axes on values, not by changing `domain` or `codomain`. `_batching` contains shared helpers for batched membership checks and batched inner products. `checked_method(..., in_batched=True, out_batched=True)` validates trailing element shape while allowing leading dimensions.
+
+`LinOp.vapply(xs)` applies `apply` over a leading batch axis. `LinOp.rvapply(ys)` applies the adjoint over a leading batch axis. The base implementation uses `ops.vmap`; dense, sparse, diagonal, algebraic, and product-structured operators provide specialized batched paths where useful. Functionals similarly expose `vvalue` and selected `vgrad` methods. `StackedSpace` is separate: it makes a fixed stack part of one element rather than a transient evaluation batch.
+
+## Decision
+
+Batching stays as explicit vectorized methods (`vapply`, `rvapply`, `vvalue`, `vgrad`) and space batch helpers. `apply` and `rapply` remain single-element methods.
+
+## Rationale
+
+This preserves the mathematical meaning of a space while supporting efficient backend vectorization and specialized dense/product fast paths.
+
+## Alternatives considered
+
+Removing batching was rejected because current operators, tests, and materialization paths rely on it. Treating every leading axis as implicit batching in `apply` was rejected because it blurs single-element membership and makes product/pytree structure ambiguous.
+
+## Consequences
+
+0.4.0 tests must cover leading-axis validation, product-structured batches, backend fallback loops, native backend vectorization, metric `rvapply`, and consistency between single and batched methods. Known limitations include a leading-axis-only convention, backend-dependent performance, and fallback warnings where NumPy-style loops are used.
+
+## Contributor invariants
+
+- `apply` and `rapply` are single-element contracts.
+- `vapply` and `rvapply` own batched LinOp behavior.
+- Batched validation must allow leading axes but still enforce trailing element shape, backend, dtype, and product component structure.
+- Backend context conversion must preserve batched behavior and not bypass metric adjoints.

spacecore-0.3.2/docs/dev/adr/007_linop_contract.md

@@ -0,0 +1,39 @@
+# ADR-007: LinOp contract
+
+## Status
+
+Accepted
+
+## Context
+
+Linear operators are the central abstraction connecting spaces, geometry, batching, and linalg.
+
+## Current design
+
+`LinOp` owns a domain space, codomain space, and context. Construction resolves one context and converts both endpoint spaces to it. Subclasses implement `apply(x)` and `rapply(y)`. `rapply` is the Hermitian adjoint with respect to the declared space geometries. `.H` returns a cached adjoint view. Algebraic operations build lazy sums, scalar multiples, differences, and compositions. `to_dense` and `to_matrix` are explicit materialization helpers for small problems and tests.
+
+Validation uses `checked_method` and endpoint membership checks when `ctx.enable_checks` is true. Conversion rebuilds spaces and owned data or operands in a target context.
+
+## Decision
+
+The LinOp contract is mathematical: `A : X -> Y` with `apply : X -> Y` and `rapply : Y -> X` satisfying the inner-product adjoint identity. Algebra must preserve domain/codomain compatibility and context compatibility.
+
+## Rationale
+
+Solvers and functionals can rely on `LinOp` without knowing whether the operator is dense, sparse, matrix-free, or structured.
+
+## Alternatives considered
+
+A matrix-only operator API was rejected because matrix-free and structured operators are first-class. Returning raw transpose matrices for adjoints was rejected because non-Euclidean spaces require metric adjoints.
+
+## Consequences
+
+New LinOp subclasses must implement true `rapply`, batching when they can improve on `ops.vmap`, conversion, and pytree flattening where applicable. See [ADR-009](009_metric_adjoint.md) for metric adjoints and [ADR-008](008_linop_subclasses.md) for implemented families.
+
+## Contributor invariants
+
+- Domain and codomain spaces are part of operator identity.
+- `rapply` must be the geometry-aware adjoint, not merely a coordinate transpose.
+- `.H.apply(y)` must be equivalent to `rapply(y)`.
+- Algebraic operators must preserve compatible contexts and spaces.
+- Validation must check inputs and outputs against the declared endpoint spaces when enabled.

spacecore-0.3.2/docs/dev/adr/008_linop_subclasses.md

@@ -0,0 +1,38 @@
+# ADR-008: LinOp subclasses
+
+## Status
+
+Accepted
+
+## Context
+
+SpaceCore implements several LinOp storage and composition families. Contributors need to know which subclasses own coordinates and which rely on user callables.
+
+## Current design
+
+Matrix-backed operators include `DenseLinOp`, `SparseLinOp`, and `DiagonalLinOp`. They own dense tensors, sparse coordinate matrices, or diagonal arrays and implement coordinate forward actions plus metric-aware adjoints. `DenseLinOp` stores shape `cod.shape + dom.shape`; `SparseLinOp` stores a 2D sparse matrix and is limited to coordinate spaces; `DiagonalLinOp` stores one diagonal element per space coordinate.
+
+Matrix-free operators include `MatrixFreeLinOp`, which trusts user-supplied callables. `IdentityLinOp` and `ZeroLinOp` are structural operators with no matrix storage. Lazy algebraic operators include `ComposedLinOp`, `SumLinOp`, and `ScaledLinOp`. Product-structured operators include `ProductLinOp`, `BlockDiagonalLinOp`, `StackedLinOp`, and `SumToSingleLinOp`.
+
+## Decision
+
+Coordinate-backed operators own coordinate representations and may optimize dense, sparse, weighted, flat, and batched paths. Matrix-free operators trust supplied callables and only validate membership. Lazy and product operators delegate to their operands and preserve structure.
+
+## Rationale
+
+This keeps high-performance coordinate cases efficient while preserving matrix-free and structured composition as first-class APIs.
+
+## Alternatives considered
+
+Forcing every operator to expose a stored matrix was rejected because it breaks matrix-free and lazy use cases. Eagerly simplifying all algebra into dense matrices was rejected because it destroys sparsity, structure, and backend tracing.
+
+## Consequences
+
+New structured operators should avoid materializing unless explicitly requested. Product operators must preserve `ProductSpace` structures, including pytree structures. Coordinate-backed operators must implement conversion for stored arrays. Matrix-free conversion cannot rewrite backend-specific Python callables.
+
+## Contributor invariants
+
+- Matrix-backed subclasses own and validate their coordinate storage shape.
+- Matrix-free `apply` and `rapply` callables are trusted as the mathematical contract.
+- Lazy algebra must not reorder or densify operands unless a documented factory rule says so.
+- Product operators must preserve domain and codomain product structures in `apply`, `rapply`, `vapply`, and `rvapply`.

spacecore-0.3.2/docs/dev/adr/009_metric_adjoint.md

@@ -0,0 +1,44 @@
+# ADR-009: Metric adjoint
+
+## Status
+
+Accepted
+
+## Context
+
+Non-Euclidean inner products make the Euclidean coordinate adjoint insufficient. This ADR records the release-gating rule for correct adjoints.
+
+## Current design
+
+Spaces expose Riesz maps through their `InnerProduct` geometry. Matrix-backed `DenseLinOp`, `SparseLinOp`, and `DiagonalLinOp` first compute the Euclidean coordinate adjoint and then adapt it to the declared domain and codomain geometry. The formula is:
+
+```text
+A^sharp = R_X^{-1} A^dagger R_Y
+```
+
+where `A : X -> Y`, `A^dagger` is the Euclidean conjugate coordinate adjoint, and `A^sharp` is the metric adjoint. Fast paths exist for Euclidean and weighted diagonal geometries. General metric paths require usable Riesz maps. `InnerProduct.validate_for(space)` validates geometry storage such as weighted metrics.
+
+`MatrixFreeLinOp` is different: its direct `rapply` callable is already the metric adjoint and must not be Riesz-wrapped. `MatrixFreeLinOp.from_coordinate_adjoint(...)` exists for the case where the user has a Euclidean coordinate adjoint and wants SpaceCore to wrap it.
+
+## Decision
+
+Matrix-backed operators are responsible for converting coordinate adjoints into metric adjoints. Matrix-free direct `rapply` is a true adjoint by contract. Type guards alone are not a correctness fix because the issue is geometry, not only class identity.
+
+## Rationale
+
+The adjoint identity must hold for the declared spaces. Riesz maps are the architectural boundary between coordinate storage and mathematical geometry.
+
+## Alternatives considered
+
+Using only type guards for Euclidean concrete spaces was rejected because custom spaces and weighted geometries need the same mathematical rule. Always Riesz-wrapping matrix-free `rapply` was rejected because it would double-wrap correct true adjoints and break user-supplied non-coordinate implementations.
+
+## Consequences
+
+Coordinate-backed operators must reject non-Euclidean spaces without Riesz maps. Matrix-free docs and tests must distinguish true adjoints from coordinate adjoints. Batched metric adjoints should use batched Riesz maps when possible and may fall back to vectorized scalar adjoints with a warning. See [ADR-004](004_inner_product_and_geometry.md) and [ADR-007](007_linop_contract.md).
+
+## Contributor invariants
+
+- Matrix-backed adjoints use `R_X^{-1} A^dagger R_Y`.
+- `MatrixFreeLinOp(..., rapply=...)` receives a true metric adjoint and must not be automatically Riesz-wrapped.
+- `from_coordinate_adjoint` is the explicit API for wrapping a Euclidean coordinate adjoint.
+- `validate_for` and Riesz-map availability must be checked before accepting non-Euclidean coordinate-backed operators.

spacecore-0.3.2/docs/dev/adr/010_functional_contract.md

@@ -0,0 +1,36 @@
+# ADR-010: Functional contract
+
+## Status
+
+Accepted
+
+## Context
+
+Functionals are scalar-valued maps on spaces. They share context and validation mechanics with LinOps but have different mathematical contracts.
+
+## Current design
+
+`Functional` owns one domain space and a context. Subclasses implement `value(x)`. `vvalue(xs)` evaluates over a leading batch axis through backend `vmap` unless overridden. `LinearFunctional` adds a Riesz-gradient contract through `representer`, `grad`, and `vgrad`. `InnerProductFunctional` stores a representer and evaluates `<c, x>`. `MatrixFreeLinearFunctional` trusts user evaluation callables and has no stored representer. `QuadraticForm` defines optional `grad`, `vgrad`, and `hess_apply`; `LinOpQuadraticForm` stores a Hermitian operator, optional linear term, and scalar offset. Pull-backs are built by composing with a LinOp and have specializations for inner-product and quadratic functionals.
+
+## Decision
+
+A functional is not a LinOp with a one-dimensional codomain. It owns a domain and scalar-valued evaluation, and gradients are space elements with respect to the domain geometry when implemented.
+
+## Rationale
+
+Scalar-valued objectives need gradients, Hessian actions, and pull-backs that are clearer as a separate abstraction than as degenerate linear operators.
+
+## Alternatives considered
+
+Representing all functionals as LinOps into a scalar space was rejected because it obscures Riesz gradients and quadratic objective structure. Requiring every functional to expose a gradient was rejected because matrix-free scalar maps may only support value evaluation.
+
+## Consequences
+
+New functionals must validate domain inputs and scalar output shape when checks are enabled. Gradients must be Riesz gradients satisfying the domain inner-product convention. Pull-back specializations may use `A.H` and therefore depend on [ADR-009](009_metric_adjoint.md).
+
+## Contributor invariants
+
+- `value` returns a scalar-like backend value, not an element of a codomain space.
+- `grad` returns a domain element when implemented.
+- Matrix-free functionals do not imply a stored representer.
+- Functional composition requires `A.codomain == F.domain`.

spacecore-0.3.2/docs/dev/adr/011_linalg_contract.md

@@ -0,0 +1,38 @@
+# ADR-011: Linalg contract
+
+## Status
+
+Accepted
+
+## Context
+
+SpaceCore linalg routines must work for dense, sparse, matrix-free, structured, Euclidean, and non-Euclidean operators without materializing matrices by default.
+
+## Current design
+
+Implemented iterative routines include `cg`, `lsqr`, `power_iteration`, `lanczos_smallest`, and `expm_multiply`. They operate on `LinOp` or, for power iteration, a quadratic-form Hessian action. They use `LinOp.apply`, `.H.apply`, space `add`, `scale`, `inner`, and `norm`. Backend loops, conditionals, indexing, eigendecompositions of small projected matrices, and array constructors are delegated to `BackendOps`.
+
+Correctness assumptions are explicit. CG requires square Hermitian positive-definite operators in the domain geometry. LSQR uses the metric adjoint for normal-equation residuals. Power iteration, Lanczos, and exponential multiply require self-adjoint actions; known non-Hermitian structure is rejected, unknown matrix-free structure is trusted.
+
+## Decision
+
+Linalg routines are operator-driven and geometry-aware. They must not require dense materialization of the input operator and must rely on backend primitives for loop and array behavior.
+
+## Rationale
+
+This lets the same algorithms run on dense, sparse, lazy, product, and matrix-free operators while preserving non-Euclidean correctness.
+
+## Alternatives considered
+
+Delegating all linalg to backend dense solvers was rejected because it would lose structure and matrix-free support. Reimplementing backend control flow ad hoc inside each solver was rejected because JAX/Torch/NumPy need different loop semantics.
+
+## Consequences
+
+New solvers must state their mathematical assumptions in terms of spaces and geometry. They must use `A.H` for adjoint products and backend loop primitives for JIT-compatible backends. Solver workspaces should be driven by operand/operator dtype; see [ADR-015](015_dtype_default_vs_scalar_field.md).
+
+## Contributor invariants
+
+- Solvers use space operations for vector arithmetic and geometry.
+- Solvers do not materialize `A` unless the routine explicitly documents that choice.
+- Hermitian, positive-definite, and residual assumptions are with respect to the declared space inner products.
+- Backend-specific loop, indexing, and small dense linalg behavior goes through `BackendOps`.

spacecore-0.3.2/docs/dev/adr/012_jordan_spectrum.md

@@ -0,0 +1,36 @@
+# ADR-012: Jordan spectrum
+
+## Status
+
+Accepted
+
+## Context
+
+Spectral operations are mathematical capabilities of Jordan algebra spaces, not generic dense-array utilities.
+
+## Current design
+
+`JordanAlgebraSpace` exposes `jordan`, `spectrum`, `spectral_decompose`, `from_spectrum`, and `spectral_apply`. Elementwise Jordan spaces return coordinates as their spectrum with `frame=None`. `HermitianSpace` uses backend `eigh` internally but exposes the result through the Jordan spectral API. Product Jordan spaces concatenate component spectra and return `ProductSpectralDecomposition` for structured component spectral data. Stacked Jordan spaces apply base spectral operations over the leading stack.
+
+## Decision
+
+Public spectral behavior belongs to space capabilities (`spectrum` and `spectral_decompose`), not to callers reaching directly for backend `eigh` except inside the implementing space.
+
+## Rationale
+
+Different Jordan spaces have different spectral meaning. A Hermitian matrix spectrum, an elementwise spectrum, and a product spectrum have different frames and reconstruction rules.
+
+## Alternatives considered
+
+Exposing `eigh` as the universal space-level operation was rejected because it only applies to Hermitian matrix coordinates. Returning raw flattened eigenpairs for products was rejected because it loses component frames and structure.
+
+## Consequences
+
+Only Jordan-capable spaces should expose spectral operations. Product spectral decompositions must remain structured objects. New spectral spaces must define reconstruction through `from_spectrum`. See [ADR-005](005_space_subclasses_and_capabilities.md).
+
+## Contributor invariants
+
+- Do not call backend `eigh` as a generic replacement for `space.spectrum`.
+- `spectral_decompose` must return enough data for `from_spectrum` to reconstruct an element.
+- Product spectral data must preserve component boundaries.
+- Capability dispatch controls whether spectral methods are present.

spacecore-0.3.2/docs/dev/adr/013_tree_structured_spaces.md

@@ -0,0 +1,36 @@
+# ADR-013: Tree-structured spaces
+
+## Status
+
+Proposed
+
+## Context
+
+Current product spaces support tuple elements and registered pytree structures. Near-term design work should generalize this toward variable trees without losing SpaceCore-specific mathematical contracts.
+
+## Current design
+
+`ProductSpace` is currently the structured space implementation. It can use `TupleStructure` or `PytreeStructure`. `PytreeStructure` delegates flattening and unflattening to JAX tree utilities and requires registered pytree/dataclass structures. Product components remain ordered coordinate spaces and capabilities are computed from shared component capabilities.
+
+## Decision
+
+The planned direction is to model variables as pytrees and treat `ProductSpace` as a future special case of a more general `TreeSpace`. Generic tree traversal and structural definitions should be delegated to a tree library such as `optree`; SpaceCore should keep ownership of spaces, geometry, validation, context conversion, batching, and mathematical capabilities.
+
+## Rationale
+
+Tree-shaped models are common in optimization and ML, but tree traversal is not SpaceCore's mathematical differentiator. Delegating generic tree mechanics avoids maintaining a parallel tree library.
+
+## Alternatives considered
+
+Keeping only tuple product spaces was rejected as too limiting for real model variables. Reimplementing full pytree semantics inside SpaceCore was rejected because mature tree libraries already solve traversal, registration, and structure comparison.
+
+## Consequences
+
+Do not treat current `ProductSpace` as the final tree abstraction. Future work must specify how tree leaves map to spaces, how context conversion rebuilds leaves, how batching interacts with tree leaves, and how capabilities compose across trees.
+
+## Contributor invariants
+
+- This ADR is a planned direction, not an implementation claim.
+- Generic tree flattening should be delegated; SpaceCore-specific math must stay in SpaceCore.
+- Product-space behavior must remain stable until a `TreeSpace` decision supersedes it.
+- Future tree spaces must preserve validation, geometry, batching, and conversion contracts from [ADR-003](003_space_hierarchy.md) and [ADR-006](006_current_batching_model.md).