Contributor guide

Documentation for people modifying the library: the conventions new code must follow, the test strategy and its traps, and the durable design-decision records (what was considered, what was rejected, and why) that guard settled choices against accidental re-litigation. Library users should not need anything here — the user-facing story lives in the User guide and Design notes.

Conventions for new code

• Signature style — shape comments as the real type system
• Doctest style — reproducible examples that teach
• Testing strategy — correctness, and the clean-padding blind spot
• Naming rules for contributors
• Refactoring and rename methodology

Design-decision records

• Batching and stacking — contributor internals
• The grouped-einsum interpreter — implementation internals
• Fitting & optimization — implementation internals
• Weighted layer — implementation internals
• S2 — Numerical-contract catalog (precondition vs caveat sweep)
• Design rationale: t3svd vs rank_adjustment_sweep
• Verifying a fixed-rank T3-SVD: error and rank checks
• The ambient derivative transpose — analysis & deferral note
• Why uniform orthogonalization must be SVD-based (the prefix-mask contract)
• Composing UniformTuckerTensorTrain: dynamic supercores + a static structure holder
• Rank masks — the decision record (why they exist, and why boolean)
• Uniform layer — implementation internals
• Uniform polymorphism: when an op shares the ragged code, and when it gets a ut3_ twin
• Deferred and rejected — the ledger
• Verification records