[Feature]: Guarantee downstream faer and BLAS interop with runnable tutorials

[shinaoka]

What are you trying to do?

Allow a downstream scientific Rust application to use tenferro as its main tensor stack while
calling faer or BLAS/LAPACK directly when an operation is not yet available, suitable, or fast
enough through tenferro's operation APIs.

This escape hatch should be documented and continuously verified as a normal downstream workflow,
not inferred from tenferro's internal implementation.

What makes it hard today?

The current tensor API exposes much of the required host-side information:

• compact host slices through as_slice() and mutable slice accessors;
• shape(), strides(), and offset() for typed views;
• host_storage() / host_storage_mut();
• explicit column-major compactness checks.

However, there is no end-to-end public example showing that a downstream crate can use only
published tenferro APIs to:

1. construct a zero-copy faer matrix view from a tenferro tensor;
2. construct a writable faer view or BLAS output over tenferro-owned host storage;
3. call the external library with the correct column-major layout and leading dimensions; and
4. return to tenferro without violating aliasing, placement, or threading assumptions.

The current tenferro-cpu implementation depends on faer or BLAS/LAPACK behind provider feature
flags, but it does not publicly re-export faer, cblas-sys, or lapack. Internal helpers such as
CpuBackend::with_linalg_pool and CpuExecutionContext::faer_parallelism are #[doc(hidden)] and
are described as operation-family extension contracts, not stable application-facing interop APIs.
The provider-inject feature registers provider function pointers for tenferro; it is not a general
downstream BLAS call surface.

Consequently, an application can probably assemble direct calls by adding matching dependencies,
but the supported dependency boundary, version policy, execution context, and provider-linking
contract are not demonstrated or guaranteed.

Proposed behavior or API

First, define and document the supported downstream boundary. The implementation may choose one of
these approaches:

• downstream applications depend directly on compatible faer / cblas-sys / lapack versions;
• tenferro provides an explicitly feature-gated interop re-export module; or
• a small optional interop crate provides typed adapters without expanding the core tensor API.

A re-export is not required if direct dependencies are the preferred contract. If correct thread and
resource-domain coordination cannot be achieved through existing public APIs, consider a narrow,
stable external-linalg execution boundary rather than exposing the internal buffer pool wholesale.

The selected contract must be demonstrated by runnable tutorial code and the online guide.

Required examples

faer

Provide a downstream-style example that:

• creates a compact column-major host tensor;
• borrows its storage without copying;
• constructs a faer immutable matrix view and performs a numerical operation;
• constructs a mutable view or output when soundly supported;
• verifies the numerical result;
• checks compactness before using the contiguous path; and
• explains the behavior for non-contiguous views and non-host placement.

BLAS/LAPACK

Provide a downstream-style example that:

• enables exactly one supported BLAS provider feature;
• passes tenferro host storage to a direct BLAS call with column-major layout and correct leading
  dimensions;
• writes into a tenferro-owned mutable output when soundly supported;
• verifies the numerical result; and
• documents LP64/ILP64, complex ABI, provider selection, and provider thread-control constraints.

The BLAS example should run with at least one provider in CI, not merely pass cargo check, so that
native symbol linkage is tested.

Relevant area

• tenferro-tensor host access and layout metadata
• tenferro-cpu provider features and CPU execution policy
• faer and BLAS/LAPACK interoperability
• tutorial code, rustdoc, and online documentation

Dependency, backend, or AD impact

• CPU-only for this issue.
• No CUDA, ROCm, WebGPU, Metal, or AD behavior is requested.
• Avoid adding a second mandatory linear-algebra dependency to tensor-core crates.
• Keep Cargo provider features additive while rejecting incompatible simultaneous native providers.
• Direct external calls must not silently oversubscribe tenferro's Rayon domain and the linked
  BLAS/LAPACK provider.
• Coordinate final host-access examples with the storage ownership redesign in Redesign storage ownership and accelerator runtime integration #1555 if that work
  changes the relevant public borrow APIs.

Non-goals

• Wrapping all of faer, BLAS, or LAPACK in tenferro.
• Making internal faer/LAPACK implementation modules public.
• Promising zero-copy access for backend/GPU buffers.
• Silently materializing non-contiguous views.
• Replacing the existing tenferro linalg APIs.

Acceptance criteria

• Decide and document whether downstream users should use direct dependencies, public
  re-exports, or a dedicated interop adapter crate.
• Publish an online guide such as docs/guides/external-linalg-interop.md covering layout,
  ownership, placement, threading, and provider constraints.
• Add runnable faer tutorial code compiled as an external/downstream consumer using only public
  APIs.
• Add runnable BLAS/LAPACK tutorial code compiled and linked with at least one provider in CI.
• Numerically verify immutable input, mutable output, shape, and leading-dimension behavior.
• Demonstrate or explicitly reject non-contiguous views without hidden materialization.
• Demonstrate the error/required transfer for non-host tensors.
• Ensure tutorial snippets and online documentation are sourced from or checked against the
  runnable examples so they cannot drift independently.
• Document how direct calls participate in, or deliberately remain outside, tenferro's CPU
  resource-domain and thread policy.

Related work

• [Feature]: Define a lightweight faer interop path for repeated non-contiguous row updates #1536 discusses the opposite direction: exposing faer-owned storage to tenferro/strided kernels.
  This issue covers tenferro-owned storage consumed by external faer or BLAS/LAPACK operations.
• Redesign storage ownership and accelerator runtime integration #1555 tracks the broader storage ownership redesign and its later documentation phase.

Verification

The documentation lane should execute the downstream fixtures, for example:

cargo run --manifest-path docs/tutorial-code/Cargo.toml --bin faer_interop
cargo run --manifest-path docs/tutorial-code/Cargo.toml --features blas-openblas --bin blas_interop

Exact command and fixture placement can follow the repository's existing tutorial-code conventions.

Provenance

No external prototype code is attached. Any implementation may be written from scratch under the
repository's existing MIT OR Apache-2.0 terms.

[shinaoka]

Two inputs for this tutorial work, from a 2026-08-09 investigation:

1. Real-world demand and the perceived cost. #1536 (dqmc-rs, faer::Mat as the canonical type) asked exactly for the borrowed-kernel path and assumed adding tenferro-tensor + tenferro-cpu was 'too heavy'. Measured marginal cost on top of an existing faer 0.24 dependency (cold dev build, Apple Silicon): unique dependency crates 76 -> 86 (+10, the tree is shared because the default provider IS faer), build 30s -> 58s (one-time), target/ 494MB -> 1.6GB. So the weight objection is about ownership/concepts, not dependencies, and the tutorial should answer it with the zero-copy path.

2. The API exists but is undiscoverable. The supported borrowed path today is TypedTensorView::from_slice(shape, strides, offset, &[T]) (crates/tenferro-tensor/src/types.rs:1469; mutable variant at :2386): safe, arbitrary strides over a borrowed host slice, exactly what wrapping a faer::Mat (data slice + column stride) needs. But: no guide documents external-memory interop (from_slice appears only incidentally in einsum/fft/troubleshooting snippets), the tenferro-compute skill mentions faer only as a feature flag, llms.txt has nothing, and the retired name TypedStridedTensorView (#886) survives only in the obsolete-names vocabulary test, so searchers who find the old issue land on a type that no longer exists.

Suggested acceptance addition: the faer tutorial demonstrates wrapping an existing faer::Mat via TypedTensorView::from_slice with no data copy and no ownership migration, and states the measured marginal dependency cost.