From 8c6d3e48a5ff8e0afc312471993fd2579ca1bef9 Mon Sep 17 00:00:00 2001
From: Sanskar <sanskarin@outlook.in>
Date: Sat, 7 Nov 2026 20:38:35 +0530
Subject: [PATCH 1/6] docs(science): add bilingual release-gated scientific
 ecosystem proposal

---
 docs/project/scientific-computing.md | 68 ++++++++++++++++++++++++++++
 1 file changed, 68 insertions(+)
 create mode 100644 docs/project/scientific-computing.md

diff --git a/docs/project/scientific-computing.md b/docs/project/scientific-computing.md
new file mode 100644
index 0000000..f9fb650
--- /dev/null
+++ b/docs/project/scientific-computing.md
@@ -0,0 +1,68 @@
+# Scientific computing and AI — proposed direction
+
+**Development proposal, not a released Scarp library.** The latest verified
+public compiler prerelease is [v0.0.6-alpha.3](https://github.com/scarp-lang/scarp/releases/tag/v0.0.6-alpha.3).
+Scientific computing remains incremental: no `scarp.math`, `scarp.tensor`,
+`scarp.science` or `scarp.ai` standard-library namespaces are implemented yet.
+
+Scarp already supports immutable finite-float vectors, two-axis numeric tiles,
+checked matrix operations, selected statistics, stable softmax, ranking and
+specialized loss-gradient kernels. The language currently executes through
+a bounded Rust interpreter. Its C11 emitter is limited to an experimental,
+Rust-hosted scalar subset; this is **not** general native executable compilation.
+There is no GPU tensor backend, automatic differentiation engine or neural
+network training framework.
+
+## Work in progress: sampled calculus
+
+[Compiler PR #153](https://github.com/scarp-lang/scarp/pull/153)
+proposes two typed pure kernels:
+
+| Proposed call | Result | Purpose |
+| --- | --- | --- |
+| `sample_area(x, y)` | `float` | Integrate measurements using the composite trapezoidal rule |
+| `sample_slopes(x, y)` | `vector` | Estimate a secant derivative for each adjacent interval |
+
+This PR is **not part of alpha.3**. Do not copy its examples into projects
+built against the published compiler until a verified compatible release
+is identified. The [compiler's detailed implementation and tests](https://github.com/scarp-lang/scarp/blob/feature/scientific-sampled-calculus/docs/sampled-calculus.md)
+are reviewable, but the development branch can change.
+
+Both functions require equal-length finite-vector inputs with at least two
+entries and strictly increasing coordinates. They are not symbolic
+differentiation, spline fitting or exact integration. The branch checks
+numerical overflow, enforces bounded work and numerical output allocation,
+and uses finite binary64 arithmetic.
+
+## Architecture and dependency order
+
+1. **Numerical correctness:** scalar edge cases, stable reductions, kernels,
+   errors, budgets, platform tests and reproducible benchmarks.
+2. **Scientific algorithms:** sampled quadrature, derivatives, regression,
+   interpolation, root finding and checked numerical solvers.
+3. **Container and type design:** compatible tensor representations, rank/shape
+   semantics, safe views and explicit allocation accounting.
+4. **First-class functions and library modules:** reviewed APIs so developers
+   can express numerical models wholly in `.srp`, without writing Rust.
+5. **Automatic differentiation and training:** tested chain rules, graph
+   lifetime quotas, parameter updates and reproducible runs.
+6. **High-performance execution:** independently verified CPU lowering,
+   optional SIMD/parallel kernels and, only later, explicit GPU backends.
+
+The long-term module names `scarp.math`, `scarp.stats`,
+`scarp.linalg`, `scarp.science`, `scarp.simulate`,
+`scarp.optimize`, `scarp.units`, `scarp.tensor`, `scarp.ai`
+and `scarp.signal` are **design candidates**, not importable modules.
+
+For the technical plan and validation requirements see
+[compiler proposal 0038](https://github.com/scarp-lang/scarp/blob/feature/scientific-sampled-calculus/docs/proposals/0038-scientific-computing-ecosystem.md).
+For functionality available today, see [vectors and tiles](/language/numerics)
+and the [built-in reference](/reference/library).
+
+## Publication gate
+
+Before advertising a new numerical call as released, require a merged compiler
+change, green Linux/Windows/macOS/MSRV tests, independently checked numerical
+output, documentation reviewed against actual type signatures, and a compatible
+published compiler artifact. Version-pinned examples in this documentation
+must continue to execute with the compiler version they claim to demonstrate.

From a9bc8e30c45ebf7a44c9837dc487d56f9fbf03a7 Mon Sep 17 00:00:00 2001
From: Sanskar <sanskarin@outlook.in>
Date: Sat, 7 Nov 2026 20:38:38 +0530
Subject: [PATCH 2/6] docs(science): add bilingual release-gated scientific
 ecosystem proposal

---
 docs/hi/project/scientific-computing.md | 64 +++++++++++++++++++++++++
 1 file changed, 64 insertions(+)
 create mode 100644 docs/hi/project/scientific-computing.md

diff --git a/docs/hi/project/scientific-computing.md b/docs/hi/project/scientific-computing.md
new file mode 100644
index 0000000..24316cb
--- /dev/null
+++ b/docs/hi/project/scientific-computing.md
@@ -0,0 +1,64 @@
+# Scientific Computing और AI — प्रस्तावित विकास
+
+**स्थिति: यह विकास प्रस्ताव है, प्रकाशित Scarp लाइब्रेरी नहीं।**
+अभी सत्यापित सार्वजनिक कंपाइलर का नवीनतम प्रीरिलीज़
+[v0.0.6-alpha.3](https://github.com/scarp-lang/scarp/releases/tag/v0.0.6-alpha.3)
+है। `scarp.math`, `scarp.tensor`, `scarp.science` और `scarp.ai`
+जैसे नाम अभी वास्तविक standard-library namespace नहीं हैं।
+
+## आज क्या उपलब्ध है?
+
+Scarp में finite `float` वाले immutable vectors, दो-अक्ष के numeric tiles,
+`matvec` और `matmul` जैसी matrix operations, कुछ statistics,
+stable `softmax`, score ranking और विशेष loss-gradient kernels हैं।
+कार्यक्रम सीमित संसाधनों वाले Rust interpreter से चलते हैं।
+प्रयोगात्मक C11 backend केवल Rust API के विशेष scalar हिस्से के लिए है;
+सामान्य native compiler, GPU tensors और पूरा automatic differentiation
+framework अभी नहीं बने हैं।
+
+## नया विकास: sampled calculus
+
+[Compiler PR #153](https://github.com/scarp-lang/scarp/pull/153)
+में दो नए, typed और pure functions का प्रस्ताव एवं implementation है:
+
+| प्रस्तावित फ़ंक्शन | नतीजा | कार्य |
+| --- | --- | --- |
+| `sample_area(x, y)` | `float` | दिए गए samples से trapezoidal integration |
+| `sample_slopes(x, y)` | `vector` | हर दो पड़ोसी samples के बीच औसत slope |
+
+**ये फ़ंक्शन प्रकाशित alpha.3 में उपलब्ध नहीं हैं।**
+किसी नए compatible compiler build के परीक्षण और आधिकारिक प्रकाशन
+के बाद ही इन्हें released APIs मानना चाहिए।
+[असली compiler branch का तकनीकी विवरण](https://github.com/scarp-lang/scarp/blob/feature/scientific-sampled-calculus/docs/sampled-calculus.md)
+देख सकते हैं।
+
+दोनों inputs की लंबाई बराबर और कम-से-कम 2 होनी चाहिए। Coordinates
+strictly increasing होने चाहिए। ये numerical estimates हैं, symbolic
+differentiation या बिल्कुल सही गणितीय integration का दावा नहीं करते।
+
+## आगे काम का सही क्रम
+
+1. **सही गणित:** numerical errors, precision, resource budgets, regression tests और benchmarks।
+2. **वैज्ञानिक algorithms:** integration, differentiation, root finding और reliable solvers।
+3. **Tensor types:** सुरक्षित shape, dimension, views और memory accounting।
+4. **Scarp libraries:** `.srp` में ही simulation और AI programs लिखने योग्य APIs।
+5. **Automatic differentiation:** gradients, optimizer, reproducible neural training।
+6. **Performance:** सत्यापित CPU compiler, SIMD/parallel computing, उसके बाद GPU के अलग backend।
+
+`scarp.math`, `scarp.stats`, `scarp.linalg`, `scarp.simulate`,
+`scarp.units`, `scarp.optimize`, `scarp.ai` आदि इस समय
+केवल **प्रस्तावित नाम** हैं; उन्हें अभी import नहीं किया जा सकता।
+
+गहराई से योजना के लिए
+[compiler proposal 0038](https://github.com/scarp-lang/scarp/blob/feature/scientific-sampled-calculus/docs/proposals/0038-scientific-computing-ecosystem.md),
+और आज उपलब्ध features के लिए
+[वेक्टर/टाइल](/hi/language/numerics) तथा
+[built-ins](/hi/reference/library) देखें।
+
+## रिलीज़ से पहले सत्यापन
+
+नया feature तभी प्रकाशित माना जाए जब उसका compiler PR merge हो,
+Linux, Windows, macOS और minimum Rust checks पास हों,
+numerical correctness independently test हो और compatible compiler
+की रिलीज़ वास्तव में प्रकाशित हो। पुराने tagged compiler के साथ
+जुड़े verified code examples को बदलना नहीं चाहिए।

From 0ea6bef609edd454e1bccafaf24bb1b0f93725de Mon Sep 17 00:00:00 2001
From: Sanskar <sanskarin@outlook.in>
Date: Sat, 7 Nov 2026 20:38:49 +0530
Subject: [PATCH 3/6] docs(science): link unreleased roadmap from existing
 numerics reference

---
 docs/language/numerics.md | 8 ++++++++
 1 file changed, 8 insertions(+)

diff --git a/docs/language/numerics.md b/docs/language/numerics.md
index 2355bfa..70b1504 100644
--- a/docs/language/numerics.md
+++ b/docs/language/numerics.md
@@ -44,6 +44,14 @@ The [verified classification and probabilities tutorial](/tutorials/verified-cla
 
 The [alpha.2 collections and numeric-learning tutorial](/tutorials/alpha2-collections-and-learning) provides four additional compiler-verified complete programs: immutable integer collections, stable score selection, numerically stable probabilities, and explicit loss gradients. The separate alpha.2 fixture suite checks them against the newer release; the existing alpha.1 numerical examples remain independently pinned. These primitives do not provide automatic differentiation or a full training loop.
 
+## Scientific computing roadmap (unreleased)
+
+Scarp is extending numerical work incrementally. The [scientific computing
+proposal](/project/scientific-computing) distinguishes shipped vector/tile
+operations from proposed integration, differentiation, tensor and AI work.
+The sampled-calculus functions in compiler PR #153 are **not** in the published
+alpha.3 compiler; do not treat them as runnable released APIs.
+
 ## Limits and errors
 
 Indexing is bounds-checked. Invalid shapes, nonfinite results, and numerical payload-budget exhaustion produce diagnostics rather than silently returning invalid data. Each vector/tile element is a finite 64-bit float; some operations materialize new buffers and consume the cumulative vector-byte budget.

From b65930265fedc679aab806120c5e570aef381209 Mon Sep 17 00:00:00 2001
From: Sanskar <sanskarin@outlook.in>
Date: Sat, 7 Nov 2026 20:38:52 +0530
Subject: [PATCH 4/6] docs(science): link unreleased roadmap from existing
 numerics reference

---
 docs/hi/language/numerics.md | 7 +++++++
 1 file changed, 7 insertions(+)

diff --git a/docs/hi/language/numerics.md b/docs/hi/language/numerics.md
index ffdecd3..0fa2e03 100644
--- a/docs/hi/language/numerics.md
+++ b/docs/hi/language/numerics.md
@@ -34,6 +34,13 @@ print(matvec(weights, [2.0, 1.0])); // [4.0, 1.0]
 
 [Alpha.2 collections और probability tutorial](/hi/tutorials/alpha2-collections-and-learning) में immutable integer collections, stable score selection, numerically stable probability और स्पष्ट loss gradient के चार पूरे tagged programs मिलते हैं। इन्हें नए alpha.2 compiler के विरुद्ध अलग CI job में सत्यापित किया जाता है। यह automatic differentiation या पूरा neural-network training loop नहीं है।
 
+## Scientific computing — आने वाला विकास
+
+[वैज्ञानिक कंप्यूटिंग की योजना](/hi/project/scientific-computing)
+में लागू vector/matrix सुविधाएँ और भविष्य के calculus, tensor तथा AI
+features अलग-अलग बताए गए हैं। Compiler PR #153 के sampled-calculus
+functions अभी प्रकाशित alpha.3 में **उपलब्ध नहीं** हैं।
+
 ## आकार और संसाधन सीमा
 
 अधिकतम vector length 65,536 तत्व है। लंबाई/shape mismatch E0032, गलत numeric domain E0034, allocation E0035 और cumulative numeric payload quota E0036 दे सकते हैं। [numeric budget](/hi/reference/budgets) तथा [builtin reference](/hi/reference/library) देखें।

From c1617521db2ce44cae959d8678fb331d618f507b Mon Sep 17 00:00:00 2001
From: Sanskar <sanskarin@outlook.in>
Date: Sat, 7 Nov 2026 20:42:08 +0530
Subject: [PATCH 5/6] docs(science): use permanent PR links rather than
 short-lived feature branch links

---
 docs/project/scientific-computing.md | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/docs/project/scientific-computing.md b/docs/project/scientific-computing.md
index f9fb650..35d8aff 100644
--- a/docs/project/scientific-computing.md
+++ b/docs/project/scientific-computing.md
@@ -25,7 +25,7 @@ proposes two typed pure kernels:
 
 This PR is **not part of alpha.3**. Do not copy its examples into projects
 built against the published compiler until a verified compatible release
-is identified. The [compiler's detailed implementation and tests](https://github.com/scarp-lang/scarp/blob/feature/scientific-sampled-calculus/docs/sampled-calculus.md)
+is identified. The [compiler's detailed implementation and tests](https://github.com/scarp-lang/scarp/pull/153/files)
 are reviewable, but the development branch can change.
 
 Both functions require equal-length finite-vector inputs with at least two
@@ -55,7 +55,7 @@ The long-term module names `scarp.math`, `scarp.stats`,
 and `scarp.signal` are **design candidates**, not importable modules.
 
 For the technical plan and validation requirements see
-[compiler proposal 0038](https://github.com/scarp-lang/scarp/blob/feature/scientific-sampled-calculus/docs/proposals/0038-scientific-computing-ecosystem.md).
+[compiler proposal 0038](https://github.com/scarp-lang/scarp/pull/153/files).
 For functionality available today, see [vectors and tiles](/language/numerics)
 and the [built-in reference](/reference/library).
 

From ca7b76c08f1a9e064deedba4e0b3011010846a48 Mon Sep 17 00:00:00 2001
From: Sanskar <sanskarin@outlook.in>
Date: Sat, 7 Nov 2026 20:42:11 +0530
Subject: [PATCH 6/6] docs(science): use permanent PR links rather than
 short-lived feature branch links

---
 docs/hi/project/scientific-computing.md | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/docs/hi/project/scientific-computing.md b/docs/hi/project/scientific-computing.md
index 24316cb..fffc90d 100644
--- a/docs/hi/project/scientific-computing.md
+++ b/docs/hi/project/scientific-computing.md
@@ -29,7 +29,7 @@ framework अभी नहीं बने हैं।
 **ये फ़ंक्शन प्रकाशित alpha.3 में उपलब्ध नहीं हैं।**
 किसी नए compatible compiler build के परीक्षण और आधिकारिक प्रकाशन
 के बाद ही इन्हें released APIs मानना चाहिए।
-[असली compiler branch का तकनीकी विवरण](https://github.com/scarp-lang/scarp/blob/feature/scientific-sampled-calculus/docs/sampled-calculus.md)
+[असली compiler branch का तकनीकी विवरण](https://github.com/scarp-lang/scarp/pull/153/files)
 देख सकते हैं।
 
 दोनों inputs की लंबाई बराबर और कम-से-कम 2 होनी चाहिए। Coordinates
@@ -50,7 +50,7 @@ differentiation या बिल्कुल सही गणितीय integr
 केवल **प्रस्तावित नाम** हैं; उन्हें अभी import नहीं किया जा सकता।
 
 गहराई से योजना के लिए
-[compiler proposal 0038](https://github.com/scarp-lang/scarp/blob/feature/scientific-sampled-calculus/docs/proposals/0038-scientific-computing-ecosystem.md),
+[compiler proposal 0038](https://github.com/scarp-lang/scarp/pull/153/files),
 और आज उपलब्ध features के लिए
 [वेक्टर/टाइल](/hi/language/numerics) तथा
 [built-ins](/hi/reference/library) देखें।