Implementation Design Notes
Implementation-focused design notes for specific subsystems. For high-level architecture see Architecture. For normative specs see Specification. Historical implementation plans and superseded migration notes live under Plans, not this active design index.
Core Design
| Document | Description |
|---|---|
| api-and-convention-freeze.md | Clean-break release posture for public API, API consistency detection, crate ownership, naming conventions, docs ownership, and audit/remediation workflow |
| supported-ops.md | Crate-by-crate inventory of supported primal and AD operations |
| tensor.md | Tensor representation, ownership model |
| tensor-session-redesign-1938.md | Accepted #1938 target for compact tensor/storage/views and explicit session execution, with per-decision implemented mappings |
| large-transfer-staging-1945-u4.md | Implemented design for bounded chunked staging on the blocking upload route (#1945 U4 item 4): measured 6.9x at 256 MiB, and why the download direction is deliberately not chunked |
| session-oriented-concrete-apis.md | Session-borrowing concrete operation surface and its migration record |
| storage-ownership-contracts.md | Normative Phase 1 contracts for the storage ownership redesign (#1555): span access and retirement, allocation groups, submission, method distribution, raw handles and reclamation, documentation ownership, and AD value retention |
| tensor-prims.md | Tensor backend protocol and execution surface |
| backend-capability.md | Runtime backend capability descriptor for typed/erased tensor support and generated CUDA coverage |
| integer-semantics.md | CPU/CUDA integer arithmetic semantics, wrapping behavior, and structured domain errors |
| output-modes.md | Output-update vocabulary for _read, _into, _add_to, and dot _into_accum surfaces |
| algebra.md | Algebra boundary, external numeric extensions, tropical paths |
| einsum.md | Einsum public API, N-ary contraction tree, algebra dispatch |
| eager-extension-placement-dispatch.md | Runtime-targeted eager einsum/linalg extension registration with no backend fallback or transfer |
| fft-backend-execution.md | FFT backend capability, validated plan descriptors, no-fallback placement semantics, and backend-neutral cache ownership |
| contraction-pipeline.md | Binary contraction pipeline, copy elision |
| dot-general-overhead.md | Fixed-cost analysis for many small dot_general contractions |
| dynamic-symbolic-shapes.md | Dynamic and symbolic shape architecture. Covers DynamicTruncate, transpose_scatter, symbolic slice_sizes, the Exact/UpperBound/Unknown extent model, and extension equalities from graph-owned scopes through compiled guards. This is the key design doc for understanding how tenferro differs from XLA-style shape-specialized compilation. |
| eager-concatenate-shape-recording.md | Exact-shape semantic recording for eager concatenate and mixed-activity stack AD (#1692) |
| eager-semantic-promotion-recording.md | Shared eager execution/semantic input-promotion planning for AD-safe mixed dtypes (#1698) |
| eager-semantic-metadata-scope-retention.md | Metadata-scope lifetime transfer across eager semantic helper nodes (#1700) |
| gpu-backend-design.md | GPU backend architecture |
| 1945-release-capability-matrix.md | What #1945 has released, deferred or left unmeasured at the pinned revisions, the guidance naming each capability, and the downstream adoption gates |
| cubecl-fork-exit-1945.md | What the pinned cubecl fork carries for #1945, why the checked-launch write-authority hole stays upstream, and the priced own-backend contingency |
| xla-backend.md | Experimental StableHLO lowering and PJRT plugin-loading peer executor over static CompiledGraph values |
| inplace-indexing.md | Partial in-place updates design |
| linalg.md | Linalg public/composite layer |
| linalg-prims.md | Backend-facing factorization and solve contracts |
| incremental-householder-qr.md | Opaque compact QR state, column append, provider execution, and semantic AD contract (#1735) |
| incremental-householder-qr-performance-gate.md | Frozen Phase-5 CPU/CUDA benchmark protocol and acceptance thresholds (#1735) |
| capi.md | C-API: opaque handles, DLPack, einsum + SVD + AD |
| capi-error-handling.md | C-API error handling policy |
| testing.md | Testing and performance verification strategy |
| nested-cargo-debug-profile.md | Repository-owned Cargo environment defaults for debug-free guide and trybuild fixture workspaces |
| execution-engine-provider-architecture.md | Authoritative runtime-owned execution-engine, provider registration, preparation, and scheduled execution architecture |
| execution-engine-ownership.md | Caller-held engines, prepare/run ownership, CPU pools and CUDA streams, and the entry surfaces that replaced the session model (#2206); links the cross-repository decision in tensor4all-meta |
| explicit-session-boundary.md | Historical backend/eager explicit-session boundary (#1926/#1929), superseded by execution-engine-ownership.md; its session mechanics are not current contracts |
| review-decision-records.md | Relationship between historical plans, reviewer-facing work logs, and durable design records |
| change-aware-ci.md | Conservative pull-request classification, shared command profiles, stable required checks, and trusted RunPod recovery |
| ci-cache-trust.md | CI cache namespace trust model, the single trusted default-branch cache writer, material-input cache keys, and immutable GPU archive artifact reuse across allocation retries |
| runpod-gpu-provisioning.md | Live price-ordered RunPod GPU candidate selection, the pre-registration CUDA smoke proof (NVRTC -> PTX -> launch -> sync), the bounded delete-and-retry provision loop, and paid-cost observability |
Reference
See Reference for external system surveys and comparison notes.