modify docu and reference

2026-08-28 00:32:30 +09:00
parent 41816c8aef
commit ca06b4b551
37 changed files with 30338 additions and 590 deletions
@@ -0,0 +1,132 @@
+# Step 7: newton-iteration-log-writer
+
+## 읽어야 할 파일
+
+- `AGENTS.md`
+- `docs/ARCHITECTURE.md`
+- `docs/nonlinear-static-newton-raphson/io.md`
+- `docs/nonlinear-static-newton-raphson/formulation.md`
+- `docs/nonlinear-static-newton-raphson/implementation-plan.md`
+- Step 0 files: `include/fesa/app/output_paths.h`, `src/fesa/app/output_paths.cpp`, `include/fesa/analysis/analysis.h`
+- Step 5 files: `include/fesa/analysis/nonlinear_static_control.h`
+
+## 이전 Step 전제
+
+Step 0 gives app-owned log path and lease lifetime. Step 5 defines convergence-channel data that log records consume.
+
+## 소유 파일
+
+- Create: `include/fesa/analysis/newton_iteration_log.h`
+- Create: `src/fesa/analysis/newton_iteration_log.cpp`
+- Create: `tests/unit/analysis/newton_iteration_log_test.cpp`
+- Modify: `src/fesa/CMakeLists.txt`
+- Modify: `tests/CMakeLists.txt`
+
+## 인터페이스
+
+```cpp
+namespace fesa {
+
+enum class NewtonIterationStage {
+  kEntered,
+  kKinematicsEvaluated,
+  kInternalAssembled,
+  kExternalAssembled,
+  kSolvedCorrection,
+  kConvergenceEvaluated,
+  kAccepted,
+  kFailed
+};
+
+struct NewtonIterationFailure {
+  bool present;
+  NewtonIterationStage stage;
+  std::string diagnostic_code;
+  std::string reason;
+};
+
+struct NewtonIterationLogRecord {
+  std::string step_name;
+  std::uint32_t increment_index;
+  double load_factor;
+  std::uint32_t iteration;
+  NewtonIterationStage last_completed_stage;
+  NewtonIterationFailure failure;
+  std::string transition;
+  std::string outcome;
+  std::string diagnostic_code;
+  NewtonChannelDecision force_residual;
+  NewtonChannelDecision moment_residual;
+  NewtonChannelDecision translation_correction;
+  NewtonChannelDecision rotation_correction;
+  bool combined_passed;
+};
+
+class NewtonIterationLogWriter {
+ public:
+  Status Open(const std::filesystem::path& log_path);
+  Status Write(const NewtonIterationLogRecord& record);
+  Status Flush();
+  Status Close();
+};
+
+}  // namespace fesa
+```
+
+The serializer, not callers, owns the exact 39 labels and fixed order from `io.md`. For evaluated convergence channels it serializes only `relative` or `zero-scale` branch labels from `NewtonConvergenceBranch`. For unevaluated typed fields it writes `not-evaluated(reason)` using `NewtonIterationFailure::reason`. Callers cannot inject arbitrary fields.
+
+## RED
+
+Add tests first.
+
+- `NSNR-LOG-001`: a complete Newton iteration writes exactly one LF-terminated line.
+- `NSNR-LOG-002`: line is UTF-8 without BOM, no header, no trailer.
+- `NSNR-LOG-003`: line has exactly 39 TAB-separated `label=value` fields in approved order.
+- `NSNR-LOG-004`: finite numeric values round-trip without locale dependence.
+- `NSNR-LOG-005`: each convergence channel serializes identity, `numerator_norm`, `denominator_scale`, branch, threshold, `threshold_unit`, and pass from `NewtonChannelDecision`.
+- `NSNR-LOG-006`: evaluated empty free-channel decisions serialize `numerator_norm=0`, `denominator_scale=0`, threshold `1.0e-3`, the channel-specific zero-scale `threshold_unit`, and branch `zero-scale`; no other branch label appears.
+- `NSNR-LOG-007`: combined pass, transition, outcome, failure stage, and diagnostic code are serialized from explicit record fields.
+- `NSNR-LOG-008`: early failure fields after the failed stage use `not-evaluated(reason)`.
+- `NSNR-LOG-009`: embedded tab, LF, CR, and backslash are escaped deterministically.
+- `NSNR-LOG-010`: write/flush/close failure returns `log-output-failure` and prevents success classification.
+- `NSNR-LOG-011`: non-Newton controlled failure path can leave a zero-byte log owned by app lifecycle.
+
+Run:
+
+```powershell
+cmake --build .harness/build --config Debug
+ctest --test-dir .harness/build -C Debug -R "NewtonIterationLog" --output-on-failure
+```
+
+Expected: new tests fail. Unexpected pass stops.
+
+## GREEN
+
+Implement a small log writer with explicit open/write/flush/close state, serializer-owned 39-field order, deterministic escaping, finite numeric formatting, `relative`/`zero-scale` convergence branch mapping, typed `not-evaluated(reason)` substitution, and structured `Status` failures.
+
+## VERIFY
+
+```powershell
+cmake --fresh -S . -B .harness/build -G "Visual Studio 18 2026" -A x64 `
+  "-DFESA_GTEST_SOURCE_DIR=$gtestSource" `
+  "-DMKL_DIR=$mklDir" `
+  "-DTBB_DIR=$tbbDir" `
+  "-DHDF5_DIR=$hdf5Dir"
+cmake --build .harness/build --config Debug
+ctest --test-dir .harness/build -C Debug -R "NewtonIterationLog" --output-on-failure
+ctest --test-dir .harness/build -C Debug --show-only=json-v1
+ctest --test-dir .harness/build -C Debug --output-on-failure
+```
+
+Recheck `.harness/config.json` before default commands.
+
+## 상태 기록
+
+Update only Step 7 status and one-line payload. Executor owns timestamps, commits, retry, and advancement.
+
+## 금지사항
+
+- Do not duplicate per-iteration log lines to stderr. 이유: approved log is file-only.
+- Do not accept arbitrary caller-provided field vectors. 이유: io.md requires an exact fixed schema and order.
+- Do not write HDF5 trial history. 이유: log is diagnostic and HDF5 stores accepted frames only.
+- Do not continue after log write/flush/close failure. 이유: log failure blocks result commit.