Utils.Parser Documentation Index

This index consolidates the parser documentation set and gives a short summary of each file.

Core contracts and boundaries

  • ProductionSupportContract.md: Normative 2.0.0-rc.1 product-support contract and first entry point for deciding what is guaranteed, including the explicit non-thread-safe generated static facade boundary; unlike the technical compatibility matrices, it defines the RC commitment rather than only describing implementation state.
  • RuntimeStateOwnership.md: Canonical authority map for runtime responsibilities (parse decisions, diagnostics, parse-tree ownership, scheduler/registry boundaries).
  • ParserMetadataAndRuntimeLimitations.md: Limitations-first reference that clarifies metadata-only semantics, unsupported runtime semantics, and activation preconditions.
  • RuntimeObservationAndExportContract.md: Defines what runtime observations are allowed to emit and how exporters must remain passive and non-authoritative.
  • DiagnosticsObservationCorrelation.md: Conservative rules for linking diagnostics to runtime observations without changing runtime authority.

Metadata and preparation documents

  • ContinuationMetadata.md: Describes continuation metadata lifecycle and explicitly states that metadata does not grant execution/resume authority.
  • SharedLookAheadPreparation.md: Documents shared-prefix/look-ahead preparation as deterministic advisory metadata only.
  • RuntimeArchitecture.md: Canonical pipeline and ownership map from preparation through analysis, including metadata authority boundaries.

Compatibility and analysis

  • EmbeddedCodeExecutionModel.md: Architecture boundary for ANTLR embedded code, including runtime-inline and generated-C# opt-in paths, typed RawEmbeddedCode/TransformedEmbeddedCode handoff through ParserEmbeddedCodeTransformationService, parser snapshot semantics, and the distinct lexer model: mutation-free supported predicates during exploration, actions only after acceptance, acceptance-local LexerActionExecutionResult staging, authoritative commands, lexer-owned operational state split by lifetime, and non-transactional external effects.
  • EmbeddedCodeTransactionalState.md: Transactional-state audit covering parser-managed backtracking snapshots and state-aware memoization, plus the lexer acceptance boundary, bounded action-result mutation ordering, lexer-owned operational state lifetimes, the prohibition on reusing parser state management, and external-side-effect limits.
  • PackagingAudit.md: Audits the package graph, generator layout, runtime resources, frameworks, and current publication-workflow risks.
  • ANTLRCompatibility.md: Canonical ANTLR compatibility reference, including conservative defaults, explicit labeled parser-rule return/result helper semantics, embedded-code preservation by default, typed raw/transformed transformer handoff, optional target-language transformers for $... convenience syntax, parser local/return writes, embedded-code opt-in paths, deterministic named-action diagnostics, literal call policies, generated-C# lexer inline action reads for $text/$type/$channel/$mode/$line/$pos, simple $type/$channel/$mode write support via LexerActionExecutionResult, command precedence, passive read-context behavior, edge-case coverage, a non-normative compatibility level estimate, and non-goals.
  • RuleArgumentsAndReturnsPlan.md: Durable state/design reference for ANTLR-style rule arguments, parameters, returns, labels, explicit literal policy subset completion, generation-flagged generated-C# exact positional simple-literal binding surfaces, explicit labeled child-return helpers, rollback boundaries, and progressive generated-C# opt-in integration.
  • Antlr4CompatibilityMatrix.md: Feature matrix for default, runtime-inline, and generated-C# behavior, including embedded-code preservation by default, typed raw/transformed embedded-code transformation before runtime compilation or generated emission, optional ANTLR-style attribute rewriting, parser local/current-rule return writes with generated-C# capture/rollback/memoization boundaries, explicit labeled result and return helpers, narrow supported $c.value/$xs.value generated-C# return sugar plus unsupported broader child/labeled return convenience access, named-action boundaries, unsupported diagnostics, literal call binding, generation-flagged generated-C# automatic positional binding surface distinctions, invocation-frame metadata, state-aware memoization constraints, generated-C# lexer action read/write rows, unsupported lexer predicate attributes, runtime-inline lexer execution, a non-normative compatibility level estimate, and full ANTLR lexer semantics.
  • LexerInlineActionsAndPredicatesAudit.md: Audits current minimal opt-in lexer inline action and predicate support, including predicate path rejection without managed mutation, post-acceptance action execution, acceptance-local last-write-wins results, command precedence, lexer-owned operational state lifetimes, @lexer::members, and explicit external-effect rollback exclusions.
  • RuntimeTraceAnalysis.md: Tooling-oriented analysis model for runtime traces, focused on descriptive outputs rather than runtime control.

Maintenance rule for contributors and agents

When adding, removing, or materially changing any file in docs/parser/, update this index in the same change so summaries stay accurate.

Recent metadata note

ANTLRCompatibility.md is the primary compatibility source for embedded code. EmbeddedCodeExecutionModel.md and EmbeddedCodeTransactionalState.md complement it with architecture and flow details, including the IParserEmbeddedCodeTransformer boundary, typed raw/transformed handoff through ParserEmbeddedCodeTransformationService, no-op default preservation, shared runtime indexing metadata, explicit unsupported reasons, fresh generated execution contexts for ParseWithEmbeddedCode(string), explicit context-bound generated policies, the preparatory ParserExecutionContextCopier<TContext> helper, generated Fork() / CopyFrom(...) context helpers, state-aware completed-result memoization via IParserExecutionStateManager.GetCurrentStateKey() plus post-rule snapshot restoration, managed execution-state capture/restore for parser backtracking attempt boundaries, required-property compatibility guidance, passive parser rule invocation-frame descriptor infrastructure with preserved raw rule locals and exception metadata, explicit before/after rule-call policy callbacks with current-call-site metadata, generated C# opt-in @init / @after lifecycle support with missing-only untyped null allocation and explicit rule-local frame helper methods, generated C# parser @header / @parser::header source-file injection diagnostics (UP1035), generated C# parser @parser::members execution-context injection, generated C# parser @footer / @parser::footer trailing source injection diagnostics (UP1036), deterministic unsupported custom lexer/unknown named-action diagnostics including parser named actions and unscoped parser-compatible actions in lexer grammars, the top-level parse-rejection rollback boundary, UP1030 predicate-options compatibility diagnostic, UP1033/UP1034 rule options metadata diagnostics, UP1031 parser-members injection diagnostics, and UP1029 generator diagnostics for visible unsupported constructs used to keep runtime-inline preparation and source-generated hooks aligned with limited generated-C# opt-in lexer action and predicate execution, plus optional generated-C# lexer action $text/$type/$channel/$mode/$line/$pos read rewriting, tested $text context text behavior for fragments, lexer rule references, commands, and more, tested $type/$channel/$mode passive metadata reads before lexer commands and across modes/fragments/rule references, $line/$pos accepted token/chunk start reads, simple $type/$channel/$mode writes through LexerActionExecutionResult, write-before-command ordering with command precedence, passive read-context behavior after writes, edge-case stabilization for last-write-wins, fragments, lexer rule refs, quantifiers, rejected alternatives, more, command override, and deterministic diagnostics for unsupported lexer $... forms.

Generated-C# positional rule arguments

The parser documentation pages listed here now distinguish conservative Parse(...), explicit runtime literal policies, and generated-C# exact-arity explicit simple positional argument binding for rule calls exposed by the project-wide UtilsParserEnableGeneratedRuleArgumentBinding opt-in, including zero-parameter callees, explicit empty argument lists, and the distinction from explicit runtime typed defaults. See RuleArgumentsAndReturnsPlan.md, ANTLRCompatibility.md, Antlr4CompatibilityMatrix.md, EmbeddedCodeExecutionModel.md, and EmbeddedCodeTransactionalState.md for the current support boundaries.

Generated-C# returns and labels boundary

The parser documentation now locks the generated-C# rule returns and labeled rule-call boundary to the existing parser named-action and embedded-code transformer strategy: named-action classification stays centralized in EmbeddedMembersSupport, parser headers/members/footers use the documented generated-source injection locations, rule-return and label metadata is not automatic ANTLR context support, conservative Parse(...) remains unchanged, and the implemented $returnName current-rule return convenience stays behind IParserEmbeddedCodeTransformer, while assignment-label $c.value and list-label $xs.value now rewrite to explicit helpers in supported generated-C# parser actions/@after; $child.value, $rule.value, $ctx, $c.ctx, $xs.ctx, bare labels, token attributes, typed contexts, public ANTLR-style parser methods, and general ANTLR attribute compatibility remain unsupported.

Generated binding diagnostics update

The parser documentation now records that generated-C# positional rule-call argument binding emits APU0107 only when UtilsParserEnableGeneratedRuleArgumentBinding=true and the target parser rule is uniquely resolved in the effective local or imported composition. Graph failures, rule collisions, lexer-only targets, and unresolved calls remain outside binding conclusions. See ANTLRCompatibility.md, Antlr4CompatibilityMatrix.md, and RuleArgumentsAndReturnsPlan.md for generation behavior and the bounded incremental model where per-file parsing is reusable but the collected project validation/emission stage may rerun globally.

Shared grammar import composition update

ANTLRCompatibility.md and Antlr4CompatibilityMatrix.md now define the common runtime/generator planning semantics: ordinal structural identities, source-order traversal, declared versus effective full-import/tokenVocab edge kinds after visibility propagation, visibility-specific rule provenance paths, local masking, imported collisions with deterministic source-order precedence, diamond deduplication, cycles, missing/ambiguous dependencies, alias limits, entry-owned options/actions/root, descriptive ParserDefinition.Imports, effective generator emission, and certainty-gated local/imported APU0107.

Packaged release-candidate note

ProductionSupportContract.md now also records the manifest-driven omy.Utils/omy.Utils.Parser.* package graph, isolated-feed acceptance boundary, analyzer support-assembly strategy, and the distribution properties that remain unclaimed.

The packaging audit additionally records package-only runtime/generator import scenarios, graph-changing incremental builds, deterministic graph diagnostics, and the precise boundary between portable-symbol checks and unvalidated SourceLink mappings.

Synchronized product-train release gate

PackagingAudit.md now records the single omy 2.0.0-rc.1 version authority, strict topological order, the published omy.Utils 1.2.1 API comparison boundary, and first candidate baselines for parser packages.

Global product-train integration

PackagingAudit.md now describes how the retained parser-specific packaged scenarios are nested within the repository-wide 24-package discovery, graph, generic-consumer, integrity, and dry-run publication chain. ProductionSupportContract.md clarifies that these distribution gates do not expand parser behavioral guarantees.

Edit this page