DType / Complex / Overflow Plan (Implementation)

Status (2025-12-16): This implementation plan is complete. Phase 1 complete; Phase 2 complete (int8/int16/int32/int64 + uint8/uint16/uint32/uint64 + float16 end-to-end); Phase 3 complete (complex floats are now first-class end-to-end on CPU for the current core-op surface); Phase 4 complete (support matrix declared + enforced in tests/tools). Optional backlog items are still listed below.

Scope update (2025-12)

This plan originally sketched “complex permutations for all base dtypes” (including complex int* and complex bit).

Current project direction: complex support is limited to complex floats only (complex_float16, complex_float32, complex_float64). Complex permutations of non-float dtypes (complex int* / complex bit) are a non-goal by design due to high implementation surface area (promotion/overflow/kernels/persistence/tests) with low practical payoff for PyCauset’s workloads.

As a result: - Phase 2 includes first-class float16 as a general dtype, plus the full signed/unsigned integer width set. - Phase 3 (complex) should be interpreted as “complex float integration”, with complex_float16 implemented after float16 readiness.

Phase completion status

• Phase 0 — Documentation & policy grounding: Complete
• Phase 1 — Centralize promotion + overflow policies: Complete
• Phase 2 — Scalar system expansion: Complete (int8/int16/int32/int64, uint8/uint16/uint32/uint64, float16 end-to-end through factories/promotion/CPU dispatch/persistence/bindings/NumPy for the core op surface)
• Phase 3 — Complex system integration: Complete (complex_float16/32/64 are first-class dtypes through factories/promotion/CPU dispatch/persistence/bindings/NumPy for core ops)
• Phase 4 — Coverage enforcement: Complete (support matrix declared + enforced in tests/tools)

This file is an implementation plan. The authoritative dtype behavior documentation lives in:

• documentation/internals/DType System.md

0) Problem statement

PyCauset supports several fundamentally different scalar/storage types (bit-packed bit, integers, floats) plus a partially-separate complex system. Adding a new operation currently requires touching multiple layers and remembering many dtype-specific corner cases:

• type/promotion rules are split between global helpers and per-op frontends,
• CPU kernels often dispatch on “result dtype” and omit some types,
• complex numbers are currently not a first-class MatrixBase dtype and therefore drift from the main dispatch/type-resolution path,
• missing coverage is easy to ship because there is no single enforceable “support matrix”.

This document proposes a new, centralized dtype architecture that:

• makes complex floats first-class in the scalar type system,
• adds multiple integer widths (signed/unsigned),
• defines explicit promotion + overflow policies,
• keeps the “anti-promotion / smallest type” ethos,
• keeps performance and out-of-core constraints as first-class concerns.

1) Key constraints (from project philosophy + recent decisions)

• Scale-first: matrices may be 100GB+; memory blowups are unacceptable.
• Underpromotion default: when PyCauset underpromotes, it means compute and result storage both use the smallest selected dtype.
• No silent widening for accuracy: no hidden “compute in float64 then downcast” in the default path.
• Bit matrices are numeric for arithmetic ops: treat bit values as 0/1 numeric values for arithmetic ops (e.g., +, *, dot, matmul). Bitwise ops are explicit and must preserve bit-packed storage.
• Overflow behavior: integer overflow is a runtime error. PyCauset does not auto-promote to avoid overflow.
• Overflow warning: for large integer matmul, run a worst-case bound preflight and emit a warning when overflow looks plausible.
• Complex floats are first-class: complex support is limited to float base dtypes.
• complex_float32 / complex_float64 are BLAS-backed where applicable (native complex types complex64 / complex128).
• complex_float16 is implemented as a first-class dtype using a two-plane float16 storage model.
• Complex non-floats are a non-goal: complex int* / complex bit are intentionally unsupported to avoid a large promotion/overflow/kernel/persistence surface area with low payoff.
• Fundamental-kind rule (bit/int/float): PyCauset never “promotes down” across fundamental kinds. If an operation mixes kinds, the result kind is the higher kind required by the operation’s semantics.

2) Terminology

• Scalar type: the per-element numeric type (bit/int/float plus width and flags).
• Matrix structure: dense/triangular/symmetric/etc. (storage layout and indexing constraints).
• Operation (op): add/subtract/elementwise multiply/matmul/inverse/eigvals/etc.
• Promotion policy: rules for selecting result dtypes for mixed-input ops.
• Overflow policy: what happens when integer arithmetic overflows.

3) Proposed scalar type model (flags/permutations)

Represent scalar types as:

• kind: bit | int | float
• width_bits: for int/float (8/16/32/64), and 1 for bit
• flags: a small set of orthogonal modifiers
• complex (supported for float scalar types only)
• unsigned (valid only for int)

Examples:

• bit = (bit, 1, {})
• int16 = (int, 16, {})
• uint16 = (int, 16, {unsigned})
• float16 = (float, 16, {})
• complex float16 = (float, 16, {complex})
• float32 = (float, 32, {})
• complex float32 (complex64) = (float, 32, {complex})
• float64 = (float, 64, {})
• complex float64 (complex128) = (float, 64, {complex})

Supported scalar set (initial target)

• bit
• int8/int16/int32/int64
• uint8/uint16/uint32/uint64
• float16/float32/float64
• complex_float16/complex_float32/complex_float64

4) Complex implementation strategy

4.1 Complex floats (performance path)

• Implement complex_float32 (complex64) and complex_float64 (complex128) as true complex numeric types.
• Prefer BLAS-backed complex GEMM where applicable.

4.2 Complex float16 (two-plane storage path)

• Represent complex_float16 as two float16 planes (real + imag).
• Motivation: there is no ubiquitous, efficient “native complex half” representation across the stack, and forcing complex-half into complex-float32 would violate the “smallest type” ethos.
• Persistence must round-trip as a single complex dtype (one logical object, two payload planes).

4.3 Explicit non-goals

• Complex permutations of non-float dtypes (complex int*, complex bit) are intentionally out of scope.
• If/when we ever revisit this, it must be driven by concrete workloads and come with a scoped support matrix (ops × dtype) rather than a blanket “closure” rule.

This plan does not assume automatic widening in integer matmul. Under the current policy:

• integer overflow throws, and
• the system does not silently widen storage to avoid overflow.

If we ever decide that a particular op’s semantic result dtype must be wider (e.g., a count-producing op), that must be a named, explicit promotion rule and must be documented as semantics, not an overflow workaround.

5) Promotion policy (centralized, op-specific)

Create a single authoritative table/function:

• resolve_result_scalar(op, a_scalar, b_scalar) -> scalar
• resolve_result_structure(op, a_structure, b_structure) -> structure

Design principles:

• Default to the smallest dtype that can represent the result per op semantics.
• Mixed float precision underpromotes by default (compute+store in the smaller float), with a configurable option to promote instead.
• Complex is a flag: complex-ness is preserved unless an op is explicitly defined to drop it.
• Unsigned is preserved where meaningful; if an op can generate negatives, rules must define whether to promote to signed or throw.

5.1 Fundamental kinds (bit / int / float) and “no promote down”

PyCauset distinguishes three fundamental kinds:

• bit (bit-packed boolean storage; special rules allowed)
• int (signed/unsigned integers)
• float (float16/float32/float64)

Rules:

1) No promote down across kinds. If kinds differ, the result kind cannot be the “lower” kind. 2) When a float participates, the result kind is float. Example: matmul(bit, float64) -> float64. 3) When only integers/bits participate, the result kind is integer unless the op is explicitly bitwise. 4) Underpromotion applies within a kind, not across kinds. Example: matmul(float32, float64) -> float32 by default.

This strikes a balance:

• it preserves the “smallest type” ethos where it is meaningful (within float precision),
• it avoids absurd outcomes like underpromoting a float computation to bit storage,
• it keeps bit special (bitwise ops remain bitwise; numeric ops may change kind).

5.2 Bit is special (scale-first exceptions)

Bit matrices/vectors are used to represent large binary structures (e.g., spacetime relations) where the storage is often 10s–100s of GB.

As a result:

• Bitwise ops (e.g., NOT/AND/OR/XOR) should preserve bit and stay bit-packed.
• Numeric ops that inherently create non-binary results (e.g., bit + bit, matmul(bit, bit) producing integer counts) may require widening to int or float.

For such numeric ops, widening can be prohibitively expensive. Therefore, for bit we allow explicit, op-specific behavior:

• supported with a documented widening result kind, or
• error-by-design unless the user explicitly requests a widened dtype.

The support matrix must record which choice is made for each op.

Config hooks:

• promotion_policy.float_mixed: underpromote_warn (default) | promote | underpromote_no_warn

Warning controls (exact API TBD, but must exist):

• warning_policy.float_underpromotion: on by default when promotion_policy.float_mixed=underpromote_warn
• warning_policy.int_reduction_acc_widen: on by default; emitted when dot/matmul widens the accumulator dtype
• warning_policy.int_overflow_risk_preflight: on by default for “large” integer matmul; emitted when conservative bounds indicate plausible overflow in the requested output dtype

6) Overflow policy

6.1 Runtime behavior

• Overflow is a hard error.
• PyCauset does not auto-promote storage to avoid overflow.

6.1.1 Why this focuses on integer overflow (and not float overflow)

Floating-point overflow is real (e.g., float32 can overflow to +inf), but it behaves differently:

• IEEE-754 overflow typically becomes inf (and may raise a floating-point flag), which then propagates.
• This is often detectable after-the-fact (e.g., isfinite checks), whereas integer overflow in C++ can be undefined behavior or silent wrap depending on the implementation.

Policy-wise:

• For integers: overflow must throw (no silent wrap).
• For floats: overflow results in inf/nan according to IEEE-754; optional “finite-check” validation can exist as a debug/strict mode, but it is not the default because scanning 100GB+ outputs is expensive.

6.2 Preflight warning for large integer matmul

For integer matmul (and potentially some other high-risk ops), run a cheap preflight to estimate overflow risk:

1) sample blocks/rows to estimate max_abs(A) and max_abs(B) (including scalar metadata factors if they apply) 2) compute a conservative bound:

\[\max |C_{ij}| \le K \cdot \max|A| \cdot \max|B|\]

Where \(K\) is the inner dimension (for square matmul, \(K=N\)).

If the bound approaches/exceeds the target dtype max value, emit a warning:

• PyCausetWarning: matmul(<lhs_dtype>, <rhs_dtype>) may overflow <out_dtype> (conservative bound). Consider requesting a wider output dtype or scaling.

Notes:

• This is a heuristic. It should warn on risk; it does not guarantee overflow will happen.
• It avoids inner-loop overflow checks in the performance-critical kernel.

Documentation requirement:

• Add an “Overflow” section/doc describing the policy, the preflight warning, and user mitigations.

6.3 Reduction-aware accumulator width (dot/matmul) + required warning

Some integer reductions (especially dot/matmul) can overflow the accumulator even when inputs are representable and the requested output dtype is unchanged.

To keep integer math defined and to uphold “overflow throws” without requiring expensive per-multiply-add overflow checks inside the hot loop, PyCauset uses a reduction-aware accumulator width for integer reductions.

Key clarifications (scale-first):

• This rule is about the accumulator dtype (compute registers / local scratch), not about materializing inputs.
• In particular, bit inputs stay bit-packed; matmul(bit, int16) does not expand the bit matrix to int32 elements.
• This rule does not silently widen the result storage dtype. If the user requests int16 output, the result is stored as int16 and overflow remains a hard error (typically detected at the final cast from the wider accumulator).

6.3.1 Accumulator-width selection (deterministic / conservative)

For matmul/dot over integer kinds (including bit treated as numeric 0/1), choose an accumulator dtype wide enough that the worst-case bound for the reduction fits.

For C = A @ B with inner dimension K:

• Use a conservative magnitude bound based on dtype limits (no sampling required):

\[\max |C_{ij}| \le K \cdot \max|A| \cdot \max|B|\]

• For bit, \(\max|A| = 1\).

For integer dtypes, \(\max|A|\) and \(\max|B|\) may be taken as the maximum representable magnitude for their dtypes (e.g., for int16, 32767). This is conservative and ensures accumulator selection is correctness-preserving without needing an extra pass over out-of-core data.

This is intentionally conservative: it is designed to be computed cheaply and to be correct without relying on probabilistic assumptions.

Optionally (future optimization): when it is cheap relative to the matmul itself and does not force an extra out-of-core pass, tighten the bound using exact streaming summaries such as row popcounts for bit and per-column max-abs for the integer operand.

6.3.2 User-visible warning (required)

Whenever the chosen accumulator dtype is wider than what a reader would naively expect from the inputs (e.g., matmul(bit, int16) accumulating into int32), PyCauset must emit a warning so users understand what is happening.

The warning must include:

• operation name (e.g., matmul / dot)
• lhs dtype and rhs dtype
• chosen accumulator dtype
• output storage dtype (explicitly stating whether it changed or not)
• reason (reduction-aware widening to keep integer overflow defined)

Suggested warning text (exact wording not required, but content is):

• PyCausetWarning: matmul(bit, int16) will accumulate in int32 (reduction-aware integer width). Output dtype remains int16; overflow still throws on cast. Bit input remains bit-packed (no materialization).

Noise control:

• Warn once per call site (or once per unique (op, lhs_dtype, rhs_dtype, out_dtype, acc_dtype) tuple) to avoid spam.
• Provide a user-facing way to silence/route warnings (Python warnings.warn(...) category, and/or a context flag).

7) Enforceable op coverage (“support matrix”)

Introduce an explicit coverage matrix that enumerates for each operation:

• required scalar families (bit/int/float + complex)
• supported widths
• supported structures (dense/triangular/symmetric/etc.)
• required behaviors (defined, error-by-design, or unimplemented)

Goal:

• When a new op is added, missing dtype coverage becomes a failing test/tool run, not a surprise at runtime.

8) Implementation sequence (phased)

Phase 0 — Documentation & policy grounding (Complete)

• Update project philosophy to explicitly define underpromotion and overflow behavior.
• Add roadmap entry for multi-int widths + unsigned.
• Add this plan doc.

Phase 1 — Centralize promotion + overflow policies (Complete)

• Single promotion resolver per op.
• Central overflow policy + preflight warning for integer matmul.
• Reduction-aware accumulator width for integer dot/matmul + required user warning when accumulator widens.
• Add mandatory tests for resolver correctness, warning emission, and reduction accumulator selection (see “Mandatory tests”).

Phase 2 — Scalar system expansion (Complete)

• Add integer widths + unsigned.
• Ensure constructors, IO, numpy interop, and basic ops exist.

Phase 3 — Complex system integration (Complete)

• Core complex-float dtype integration is implemented (CPU + persistence + Python/NumPy for key ops).
• See “Phase 3 — Complex system integration (Detailed)” in Section 8.1.

Phase 4 — Coverage enforcement (Complete)

• Support matrix exists and is executed by unit tests and a dev checker tool, so declared support can’t silently regress.

8.1) Phase 3 — Complex system integration (Detailed)

Objective: Make complex float dtypes first-class and integrate them into the same end-to-end pipeline as real dtypes (frontend allocation → promotion resolver → CPU/GPU dispatch → persistence → Python).

User-facing requirement: complex float dtypes must behave like normal dtypes on the frontend. For example, pc.complex_float16 (or equivalent public token) must be a valid dtype= argument to Matrix/Vector factories.

Scope for Phase 3: expand complex support to float base dtypes only:

• float16 → complex_float16 (two float16 planes)
• float32 → complex_float32 (a.k.a. complex64)
• float64 → complex_float64 (a.k.a. complex128)

Out of scope: complex permutations of non-float dtypes (complex int*, complex bit).

3.x Phase 3 status update (2025-12-16)

Completed in the current codebase:

• First-class complex float dtypes exist end-to-end: complex_float16/32/64.
• Storage:
• complex_float32/64: dense storage uses native complex element types.
• complex_float16: two-plane float16 storage (real+imag) for both matrices and vectors.
• Dispatch/promotion:
• promotion resolver supports complex results for matmul/add/sub/elementwise, plus dot/matvec/vecmat/outer.
• CPU solver contains complex implementations for dot/matvec/vecmat/outer and vector elementwise/scalar ops.
• Python/NumPy/persistence:
• dtype tokens + factory inference + np.array(...) interop + container persistence round-trip.
• dot returns Python complex when either operand is complex.

Optional backlog (not required for plan completion):

• Ensure solver/eigensystem outputs use first-class complex dtypes end-to-end (no parallel complex object model).
• BLAS/cBLAS complex GEMM path for dense complex matmul on CPU (and GPU complex where applicable).
• Expand complex coverage across additional operations beyond the current core set.

3.0 Replace legacy ComplexMatrix / ComplexVector (compat layer)

Current state (updated 2025-12-16):

• First-class complex float matrices/vectors now exist as MatrixBase/VectorBase dtypes (complex_float16/32/64).
• The legacy ComplexMatrix / ComplexVector concept may still exist in some solver/eigensystem return paths. That legacy path is now considered technical debt (it drifts from the first-class dtype pipeline).

Plan (still valid):

• Ensure any remaining solver/eigensystem paths route through first-class complex dtype matrices/vectors.
• Long-term goal: complex is a normal MatrixBase/VectorBase dtype, so LinearAlgebra and ComputeDevice don’t need a parallel complex universe.

Frontend contract note:

• Provide explicit dtype tokens for complex floats (at minimum: complex_float16, complex_float32, complex_float64).
• These tokens must normalize through the same dtype normalization funnel as real dtypes and participate in the same factory code paths.

3.1 Make “complex” first-class in the scalar type model

Requirement: represent scalar types as (kind, width_bits, flags) where flags includes at least {complex, unsigned}.

Implementation direction:

• Introduce a ScalarType descriptor (or equivalent) that can represent:
• base dtype (float16/float32/float64)
• flags (complex)
• Plumb this through the type-resolution path so promotion is defined as:
• resolve_result_scalar(op, a_scalar, b_scalar) -> scalar

Design constraint (to match the frontend requirement):

• Even though complex can be represented as (base_dtype + complex flag), it must be treated as a distinct dtype identity for:
• promotion resolution,
• dispatch selection,
• persistence metadata,
• and the support-matrix enforcement (coverage must be tracked per complex permutation).

Back-compat note:

• The existing DataType enum can remain as a legacy base-type id during migration, but Phase 3 must ensure complex-ness is not “out-of-band” anymore.

3.2 Storage strategy for complex (by base kind)

We intentionally use two different representations depending on the float width, to balance performance and scale-first storage efficiency.

3.2.1 Complex floats (performance path)

• complex_float32 (complex64) and complex_float64 (complex128) are true complex numeric types.
• Implement dense complex storage as contiguous std::complex<float> / std::complex<double> (or ABI-compatible equivalent).
• Route matmul to BLAS complex GEMM where possible.
• GPU: use cuBLAS complex GEMM when available.

3.2.2 Complex float16 (two-plane storage path)

• Represent complex_float16 as two float16 planes of equal shape:
• real plane: float16
• imag plane: float16
• Motivation: avoid forcing half-precision complex values into float32 complex storage, and avoid depending on a non-portable “native complex half” ABI.

Important clarification:

• “Two-plane storage” is an implementation detail. The object is still a single complex-typed matrix/vector from the API perspective, and it must round-trip via persistence as a complex dtype (not as two unrelated real objects).

3.3 First-class complex matrices/vectors in the core object model

Hard requirement: complex objects must participate in factories, persistence, and dispatch the same way other dtypes do.

Minimum deliverables:

• A MatrixBase-derived complex matrix implementation for:
• complex_float32 / complex_float64 (dense)
• complex_float16 (two-plane storage)
• A VectorBase-derived complex vector implementation (same split).

Interface hazards to address explicitly (to avoid “biting us later”):

• Many existing code paths use get_element_as_double(...). For complex dtypes, this must never silently drop the imaginary part.
• Either implement get_element_as_double as a hard error for complex matrices, or ensure it is only used behind a “real-only” guard.
• Complex-aware paths must use get_element_as_complex(...).
• ComputeDevice::multiply_scalar currently takes double; Phase 3 must define the complex-scalar story:
• either add complex-scalar device entry points, or
• restrict complex-scalar multiply to frontend methods that dispatch to complex kernels.

3.4 Operation coverage policy for complex

Phase 3 does not require “every op supports every complex dtype” on day one, but it must make coverage enforceable:

• For each op in the canonical LinearAlgebra surface (at least LinearAlgebra.hpp):
• declare complex propagation rules (preserve complex, drop complex, or error-by-design)
• declare result dtype selection rules (including for bit special cases)
• Ensure the resolver has explicit rows for complex permutations.

Coverage principle (mathematical independence):

• Complex permutations must be treated as separate coverage targets even when they reuse plane-wise kernels.
• “Works because it decomposes into two real ops” is not a substitute for tests: each complex dtype/op combination must be explicitly tested (or explicitly error-by-design with a stable error).

Specific expectations:

• complex_float32/complex_float64:
• add/sub/elementwise/matmul must work on CPU.
• GPU support is optional, but routing must be correct (fallback to CPU when unsupported).
• complex_float16:
• add/sub/elementwise/matmul must work on CPU.
• if implemented via two-plane arithmetic, correctness must be validated vs NumPy complex computations.

3.5 Persistence format for complex

Current implementation note (updated 2025-12-16):

• complex_float16 uses a two-plane in-memory layout (real + imag), but is persisted as a single contiguous raw payload containing both planes back-to-back.
• Typed metadata records the dtype identity (complex_float16) and the normal shape/layout fields; there is no need for multi-member payloads to round-trip correctly.

Future option (not required for correctness):

• Multi-member payloads could still be introduced later for tooling/inspection convenience, but would be an on-disk format enhancement rather than a correctness requirement.

3.6 GPU/CPU selection policy

Match project intent:

• Default behavior: benchmark/poll hardware once, then pick the fastest device.
• If GPU does not support a dtype/op/structure, fall back to CPU.
• Avoid exploding “one kernel per infinitesimal device” by using:
• a small set of coarse regimes (dtype/shape thresholds)
• a micro-benchmark-derived speedup factor

3.7 Tests (keep the explosion under control)

The only way this stays maintainable is if we separate:

• pure-logic resolver tests (exhaustive across dtype permutations), from
• kernel correctness tests (representative shapes), from
• error-by-design tests (stable error messages).

Phase 3 must add a minimal “complex smoke matrix” for the LinearAlgebra surface:

• complex_float64: add/sub/elementwise/matmul correctness vs NumPy
• complex_float32: same, smaller shapes + tolerances
• complex_float16: add/sub/elementwise/matmul correctness vs NumPy (two-plane storage) + persistence round-trip

9) Mandatory tests

These tests are required. They exist to prevent dtype coverage drift and to catch correctness/performance regressions early.

9.1 Pure-logic dtype resolution tests

Add unit tests (no kernels) that exercise the resolver tables/functions. At minimum:

• Fundamental kind rule: never promote down across bit -> int -> float.
• Float underpromotion: e.g., matmul(float32, float64) -> float32 by default.
• Complex flag behavior: for each op, verify complex propagation/behavior is explicit (preserve/drop/error-by-design) and covered.
• Unsigned flag behavior: verify signed/unsigned mixing rules are explicit and tested.
• Error-by-design paths: verify they error with stable, specific messages.

These tests should be table-driven and exhaustive across the supported dtype set for each resolver entry.

9.2 Kernel/integration correctness tests

Add tests that validate numeric correctness and overflow behavior for representative ops and shapes:

• dot/matmul integer correctness across widths.
• Overflow throws deterministically (no silent wrap).

For reduction-aware accumulator widening specifically, add at least one test where:

• matmul(bit, int16) (or dot(bit, int16)) produces a value that would overflow an int16 accumulator but fits in int32 output.
• The test asserts:
• correct numeric result,
• accumulator-widen warning is emitted and mentions: op name, lhs/rhs dtypes, accumulator dtype, and output dtype.

9.3 Warning tests (user-facing behavior)

Add Python-level tests (and C++ tests where applicable) that validate warnings are:

• emitted when required,
• de-duplicated (warn-once policy),
• informative (message includes the dtypes involved and what is happening),
• suppressible/routable via a user-facing control.

Warnings to cover:

• float underpromotion warning (if enabled)
• integer overflow-risk preflight warning (heuristic)
• integer reduction accumulator-widen warning (deterministic)

9.4 Scale-first regression tests (bit materialization guard)

Add a regression test that guards the key scale-first property for bit operands:

• bit inputs must remain bit-packed during dot/matmul (no full materialization to an int/float element buffer).

Implementation note (testability): this may require a test-only hook (e.g., allocation tracer, “materialized_bit_elements” counter, or a debug trace flag) so the test can assert that no allocation proportional to A.numel() * sizeof(int32) occurred.

9.5 Support-matrix completeness test

The support matrix must be executable as a test/tool:

• It must fail CI if an op claims support for a dtype/structure/device combination that lacks an implementation or test coverage.

10) Acceptance criteria

• Adding a new operation requires changing:
• the op implementation,
• one promotion rule table,
• one coverage declaration,

• tests. It must not require “hunt across the codebase”.

• Complex dtypes are supported for float base dtypes only (complex_float16/32/64).

• Overflow behavior is consistent:

• overflow throws,
• large integer matmul emits a risk warning when appropriate,
• no auto-promotion to avoid overflow.

11) Open questions (to confirm before implementation)

• Exact list of supported ops for “core coverage” in the support matrix (minimal set to enforce first).
• Whether unsigned + signed mixing rules should default to promoting to signed or throwing in ops that can go negative.
• Default behavior for numeric ops on bit when the semantic result is not representable in bit without widening: default widen vs error-by-design unless the caller explicitly requests an output dtype.