Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

%gra Structural Safeguards

Status: Current implementation behavior Last updated: 2026-05-19 22:51 EDT

This page describes the current structural safeguards around generated %gra tiers in batchalign3 morphotag.

The important implementation fact is narrower than a blanket linguistic “guarantee”:

  • generated %gra relations are validated before they are returned from map_ud_sentence()
  • invalid generated structures return MappingError
  • the caller skips that utterance instead of serializing the invalid %gra

That protects against known structural failures such as missing roots, multiple roots, cycles, invalid head references, and %mor/%gra chunk-count mismatch.

It does not claim that every utterance will successfully map, or that every successful %gra is linguistically correct. The safeguard is structural.

Where the validation happens

Current implementation (post crate-split):

  • crates/batchalign-transform/src/morphosyntax/sentence_mapping.rs: map_ud_sentence() at line 81 builds %mor and %gra.
  • crates/batchalign-transform/src/morphosyntax/gra_validate.rs: validate_generated_gra(&gras)? at line 20 runs before the mapping is returned.
  • The chunk-count alignment check happens in the same module before Ok((mors, gras)) is returned.
  • MappingError (with InvalidRoot, CircularDependency, InvalidHeadReference variants) is the error type, defined in the parent talkbank_transform::morphosyntax module.

If validation fails, the function returns Err(MappingError) and the caller can log and skip the utterance rather than writing broken output. The batchalign side only carries the focused validation tests at crates/batchalign/src/chat_ops/nlp/mapping/tests/core_mapping.rs.

What is validated

validate_generated_gra() currently checks:

  1. there is exactly one non-terminator root
  2. the generated graph is acyclic
  3. every head reference points to an existing relation or root

map_ud_sentence() also checks:

  1. %mor chunk count matches %gra relation count

These checks are aimed at structural correctness of generated output, not at rating the underlying dependency parse.

Failure behavior

The current contract is:

  • valid generated relations continue through injection and serialization
  • invalid generated relations fail early with MappingError
  • the utterance can be skipped without writing a malformed %gra tier

This is intentionally different from silently emitting structurally broken relations.

Focused test coverage

The current crate has six focused validation tests for generated %gra structures:

  • test_validate_generated_gra_accepts_valid
  • test_validate_generated_gra_accepts_head_zero
  • test_validate_generated_gra_rejects_no_root
  • test_validate_generated_gra_rejects_multiple_roots
  • test_validate_generated_gra_rejects_cycle
  • test_validate_generated_gra_rejects_invalid_head

You can list or run that group with:

cargo test -p batchalign validate_generated_gra

Scope

These safeguards cover the %gra structures generated by the current Rust mapping code.

They do not by themselves guarantee:

  • that an utterance will always produce output
  • that upstream NLP parses are linguistically correct
  • that pre-existing %gra tiers in old data are valid

For release-facing documentation, the accurate claim is:

batchalign3 validates generated %gra structure before emission and skips invalid generated relations instead of serializing them.

This page last changed: 2026-07-30 (commit 5157a549). The whole book last changed: 2026-09-16 (commit 34d249d8).