Add assisting files for closed misbehaviours and runtime analysis

.dotstop.dot

@@ -94,11 +94,11 @@ digraph G {
 "JLS-64" [sha="40f1382c156e308ee543c30df4dc7eb457ac14d472909c30eb6caae9a3bc1d68"];
 "JLS-65" [sha="e413de6c831c1c019c67c3e3477b9dc9302cc79433ec894beaee0c95e053b545"];
 "JLS-66" [sha="cf57eaf55654ef52589b1879c7294de13ddf1258ecdff4f6371178c6e8e6975b"];
-"JLS-74" [sha="c161214f0f206f3c0826750978fcc4c99e2765a0c3333592e1293b323434ca34"];
 "JLS-70" [sha="5958335832f06baaa624a093c06ce9abc2ee88c8034819ace3be2c5fff0e0a74"];
 "JLS-71" [sha="83bb8658b1b8914e0f37cdd0333d5f9351a75763486565ce7804a240d9a418ac"];
 "JLS-72" [sha="0b061840170a819c7daf1005b2eee53d121e04e921413935f5eed4fec98a8726"];
 "JLS-73" [sha="42d8dd90dc4a321923567287216e216a30c55ede8836824e19fba046a2121a97"];
+"JLS-74" [sha="c161214f0f206f3c0826750978fcc4c99e2765a0c3333592e1293b323434ca34"];
 "JLS-76" [sha="ebcfc023f88ef50a3c804cb72318428e7566dc44c3539c54742e25f261ff3249"];
 "NJF-01" [sha="548dc86014e093974f68660942daa231271496a471885bbed092a375b3079bd8"];
 "NJF-02" [sha="6ea015646d696e3f014390ff41612eab66ac940f20cf27ce933cbadf8482d526"];

TSF/docs/introduction/index.rst

@@ -61,7 +61,6 @@ The underlying standard, which defines the syntax of JSON data and the necessary
 Therefore, this documentation asserts the trustability of the capabilities of the library to recognize ill-formed JSON data according to RFC8259 and parse well-formed JSON data.
 In particular, the capabilities (and inabilities) according to different JSON formats, e.g. `RFC6902 <https://doi.org/10.17487/RFC6902>`_, `RFC7396 <https://doi.org/10.17487/RFC7396>`_, `RFC7493 <https://doi.org/10.17487/RFC7493>`_, `RFC7049 <https://doi.org/10.17487/RFC7049>`_ and `RFC8949 <https://doi.org/10.17487/RFC8949>`_ are not covered in this documentation.
 
-
 Context Diagram
 -----------------------------------
 

TSF/docs/nlohmann_closed_misbehaviours.md

@@ -0,0 +1,37 @@
+# Sample of closed upstream misbehaviours (pre-3.12.0)
+
+This file collects and comments a **sample** of *20 closed* upstream bug issues from the original [`nlohmann/json`](https://github.com/nlohmann/json) repository.
+
+Selection criteria:
+- Issue is **closed** and labeled **`kind: bug`** upstream.
+- Issue was **closed before** the upstream release of **v3.12.0** (published at `2025-04-11`).
+- A **random sample of 20** issues was taken from the upstream query: [closed `kind: bug` before v3.12.0](https://github.com/nlohmann/json/issues?q=is%3Aissue+is%3Aclosed+label%3A%22kind%3A+bug%22+closed%3A%3C2025-04-11)
+
+## sampled closed misbehaviours
+
+issue-id | applies to S-CORE | problem | resolution | closed after
+---------|-------------------|---------|------------|-------------
+[2147](https://github.com/nlohmann/json/issues/2147) | No | Compilation error report for very old GCC (4.8.5) with `std::bind`/`std::function`. | Was labeled as a compiler bug; closed as stale after no further comment from author after trial of workaround. | 2.5 months
+[2574](https://github.com/nlohmann/json/issues/2574) | No | `get<std::array<T,N>>()` fails for non-default-constructible element types. | Was fixed in https://github.com/nlohmann/json/pull/2576 and ticket closed after release in 3.10. | 3.5 months
+[2655](https://github.com/nlohmann/json/issues/2655) | No | `std::pair` serialization expectation mismatch, object serialized instead of arrays. | Documentation updated to better explain behavior. | 5 months
+[2676](https://github.com/nlohmann/json/issues/2676) | No | NVCC warnings when instantiating templates under CUDA. | Was fixed in https://github.com/nlohmann/json/pull/3227 after release in 3.10.5. | 10 months
+[2725](https://github.com/nlohmann/json/issues/2725) | No | Build with `-fno-exceptions` (and/or `JSON_NOEXCEPTIONS`) still hits `throw`. | Was already fixed in https://github.com/nlohmann/json/pull/2347. | the same day
+[3025](https://github.com/nlohmann/json/issues/3025) | No | Brace-initialization in function calls was reported to select a copy path (`func({j});` prints `10` instead of `[10]`). | Was a duplicate of https://github.com/nlohmann/json/issues/2311 and that issue was declared not a bug and solved by referencing to Docu. | next day
+[3156](https://github.com/nlohmann/json/issues/3156) | No | `std::filesystem::path` conversions unavailable for older macOS deployment targets even with C++17. | Was already solved in https://github.com/nlohmann/json/pull/3101. | the same day
+[3542](https://github.com/nlohmann/json/issues/3542) | No | AddressSanitizer container-overflow report in diagnostics code path on Windows/MSVC test configuration. | Was declared bug of MSSTL outside of nlohmann/json. | 2.5 years
+[3704](https://github.com/nlohmann/json/issues/3704) | No | `operator[]`/`.at()` to `std::string const&` binds a temporary; use `get_ref` for a real reference. | Was not a bug but expected behaviour. | the same day
+[4019](https://github.com/nlohmann/json/issues/4019) | No | `flatten()` fails to compile when using an alternative string type. | Issue was confirmed and fixed upstream in https://github.com/nlohmann/json/pull/4613. | 21 months
+[4066](https://github.com/nlohmann/json/issues/4066) | No | Parsing freeze reported on a constrained platform (Nintendo Switch) with a larger JSON input. | Author identified problem in own code. | within 1 day
+[4116](https://github.com/nlohmann/json/issues/4116) | No | GCC `-Wodr` warning about potential ODR violations in the single-header build. | Author identified it as issue of other library tinygltf. | the same day
+[4163](https://github.com/nlohmann/json/issues/4163) | No | Deprecation warning about `std::char_traits<unsigned char>` when parsing binary formats from `std::vector<std::uint8_t>`. | Was fixed in https://github.com/nlohmann/json/pull/4179. | 2 months
+[4193](https://github.com/nlohmann/json/issues/4193) | No | Exception SIGSEGV reported while parsing a valid JSON file from a stream. | Was declared issue of compiler. | the same day
+[4241](https://github.com/nlohmann/json/issues/4241) | No | `#include <version>` was reported to be shadowed by a project-provided header named `version` on the include path. | Declared issue of the calling library not adhering to standard. | the same day
+[4284](https://github.com/nlohmann/json/issues/4284) | No | `#pragma pack(push, 1)` was reported to break compilation units and lead to a segfault if packing is not restored. | Was declared not a bug but user error. | within 1 week
+[4299](https://github.com/nlohmann/json/issues/4299) | No | Single-element `std::initializer_list` construction was reported to yield an array for strings (e.g., `json{"hello"}`). | Was declared not a bug but user error. | the same day
+[4332](https://github.com/nlohmann/json/issues/4332) | No | Hex-like git ref string reported as number overflow. | Author realised themselves that it was user error. | the same day
+[4427](https://github.com/nlohmann/json/issues/4427) | No | Misfiled "CVE" report describing a Python `jaraco/zipp` issue for possible DoS Attack. | Was declared not a bug. | the same day
+[4467](https://github.com/nlohmann/json/issues/4467) | No | Error C2440 report with little context given. | Author realised themselves that it was user error. | within 1 week
+
+## Conclusion
+
+The analysis of a random sample of 20 closed upstream misbehaviours showed that misbehaviours were addressed appropriately and closed in a reasonable timeframe.

TSF/docs/nlohmann_runtime_and_memory_analysis.md

@@ -0,0 +1,42 @@
+# Runtime and memory consumption analysis
+
+This file gives an overview about performance and memory usage of the nlohmann/json library and analyses railguards at extreme memory usage and timeout.
+
+## External parsing benchmark snapshot
+
+The upstream benchmark project [miloyip/nativejson-benchmark](https://github.com/miloyip/nativejson-benchmark#parsing-time) publishes a parsing-time comparison for a wide set of C and C++ JSON libraries. Its sample result includes `nlohmann/json` and provides an external point of reference for parsing speed.
+
+![Parsing-time benchmark snapshot from miloyip/nativejson-benchmark](https://raw.githubusercontent.com/miloyip/nativejson-benchmark/master/sample/performance_Corei7-4980HQ@2.80GHz_mac64_clang7.0_1._Parse_Time_(ms).png)
+
+In the parsing-time benchmark, nlohmann/json has a parsing time of 72 ms and ranks 17th out of 40 compared JSON parsers, placing it in the faster half of the sample. The average parsing time across all parsers in that sample is 145.675 ms.
+
+The same benchmark also publishes a parsing-memory comparison for the same sample environment.
+
+![Parsing-memory benchmark snapshot from miloyip/nativejson-benchmark](https://raw.githubusercontent.com/miloyip/nativejson-benchmark/master/sample/performance_Corei7-4980HQ@2.80GHz_mac64_clang7.0_1._Parse_Memory_(byte).png)
+
+In the parsing-memory benchmark, the rank-1 parser "Qt(C++)" is excluded because the benchmark did not correctly hook its memory allocations and therefore reports an incorrect result (see https://github.com/miloyip/nativejson-benchmark?tab=readme-ov-file#parsing-memory). Of the remaining 39 parsers, nlohmann/json ranks 10th with a memory usage of 9,897,872 bytes, placing it in the lowest-memory quarter of the sample. The average memory usage across the remaining parsers is 28,922,224 bytes.
+
+Note: The figures and data above are externally maintained benchmark snapshots from the `nativejson-benchmark` repository and are included here as contextual evidence only. They were not generated by the CI of this repository and were last updated on 2016-09-09. This benchmark library was chosen due to the wide range of tested JSON libraries and its popularity, as it is also referenced in the original `nlohmann/json` repository. Newer comparisons such as https://github.com/stephenberry/json_performance show a similar broad trend for libraries that appear in both comparisons, but the exact numbers are environment-dependent and should not be treated as repository-specific guarantees.
+
+## Benchmark conclusion
+
+The benchmark snapshot does not show nlohmann/json to be a best-in-class parser for raw performance. In the sampled environment it is materially slower (~9x) and more memory-intensive (~2x) than the popular JSON parser RapidJSON, while still performing better than the sample average and remaining within the same general range as many other widely used JSON libraries.
+
+For the TSF process, the relevant conclusion is therefore not that nlohmann/json is the fastest parser, but that its observed runtime and memory characteristics are consistent with the stated scope and claims of this repository. This repository does not make a hard real-time, low-latency, or minimum-memory claim. Instead, it documents the library's expected trade-off: usability, maturity, and broad ecosystem adoption are prioritised over maximum parsing speed. As such, no disproportionate runtime or memory concern is indicated for the intended repository scope.
+
+## Scaling with runtime and memory usage
+
+For `nlohmann/json`, parsing complexity is input-dependent. [The nlohmann/json documentation](https://json.nlohmann.me/api/basic_json/parse/#complexity) states that parsing is linear in the length of the input, and may be higher depending on callback complexity and input access characteristics. [Memory usage](https://json.nlohmann.me/api/basic_json/) also depends on the stored JSON structure and value representation, as the library uses default container/value types such as std::string, std::map, and std::vector.
+
+## Maximum runtime and timeout criterion
+
+There is currently no repository-level timeout criterion defined for the runtime of `nlohmann/json` in deployed use. Instead, this is explicitly treated as an integrator responsibility in AOU-31.
+
+More specifically:
+
+- This repository defines CI- and process-based indicators, such as coverage and pull-request count gates.
+- This repository does not define a numeric runtime limit, latency budget, or automatic timeout threshold for arbitrary JSON processing in production use.
+- AOU-31 requires the integrator to define resource and time budgets for JSON parsing and validation, including maximum input size, maximum nesting or structure complexity, and maximum processing time.
+- AOU-31 also requires suitable enforcement mechanisms at the integration boundary to prevent hangs or resource exhaustion when processing untrusted or extreme inputs.
+
+This is consistent with the existing TSF scope: If a consuming system needs a maximum runtime criterion or timeout threshold, that threshold must be defined and enforced by the integrator in the target environment rather than by this repository alone.

TSF/trustable/assertions/TA-CONSTRAINTS_CONTEXT.md

@@ -59,7 +59,7 @@ reporting bugs, issues, and requests.
 - User guides detailing limitations in interfaces designed for expandability or modularity
   - **Answer**: See JLS-73.
 - Documented strategies used by external users to address constraints and work with existing Statements
-  - **Answer**: See AOU-10 and AOU-11.
+  - **Answer**: See AOU-10 and AOU-11. For resource and time budgeting constraints on parsing and validation of untrusted or extreme inputs, see also AOU-31 and the supporting analysis in TSF/docs/nlohmann_runtime_and_memory_analysis.md.
 
 **Confidence scoring**
 

TSF/trustable/assertions/TA-MISBEHAVIOURS_CONTEXT.md

@@ -89,7 +89,7 @@ established and reusable solutions.
 **Suggested evidence**
 
 - List of identified Misbehaviours
-  - **Answer**: A list of Misbehaviours was identified through STPA risk analysis (risk_analysis.md). Upstream bug tracking (JLS-11 and nlohmann_misbehaviours_comments.md) is used as complementary empirical evidence to confirm coverage and update the list where needed.
+  - **Answer**: A list of Misbehaviours was identified through STPA risk analysis (TSF/docs/risk_analysis.rst). Upstream bug tracking (JLS-11 and TSF/docs/nlohmann_misbehaviours_comments.md) is used as complementary empirical evidence to confirm coverage and update the list where needed. Furthermore, the handling of misbehaviours that were closed (TSF/docs/nlohmann_closed_misbehaviours.md) is analysed, with a focus on how long the tickets remained open and how they were resolved.
 - List of Expectations for mitigations addressing identified Misbehaviours
   - **Answer**: Mitigation expectations are expressed implicitly through (a) documented Quality assurance (https://json.nlohmann.me/community/quality_assurance) requirements and (b) concrete mitigation mechanisms captured by existing Statements: JLS-02 (fuzzing), JLS-31 (static analysis), JLS-25 (review/security policy), JLS-24 (defined failure mode via exceptions), and WFJ-06 (input validation via accept()).
 - Risk analysis