Nesting Limits¶

Overview¶

Implementations MUST limit recursion and nesting depth to prevent stack overflow.

Requirements¶

Include Depth¶

Limit	Minimum	Recommended
Include depth	10	100

Example at depth 3:

main.beancount
└── include accounts.beancount     (depth 1)
    └── include assets.beancount   (depth 2)
        └── include bank.beancount (depth 3)

Implementations MUST: - Track current include depth - Reject includes exceeding the limit - Report the include chain in error messages

Parser Recursion¶

Limit	Minimum	Recommended
Expression depth	50	200
Metadata nesting	10	50

Cost Specification Nesting¶

Cost specs have limited nesting by grammar, but implementations MUST NOT allow unbounded recursion in cost parsing.

Error Messages¶

error: Include depth limit exceeded
  --> deeply/nested/file.beancount
  |
  = depth: 101
  = limit: 100
  = chain: main.beancount → ... → file.beancount

Implementation Guidance¶

Iterative vs Recursive¶

Prefer iterative algorithms with explicit stacks:

# Bad: recursive (can overflow)
def process(node):
    for child in node.children:
        process(child)

# Good: iterative with bounded stack
def process(root):
    stack = [root]
    while stack and len(stack) < MAX_DEPTH:
        node = stack.pop()
        stack.extend(node.children)

Stack Size Estimation¶

Language	Default Stack	Safe Recursion Depth
Python	1 MB	~1000 frames
Rust	2-8 MB	~10000 frames
JavaScript	~1 MB	~10000 frames

Rationale¶

10 depth minimum handles typical modular ledgers
100 recommended handles complex organizational structures
Limits prevent stack overflow on all platforms