Add tri-fold confidence semiring and utilities

[research-developer]

Summary

• implement a TriFold semiring for subject/predicate/object log-scores with conversion helpers
• add differentiable Phi/Psi folding utilities and export them from the confidence package
• extend the semiring property verifier and add targeted unit tests for the new semiring

Testing

• pytest tests/models/confidence/test_trifold.py -o addopts= (fails: missing torch dependency in environment)

---

https://chatgpt.com/codex/tasks/task_e_68f711c1ae7083249dbad2025c17e11d

[claude]

PR Review: Add tri-fold confidence semiring and utilities

Thank you for this contribution! Overall, this is a well-structured addition with clear documentation and good test coverage.

---

Strengths

Code Quality

• Excellent documentation: The module-level and function-level docstrings clearly explain the purpose and behavior
• Clean abstractions: The as_trifold and split_trifold helper functions provide a nice interface for working with the 4-channel structure
• Proper error handling: Input validation in _ensure_trifold and split_trifold prevents runtime errors
• Type hints: Good use of type annotations throughout

Testing

• Comprehensive test coverage: Tests cover round-trip conversion, semiring operations, folding/unfolding, and property verification
• Clear test names: Test functions are well-named and easy to understand

---

Issues and Concerns

1. Architectural Alignment (High Priority)

The TriFoldSemiring uses component-wise addition for combine() and component-wise maximum for aggregate(), which operates in log-space. However, this deviates from the documented confidence semantics in CLAUDE.md.

The TriFoldSemiring appears to be a log-space product semiring but doesn't clearly document:

1. Why log-space is needed for subject/predicate/object confidence
2. How this integrates with the existing ProductSemiring and MinMaxSemiring
3. Which NSM-12 exploration branch this belongs to (product/minmax/learned)

Recommendation: Add documentation explaining the log-space semantics and integration points.

2. Semiring Identity Element (Medium Priority)

The get_combine_identity method returns a zero tensor (additive identity in log-space), which is correct for log-probabilities. However, verify_semiring_properties test may expect probability-space semantics.

The verifier now correctly calls get_combine_identity() (good!), but the test values are in probability space [0.3, 0.8], not log-space.

Recommendation: Document that TriFoldSemiring expects log-space inputs, or update verify_semiring_properties to handle log-space semirings.

3. Output Range Validation (Medium Priority)

The verify_semiring_properties test checks 0 <= output <= 1, which is invalid for log-space values (typically negative). The test at test_trifold.py:91-96 uses torch.randn, which can be negative.

Recommendation: Skip the output range check for log-space semirings or document the expected range.

4. Missing Test Coverage (Medium Priority)

Missing tests:

• Batched operations (multi-dimensional tensors beyond 2D)
• Gradient flow through Phi/Psi operators
• Edge cases (empty tensors, single elements)
• Numerical stability (very large/small log-values)

Recommendation: Add tests for batched operations and gradient flow.

5. Naming Consistency (Low Priority)

The parameter name obj is used instead of object (since object is a Python builtin), but docstrings reference "object" which could be confusing.

Recommendation: Use obj consistently in docstrings, or use object_ / object_score.

---

Performance Considerations

1. Broadcasting overhead: as_trifold calls torch.broadcast_tensors even when shapes already match (minor impact)
2. Repeated validation: _ensure_trifold is called in every operation (low impact, but could be optimized)

---

Action Items

Required before merge:

1. Clarify architectural role in Phase 1 and NSM-12 exploration
2. Fix test compatibility with log-space semirings
3. Add batch tests for multi-dimensional tensors

Recommended:

4. Add gradient flow tests for Phi/Psi operators
5. Document expected input range (log-space vs probability-space)
6. Add edge case tests

---

Summary

This is a solid foundation for tri-fold confidence tracking, but needs architectural clarification before merging:

1. Is this intended for NSM-12 exploration or Phase 1 baseline?
2. How does it integrate with existing confidence propagation?
3. Should inputs be log-space or probability-space?

Overall Assessment: Needs clarification - Good implementation, unclear architectural fit

Let me know if you'd like help addressing any of these points!