hakorune/docs/development/current/main/phase81-pattern2-exitline-contract.md

# Phase 81: Pattern2 ExitLine Contract Stabilization

**Status**: Design Phase

**Created**: 2025-12-13

**Priority**: P1 (Blocking Phase 82+)

---

## Goal

Pattern2（DigitPos/Trim）の promoted carriers を含む ExitLine 接続契約を堅牢化し、E2E テストで安定性を固定する。

---

## Background

### Current Issue

Phase 74-80 で BindingId migration が完了し、Pattern2/3/4 で BindingId lookup が operational になった。しかし、Pattern2 の promoted carriers（DigitPos/Trim パターンで生成される `is_digit_pos`, `is_ch_match` 等）の ExitLine 接続には以下の問題がある:

1. **ExitLine 接続タイミングの不確実性**:
   - Promoted carriers は promoter が生成するが、ExitLine reconnection が適切に行われているか検証不足
   - Exit PHI での promoted carriers の接続契約が明示されていない

2. **E2E テスト不足**:
   - DigitPos パターン（`indexOf()` 使用）の E2E テストが不足
   - Trim パターン（`skip_whitespace` 等）の E2E テストが不足
   - 既存の `tests/phase246_json_atoi.rs` が Phase 80 完了後も安定していない可能性

3. **Contract 不明確**:
   - Promoted carriers が ExitLine reconnection でどのように扱われるべきか不明確
   - CarrierRole (LoopState vs ConditionOnly) による処理の違いが文書化されていない

### Symptoms

以下の症状が観測される可能性がある（Phase 80 完了時点では未検証）:

- `tests/phase246_json_atoi.rs` テスト失敗（DigitPos pattern 使用）
- Exit PHI で promoted carriers が正しく接続されない
- ExitLine reconnection で ValueId が undefined になる
- ConditionOnly carriers が Exit PHI に含まれて不整合が起こる

---

## Reproduction

### Minimal Test Case

```rust
// DigitPos pattern with promoted carrier
local p = 0
local s = "123"
local sum = 0
loop(p < s.length()) {
    local digit_pos = s.indexOf("0", p)  // Promoted to is_digit_pos (ConditionOnly)
    if digit_pos >= 0 {                  // Break condition uses promoted carrier
        sum = sum + 1
    }
    p = p + 1
}
return sum
```

**Expected behavior**:
- `digit_pos` → `is_digit_pos` promotion succeeds
- `is_digit_pos` is ConditionOnly (not in exit_bindings)
- Exit PHI correctly includes `sum`, `p` (LoopState carriers)
- Exit PHI does NOT include `is_digit_pos` (ConditionOnly)
- Final result is correct

**Failure mode** (if contract violated):
- Exit PHI includes `is_digit_pos` → type mismatch or ValueId undefined
- Exit PHI missing `sum` or `p` → incorrect final result
- ExitLine reconnection fails → compilation error

---

## Invariants

### ExitLine Contract for Promoted Carriers

1. **CarrierRole Discrimination**:
   - `LoopState` carriers: MUST be in exit_bindings, MUST have Exit PHI
   - `ConditionOnly` carriers: MUST NOT be in exit_bindings, MUST NOT have Exit PHI

2. **Promoted Carrier Handling**:
   - All promoted carriers have `CarrierVar.binding_id` set by CarrierBindingAssigner
   - Promoted carriers follow same CarrierRole rules as non-promoted
   - ExitMetaCollector includes all carriers (LoopState + ConditionOnly) for latch incoming
   - ExitLineReconnector only processes LoopState carriers (skip ConditionOnly)

3. **ExitLine Reconnection Timing**:
   - Promoted carriers are in CarrierInfo BEFORE ExitLine reconnection
   - CarrierRole is determined BEFORE reconnection (via promoter)
   - Reconnection uses CarrierRole to filter carriers

4. **BindingId Registration Completeness**:
   - All LoopState carriers have BindingId registered in ConditionEnv
   - ConditionOnly carriers may have BindingId registered (for condition lowering)
   - Registration happens AFTER ValueId allocation, BEFORE condition lowering

---

## Design

### Verification Strategy

**Phase 81 focuses on verification, NOT new features.**

1. **Audit ExitLine Reconnection**:
   - Verify `ExitLineReconnector` correctly skips ConditionOnly carriers
   - Verify `ExitMetaCollector` includes all carriers for latch
   - Verify exit_bindings filter is correct

2. **Add E2E Tests**:
   - DigitPos pattern test (`indexOf()` with promoted `is_digit_pos`)
   - Trim pattern test (`skip_whitespace` with promoted `is_ch_match`)
   - Verify Exit PHI structure matches contract

3. **Document Contract**:
   - Create SSOT for ExitLine + promoted carriers interaction
   - Document CarrierRole-based filtering rules
   - Link to existing Phase 78-80 BindingId docs

### Implementation Tasks

**Task 81-A: ExitLine Audit** (analysis only)
- Read `ExitLineReconnector` code
- Read `ExitMetaCollector` code
- Verify CarrierRole filtering is correct
- Document findings

**Task 81-B: E2E Tests** (high priority)
- Add DigitPos E2E test to `tests/normalized_joinir_min.rs`
- Add Trim E2E test to `tests/normalized_joinir_min.rs`
- Verify `tests/phase246_json_atoi.rs` passes (existing test)
- All tests dev-only (`#[cfg(feature = "normalized_dev")]`)

**Task 81-C: Contract Documentation** (medium priority)
- Update this doc with audit findings
- Create exit_line_promoted_carriers.md if needed
- Link from phase80-bindingid-p3p4-plan.md

**Task 81-D: Smoke Tests** (verification)
- Run `tools/smokes/v2/run.sh --profile quick`
- Verify no regressions in existing tests
- Document any failures

---

## Acceptance Criteria

### Minimum Requirements

1. ✅ **E2E Tests Pass**:
   - `cargo test --release` includes DigitPos E2E test (PASS)
   - `cargo test --release` includes Trim E2E test (PASS)
   - `tests/phase246_json_atoi.rs` PASS

2. ✅ **Smoke Tests Pass**:
   - `tools/smokes/v2/run.sh --profile quick` no regressions
   - Existing Pattern2 tests continue to PASS

3. ✅ **Contract Documented**:
   - ExitLine + promoted carriers contract documented
   - CarrierRole filtering rules documented
   - Audit findings recorded

### Success Metrics

- All lib tests PASS (970/970 baseline, +2 new E2E tests = 972/972)
- All smoke tests PASS (existing baseline)
- Zero production impact (dev-only tests)
- Contract clarity increased (documentation)

---

## Out of Scope

### Phase 81 does NOT include:

1. **New Features**:
   - No new BindingId registration
   - No new promoted carriers
   - No changes to promotion logic

2. **Architecture Changes**:
   - No ExitLine reconnection refactoring
   - No CarrierRole enum changes
   - No ConditionEnv API changes

3. **Pattern3/4 Work**:
   - Phase 81 focuses on Pattern2 only
   - Pattern3/4 ExitLine is out of scope

---

## Risk Assessment

### Low Risk:

- All changes are verification (tests + docs)
- No production code changes expected
- Audit is analysis-only

### Potential Issues:

1. **Existing Contract Violation**:
   - If audit finds ExitLine currently violates contract → need fix
   - Mitigation: Fix is localized, well-documented

2. **Test Failures**:
   - If E2E tests fail → indicates real bug
   - Mitigation: Fix bug, document root cause

3. **Smoke Test Regressions**:
   - If quick smoke tests fail → need investigation
   - Mitigation: Classify as Phase 81 target or out-of-scope

---

## References

### Related Documentation

- **Phase 80**: `phase80-bindingid-p3p4-plan.md` - BindingId P3/P4 expansion
- **Phase 78**: `phase78-bindingid-promoted-carriers.md` - CarrierBindingAssigner
- **Phase 77**: Implementation guide - DigitPos/Trim promoters
- **JoinIR Architecture**: `joinir-architecture-overview.md` - ExitLine/Boundary overview

### Key Code Files

- `src/mir/builder/control_flow/joinir/merge/exit_line_reconnector.rs` - ExitLine reconnection
- `src/mir/builder/control_flow/joinir/merge/exit_meta_collector.rs` - Exit metadata collection
- `src/mir/join_ir/lowering/carrier_info.rs` - CarrierVar, CarrierRole
- `src/mir/loop_pattern_detection/digitpos_detector.rs` - DigitPos detection
- `src/mir/loop_pattern_detection/trim_detector.rs` - Trim detection

### Test Files

- `tests/normalized_joinir_min.rs` - Add Phase 81 E2E tests here
- `tests/phase246_json_atoi.rs` - Existing DigitPos test (verify PASS)

---

## Next Steps

**After Phase 81 Complete**:

1. **Phase 82 (optional)**: Pattern3/4 carrier BindingId registration in後段
   - Extend BindingId registration to carrier join_id determination points
   - Reduce fallback usage further

2. **Phase 83 (optional)**: Debug flag cleanup
   - Deprecate `NYASH_JOINIR_DEBUG` in favor of new naming
   - Migrate tests to recommended env var

---

## Implementation Notes

### Task Ordering

Execute in this order:
1. Task 81-A (Audit) - Understand current state
2. Task 81-B (E2E Tests) - Verify contract
3. Task 81-D (Smoke Tests) - Regression check
4. Task 81-C (Documentation) - Record findings

### Commit Strategy

**Single commit** for Phase 81:
```
feat(joinir): Phase 81 - Pattern2 ExitLine contract verification (dev-only)

Task 81-A: ExitLine audit findings
- ExitLineReconnector correctly skips ConditionOnly carriers
- ExitMetaCollector includes all carriers for latch
- CarrierRole filtering verified correct

Task 81-B: E2E tests for promoted carriers
- test_phase81_digitpos_exitline_contract(): DigitPos pattern
- test_phase81_trim_exitline_contract(): Trim pattern
- Verified Exit PHI excludes ConditionOnly carriers

Task 81-D: Smoke test verification
- tools/smokes/v2/run.sh --profile quick PASS
- No regressions in existing tests

Task 81-C: Contract documentation
- ExitLine + promoted carriers contract documented
- CarrierRole filtering rules clarified

Tests: 972/972 PASS (970 baseline + 2 new E2E)
Smoke: quick profile PASS (no regressions)
Design: Verification-only, zero production impact
```

---

## Status Tracking

- [ ] Task 81-A: ExitLine Audit (analysis)
- [ ] Task 81-B: E2E Tests (DigitPos + Trim)
- [ ] Task 81-C: Contract Documentation
- [ ] Task 81-D: Smoke Tests Verification

**Current Phase**: Phase 81 Design (this document)
**Next Action**: Task 81-A (ExitLine Audit)