diff --git a/CHANGELOG.md b/CHANGELOG.md index 02abd09..78718ef 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -7,6 +7,19 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 ## [Unreleased] +## [0.1.5] - 2026-06-23 + +### Documentation + +- Document why `maxNestingDepth` is the necessary and sufficient safety bound + for deeply nested input: a `Model.Value` is a recursive tree whose every + operation (compose, emit, compare, hash, and especially deallocate) recurses + with nesting, and Swift cannot deallocate a recursive value type iteratively, + so bounding the tree's depth at parse time is the only complete protection. + Records the measured headroom, why the bound cannot be raised without an + iterative parser (and would be pointless past the ~5,000 `deinit` limit), and + the caveat that trees built by encoding a deep `Codable` value bypass it. + ## [0.1.4] - 2026-06-23 ### Fixed diff --git a/Sources/Parsing/TokenEventParser.swift b/Sources/Parsing/TokenEventParser.swift index c6cb114..60a8c33 100644 --- a/Sources/Parsing/TokenEventParser.swift +++ b/Sources/Parsing/TokenEventParser.swift @@ -9,11 +9,40 @@ extension PureYAML.Parsing { /// with a diagnostic instead of overflowing the stack. var depth = 0 - /// Maximum node nesting the recursive-descent parser will follow. - /// Real-world specs nest well under this; the bound exists so a - /// pathologically nested document (e.g. hundreds of `[[[...]]]`) - /// throws ``ParseError/nestingTooDeep(line:column:)`` rather than - /// crashing the process. + /// Maximum node nesting the parser will follow before failing with + /// ``ParseError/nestingTooDeep(line:column:)``. + /// + /// This bound is the single safety invariant for deeply nested input, + /// and it is *necessary*, not merely convenient. A ``Model/Value`` is a + /// recursive tree, so composing it, emitting it, comparing it, hashing + /// it, and -- crucially -- deallocating it all recurse with the nesting + /// depth. Swift tears down a recursive value type recursively, and that + /// teardown cannot be made iterative cheaply, so the only way to keep + /// every operation within the call stack is to bound the depth of the + /// tree where it is built: here, while parsing. + /// + /// Because every parsing entry point routes through ``parseNode``, this + /// one bound caps the depth of any parsed tree, which transitively keeps + /// the parser, the event composers, the emitter, equality, hashing, and + /// deallocation all well inside their limits. Measured on the main + /// thread's 8 MB stack: the parser overflows near depth 225 and the + /// tree operations near depth 50,000, while real-world specs nest below + /// ~40. So 64 accepts every realistic document yet rejects pathological + /// input -- for example a 100 KB `[[[...]]]` -- cleanly and early. + /// + /// The bound cannot simply be raised: above ~225 the recursive parser + /// itself overflows before the guard fires (lifting it would require an + /// iterative parser), and a tree past ~5,000 deep crashes on `deinit` + /// regardless, so a higher limit would trade a parse-time failure for an + /// un-fixable teardown crash. 64 is the largest value that is both safe + /// here and sufficient for real input. + /// + /// Caveat: a tree built *without* the parser -- for example by encoding + /// a pathologically deep `Codable` value -- bypasses this bound, and + /// operations on such a tree are O(depth) in stack like any recursive + /// value type. Keeping those shallow is the caller's responsibility, the + /// same way the standard library cannot prevent unbounded recursion in + /// user code. static let maxNestingDepth = 64 init(