Design Records

Each record explains a decision in the design of SyntaxIR and the alternatives that were considered.

Record Status Date
000. Design Record Template Template 2026-10-09
001. Grammar JSON Marshalling Implemented 2025-06-29
002: Transparent Choice by Default Implemented 2025-06-29
003. SCC-Based Memoization and Left-Recursion Support Implemented 2025-06-30
004. Stabilizing Left Recursion in the VM Superseded 2025-06-30
005. Operators Rule Implemented 2026-10-07
006. Syntax Error Reporting and Error Recovery Implemented 2026-10-07
007. Stream Parsing and Incremental Parsing Implemented 2026-10-07
008. Generating Go Parsers Implemented 2026-10-07
009. Saving and Loading Compiled Grammars (.sxirc) Implemented 2026-10-07
010. Bytecode VM Implemented 2026-10-07
011. Source Formatting That Keeps Comments Implemented 2026-10-07
012. Typed Values in Generated Parsers Implemented 2026-10-08
013. Generating TypeScript Parsers Implemented 2026-10-08
014. Tracing and Profiling Implemented; the observation API, event and profile shapes, and examined end are superseded in part by [077](077-observability-contract.md) 2026-10-08
015. Grammar-Based Input Generation Implemented 2026-10-08
016. Web Site and Playground Implemented 2026-10-08
017. A Language Server for SyntaxIR Grammars Implemented 2026-10-08
018. Grammar Linting Implemented 2026-10-08
019. Incremental Document Storage and Tree Tooling Proposed 2026-10-09
020. Wide Repetition Bounds Implemented 2026-10-09
021. Structural Validation of Grammar ASTs Implemented 2026-10-10
022. Configurable Depth Limits in Generated Parsers Implemented 2026-10-10
023. Playground Asset Retention Across Deploys Implemented 2026-10-10
024. Reproducible Controls for Optimization Mechanisms Partially Implemented 2026-10-10
026. Bounded Stream Text Snapshots Implemented 2026-10-11
028. Strict Grammar JSON Intake Implemented 2026-10-11
029. Parse Named Rules as Typed Values Implemented 2026-10-11
030. Generate Typed TypeScript Values from Parse Trees Implemented 2026-10-11
031. Iterative Tree Traversal and JSON Output Partially Implemented 2026-10-11
032. Versioned Document Snapshots and Atomic Edit Batches Implemented 2026-10-11
033. Cancellable Parses and Budgets Implemented 2026-10-11
034. Typed Output Liveness and Alias-Safe Cleanup Proposed 2026-10-11
035. Incremental Cache Controls Implemented 2026-10-11
036. Stream Iteration and Bounded Diagnostics Implemented 2026-10-11
037. Replayable Edit Fuzzing Implemented 2026-10-11
038. Versioned Structured Output Schemas Implemented 2026-10-11
039. Conservative Document Change Notifications Implemented 2026-10-11
040. Structural Queries and Target-Language Highlighting Partially Implemented 2026-10-11
041. Opt-In Missing Literal Recovery Partially Implemented 2026-10-11
042. Responsive LSP Analysis and Code Actions Implemented 2026-10-11
043. Generated Parser Tracing and Profiling Implemented; the observation API, event and profile shapes, and examined end are superseded in part by [077](077-observability-contract.md) 2026-10-11
044. Standalone Generated Document and Stream Parsers Partially Implemented 2026-10-11
045. Serialized Recognition Programs for Compiled Grammars Superseded 2026-10-11
046. Position Maps and Fragment Parsing Partially Implemented 2026-10-12
047. Diagnostic Expectation Names Implemented 2026-10-12
048. Inline Grammar Actions Implemented 2026-10-12
049. Rule Attribute Prefixes Superseded 2026-10-12
050. Controlling Implicit Operators Rule Whitespace Skips Proposed 2026-10-12
051. Chunked Input for Document Edits Implemented 2026-10-13
052. Multi-Statement Predicate Actions Implemented 2026-10-13
053. Variable Declarations Implemented 2026-10-13
054. Generated Grammar Source Parser Accepted 2026-10-13
055. Typed Node Lists and Filtering Implemented 2026-10-14
056. Simplified Grammar Syntax View Implemented 2026-10-14
057. Source Metadata and Declaration Comments Partially Implemented 2026-10-14
058. Positional Terminal Constructors Superseded 2026-10-14
059. Grammar Fixture Runner Implemented 2026-10-14
060. Value Types and Generic Nodes Implemented 2026-10-17
061. Explicit Start Rules Implemented 2026-10-22
062. Backend-Independent Optimization IR Partially Implemented 2026-10-22
063. Configurable Optimization Pass Pipeline Implemented 2026-10-25
064. Grammar Complexity: a Cost Model, a Classifier and Safeguards Partially Implemented 2026-10-28
065. Exec IR: One Parser VM Specified for Every Target Implemented, as [Completion](#completion) defines it 2026-10-31
066. Limits Chosen by Purpose Implemented 2026-11-01
067. Repetition Run Records Partially Implemented 2026-11-04
069. Exclusion Analysis of Ordered Choice Partially Implemented 2026-11-04
070. Unknown Outranks Polynomial Implemented 2026-11-10
071. Doubled Recursion Values Implemented 2026-11-10
072. Release Package Layout Accepted 2026-11-16
073. Code IR Dialects and the Conversion Between Stages Accepted 2026-11-19
074. One Pass Pipeline per Compilation Accepted 2026-11-20
075. The Playground's WebAssembly as a Pinned Release Implemented 2026-11-20
076. Compute Units as Logical Events Proposed 2026-11-21
077. Observability Contract 2026-11-21
078. Hotspot of a Limit Error Implemented on the engine, generated Go and generated TypeScript; the rule at the check (`LimitError.Rule`) is planned and not built 2026-11-22
079. Derived Compute Budget Partially Implemented: the derivation and its report have landed, and the derived value is not the default until the linear-cost proof confirms its constants 2026-11-22