Segment Create/SplitSegment/MergeSegments/RebuildSegments/Duplicate -- replace manual SegmentsOS mutation with IStTxtPara.Contents edits

[MattGyverLee]

Root cause

ISegment.BaselineText is a read-only, computed ITsString property (declared in InterfaceAdditions.cs:542; implemented in OverridesCellar.cs:4397-4400). Its backing store is IStTxtPara.Contents.

The following methods in flexlibs2/code/TextsWords/SegmentOperations.py all follow the same broken pattern:

1. Manually add/remove/restructure entries in para_obj.SegmentsOS (or call SegmentsOS.Clear()).
2. Then try to set segment.BaselineText.set_String(...) or segment.BaselineText.CopyAlternatives(...) on the new/moved segments.

Both steps are wrong. SegmentsOS is owned by AnalysisAdjuster, not caller code. The correct LCM idiom is to edit IStTxtPara.Contents via a TsStrBldr; the ContentsSideEffects notification fires AnalysisAdjuster.AdjustAnalysis which rebuilds and reconciles SegmentsOS automatically.

Entangled sites (file:line)

All in flexlibs2/code/TextsWords/SegmentOperations.py:

Method	Line(s)	Nature of entanglement
Create	519 (SegmentsOS.Add) + 523 (set_String)	Creates segment, manually adds to SegmentsOS, then tries to set BaselineText
Duplicate	634 (SegmentsOS.Add) + 638 (CopyAlternatives)	Adds to SegmentsOS, then calls CopyAlternatives on ITsString (IMultiString method)
SplitSegment	890, 897 (SegmentsOS.Insert) + 892, 899 (set_String)	Inserts two new segments, sets text on each
MergeSegments	992 (SegmentsOS.Insert) + 995 (set_String)	Creates merged segment, inserts into SegmentsOS, sets text
RebuildSegments	1340 (SegmentsOS.Clear) + 1363 (SegmentsOS.Add) + 1367 (set_String)	Clears all segments, creates new ones, sets text on each

Correct write idiom (from /lex-domain analysis)

para = segment_obj.Paragraph        # IStTxtPara
begin = segment_obj.BeginOffset
end = segment_obj.EndOffset
bldr = para.Contents.GetBldr()
new_run = TsStringUtils.MakeString(new_text, ws)
bldr.ReplaceTsString(begin, end, new_run)
para.Contents = bldr.GetString()    # ContentsSideEffects -> AnalysisAdjuster.AdjustAnalysis

For Create/Split/Merge/Rebuild the equivalent idiom is to build the full desired Contents string for the paragraph and assign it once; AnalysisAdjuster handles all segment reconciliation.

Relevant liblcm sources

• InterfaceAdditions.cs:542 -- ISegment.BaselineText declaration (ITsString, get-only)
• OverridesCellar.cs:4397-4400 -- computed implementation returning substring of para Contents
• StTxtPara.cs:533-577 -- ContentsSideEffects triggering AnalysisAdjuster.AdjustAnalysis

(Source tree: D:\Github\_Projects\_LEX\liblcm\)

Dependency: test coverage

QC review of commit 295f613 noted there are currently no live tests for Duplicate, SplitSegment, or MergeSegments. These methods must have live-test coverage established before the architectural rewrite can be safely validated. Recommend filing or reusing a test-coverage issue alongside this work.

Context

Spun out of #172 after /lex-domain analysis identified that applying the bldr.ReplaceTsString fix mechanically to these methods would fight AnalysisAdjuster and likely regress. The safe read/write sites from #172 (GetSyncableProperties and SetBaselineText) were fixed directly in #172's commit; the entangled sites are deferred here.

[MattGyverLee]

Code Analysis — Direct SegmentsOS mutation inventory

Reviewed flexlibs2/code/TextsWords/SegmentOperations.py (1,427 lines).

Root cause

IStTxtPara.SegmentsOS is maintained automatically by ContentsSideEffects via AnalysisAdjuster.AdjustAnalysis. Any direct SegmentsOS.Add/Insert/Remove/Clear call bypasses that side-effect mechanism, leaving BeginOffset/EndOffset undefined or stale, and annotations orphaned.

Affected methods

Method	SegmentsOS mutations	Extra type-mismatch bug	Lines
Create	SegmentsOS.Add(segment)	BaselineText.set_String (no-op — see #172)	~540
Delete	SegmentsOS.Remove(segment_obj)	—	~571–583
Duplicate	Add + Remove + Insert (×3)	BaselineText.CopyAlternatives — IMultiString method on ITsString field; raises or silently fails	~657–681
SplitSegment	Insert ×2 + Remove	BaselineText.set_String ×2 (no-op)	~926–938
MergeSegments	Insert + Remove ×2	BaselineText.set_String (no-op)	~1035–1042
RebuildSegments	Clear + Add in loop + manual BeginOffset/EndOffset	BaselineText.set_String ×N (no-op)	~1390–1417

Also: zero UndoableUnitOfWorkHelper.Do(...) wrappers in the entire file — all write methods lack undo registration.

Reference implementation

SetBaselineText (lines 282–290) was already fixed correctly:

para = segment_obj.Paragraph
bldr = para.Contents.GetBldr()
bldr.ReplaceTsString(begin, end, new_run)
para.Contents = bldr.GetString()   # triggers AnalysisAdjuster automatically

All other methods should follow this pattern — mutate para.Contents, let AnalysisAdjuster rebuild segments.

Correct idioms per method

• Create: bldr.Replace(end_of_para, end_of_para, text, props) → assign para.Contents
• Delete: bldr.Replace(segment.BeginOffset, segment.EndOffset, "", null) → assign
• Split: insert sentence-boundary character at split_offset → assign; AnalysisAdjuster splits automatically
• Merge: remove boundary character between the two segments → assign; AnalysisAdjuster merges automatically
• Duplicate: insert duplicated text at target position in para.Contents → assign
• Rebuild: construct fresh ITsString from all sentences, assign once; AnalysisAdjuster rebuilds all segments and offsets

Effort estimate

~50 lines of write logic across 6 methods, plus transaction wrappers. Estimated 10–15 hours for a complete fix with tests. SplitSegment and MergeSegments are the hardest because they require understanding the sentence-boundary character representation in the ITsString run structure.

---

Generated by Claude Code