Module ast_depth 

The AST depth gate — “parsed ⇒ bounded”.

Every consumer downstream of the parser (optimizer, codegen, tree-walker, VM compiler, transpiler) walks the AST recursively; a tree nested thousands of levels deep (a 10,000-term 1+1+… chain, a parenthesis tower, a generated block pyramid) overflows their stacks and aborts the process — on every surface at once (CLI, REPL, LSP, web Studio).

The gate enforces one contract at the single choke point (Parser::parse_program): any program that parses has nesting depth ≤ the enforced limit (max_ast_depth), so downstream recursion is bounded by construction. Programs past the limit get a graceful AstTooDeep diagnostic with a Socratic fix (split into Let bindings).

The walker itself is iterative (an explicit work stack) — measuring the depth must never be the thing that overflows. Its matches are exhaustive with no wildcard: adding an AST variant with children fails compilation here, forcing the author to classify the new children — the ratchet that keeps the gate honest as the language grows.

Boxed noun-phrase payloads (Categorical, Relation, NeoEvent, comparatives) carry Terms whose nesting is bounded by English sentence structure, not by program size — they count as one level.

Constants

DEFAULT_MAX_AST_DEPTH

The DEFAULT maximum AST nesting depth.

MIN_AST_DEPTH

The smallest limit the override accepts — below this, ordinary programs stop parsing.

Functions

limit_from

Pure resolution of the override value (unit-testable without touching process environment): a parseable value is clamped to at least MIN_AST_DEPTH; anything else falls back to the default.

max_ast_depth

The EFFECTIVE depth limit: DEFAULT_MAX_AST_DEPTH unless the LOGOS_MAX_AST_DEPTH environment variable overrides it.

max_parse_recursion

The parse-time recursion budget: a quarter of the AST limit (min the floor).

program_depth

Measure the maximum nesting depth of a parsed program, iteratively.

validate_program_depth

Validate a parsed program against the effective limit (max_ast_depth).