feat: save a log with its system definition and read it back

save_log(logger, system, name) writes the SystemDefinition into the log
metadata under topology; definition(log) reads it from a loaded SysLog.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

Author: 1-Bort-1

changelog.d/KiteModels.jl-322.md

@@ -0,0 +1,3 @@
+### Added
+
+- `save_log(logger, system, name)` saves a KiteUtils log with the `SystemDefinition` `system` in its metadata under `topology`, and `KiteGeometry.definition(log)` reads it back from a log `load_log` loaded.

docs/src/structure.md

@@ -27,10 +27,18 @@ from_yaml
 to_yaml
 from_json
 to_json
-KiteGeometry.definition
 connectivity_sha
 ```
 
+## Logs
+
+A KiteUtils log carries a system definition as JSON in its metadata under the key `topology`. Saving a log with the definition writes it there, and `KiteGeometry.definition` reads it back from the loaded log or from the string itself.
+
+```@docs
+KiteGeometry.KiteUtils.save_log(::KiteGeometry.Logger, ::SystemDefinition)
+KiteGeometry.definition
+```
+
 ## SymbolicAWEModels' authoring YAML
 
 SymbolicAWEModels authors a system in design coordinates: points at `pos_cad`, tethers by their segment count and stretched length, `variables` shared between rows, and `transforms` that turn the whole to an elevation, azimuth and heading. `load_authoring` converts that dialect into a placed `SystemDefinition`, so `structure_document` writes it as the full-form document. Values a row leaves out — segment material, every winch's gear ratio and drum radius — come from KiteUtils `Settings`. A `canopy_faces` table with the schema's own columns states each wing's canopy: a face's wing, and its corners by name or index. A filled cell that neither the loader nor the row's model reads is refused, as `load_structure` refuses one, naming the block and its columns, and so is a block it does not read that holds rows; a row's `idx`, where it has one, must be its position. A column a dict row leaves out is an unset cell, which a model field holds only where it admits `nothing`.

src/KiteGeometry.jl

@@ -15,7 +15,7 @@ for more information.
 module KiteGeometry
 
 using JSON: JSON
-using KiteUtils: Settings, wrap2pi
+using KiteUtils: KiteUtils, Logger, Settings, SysLog, save_log, wrap2pi
 using LinearAlgebra: Diagonal, I, cross, dot, norm, normalize
 using OrderedCollections: OrderedDict, OrderedSet
 using SHA: sha256

src/document.jl

@@ -199,6 +199,27 @@ The `SystemDefinition` in the JSON structure document a log carries under the ke
 """
 definition(topology::AbstractString; strict=true) = from_json(topology; strict)
 
+"""
+    definition(log::SysLog; strict=true)
+
+The `SystemDefinition` a log loaded by `load_log` carries under its metadata key
+`topology`.
+"""
+definition(log::SysLog; strict=true) = definition(log.metadata["topology"]; strict)
+
+"""
+    save_log(logger::Logger, system::SystemDefinition, name="sim_log", compress=true;
+             metadata=Dict{String, String}(), kwargs...)
+
+`save_log(logger, name, compress; metadata, kwargs...)` with `system` added to
+`metadata` as JSON under the key `topology`, which `KiteGeometry.definition` reads back.
+"""
+function KiteUtils.save_log(logger::Logger, system::SystemDefinition, name="sim_log",
+                            compress=true; metadata=Dict{String, String}(), kwargs...)
+    metadata = merge(metadata, Dict("topology" => to_json(system)))
+    return save_log(logger, name, compress; metadata, kwargs...)
+end
+
 """
     to_yaml(system::SystemDefinition)
 

test/test-log.jl

@@ -0,0 +1,15 @@
+# SPDX-FileCopyrightText: 2026 Bart van de Lint
+# SPDX-License-Identifier: MIT
+
+using KiteUtils: Logger, SysState, load_log, log!, save_log
+
+@testset "a log saved with a system definition reads it back" begin
+    system = load_structure(joinpath(@__DIR__, "data", "v3_beam_structure.yml"))
+    logger = Logger(3, 2)
+    log!(logger, SysState(3))
+    path = mktempdir()
+    save_log(logger, system, "topology"; path, metadata=Dict("note" => "kept"))
+    log = load_log("topology"; path)
+    @test structure_document(KiteGeometry.definition(log)) == structure_document(system)
+    @test log.metadata["note"] == "kept"
+end