feat(interaction-map): expose Rust explained share

[seonghobae]

Summary

• compute cellwise squared reconstruction share in the Rust residual interaction-map core;
• expose the same Rust-owned diagnostic through both the existing map API and the versioned feat(interaction-map): extend Rust result envelope #1417 envelope/PyO3 surface;
• document the unclamped diagnostic contract and zero-residual semantics.

Live stack authority — 2026-09-03

This PR overlaps the residual interaction-map numerical core owned by #1417, so it remains intentionally stacked on feat/interaction-map-rust-summary-1412 rather than competing for protected main.

Fresh exact refs:

• parent feat(interaction-map): extend Rust result envelope #1417: feat/interaction-map-rust-summary-1412@3cdc684a94d7cdc0c30c0db773c0e92cfd9492f2;
• child feat(interaction-map): expose Rust explained share #1457: feat/interaction-map-explained-share@66209cce96a41c51823e3018176de73d213272e5;
• GitHub compare reports merge base exactly the current parent 3cdc684a94d7cdc0c30c0db773c0e92cfd9492f2; GitHub metadata reports the Draft open and mergeable.

The prior ancestry-stale state is repaired. #1726 merged the explicit ancestry-only reconciliation and #1725 then closed as the superseded ordinary reconciliation lane. Later compatible parent/child movement advanced both exact refs without breaking the stack; current ref state, not historical prose, is authoritative. No destructive rebase or force update is used.

Scientific contract

The share is a cell-local diagnostic, not a probability. It remains unclamped; values above one can reveal an overshooting truncated reconstruction. A near-zero residual reconstructed near zero reports 0.0; otherwise the share is unavailable and becomes NaN only at the Python projection boundary. Existing residual, reconstruction, unexplained, cross-share, Gabriel scaling, eigendecomposition, distance, inertia, input-digest, and recovery arithmetic/contracts are otherwise unchanged.

All result-affecting interaction-map arithmetic remains Rust-owned. Python exposes and validates the versioned envelope; it does not recompute explained_share or neighboring diagnostics.

Current exact-head evidence

Current exact child head is 66209cce96a41c51823e3018176de73d213272e5. Every check/review attached to an older child head is historical after that movement. This PR remains Draft because #1417 is the parent integration authority and exact-current repository/security/package/coverage/SBOM/provenance/review evidence is not assumed from predecessor runs.

Integration acceptance

• feat(interaction-map): extend Rust result envelope #1417 must integrate before this child can become a protected-main candidate.
• After any parent or child movement, re-read exact ancestry and reacquire all then-applicable repository CI, CodeQL, security/SAST, fuzz/package, coverage, SBOM/provenance, and central-review evidence.
• Only unresolved findings on the exact current head count; stale/outdated predecessor findings are not landing evidence.
• Normal protected merge requires one unchanged exact head with every applicable live gate terminal success and the live-policy qualifying independent approval, including last-push approval semantics where applicable.
• No self-approval, bypass, force push, destructive rebase, gate weakening, no-op retrigger commit, or predecessor-success transfer is authorized.

Consumer boundary

This diagnostic supports non-calculating downstream consumers without duplicating psychometric arithmetic outside fast-mlsirm. Temporal/event composition remains TEPP-owned. context-graph-contracts and enterprise-architecture-core remain read-only foreign-owner dependencies in this fast-mlsirm lane.

[coderabbitai]

Important

Draft PR not reviewed

Draft PRs are not automatically reviewed by default.

• Trigger a manual review

To automatically review draft PRs, update your CodeRabbit configuration:

reviews:
  auto_review:
    drafts: true

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[devin-ai-integration]

✅ Devin Review: No Issues Found

Devin Review analyzed this PR and found no bugs or issues to report.

[devin-ai-integration]

Devin Review found 1 new potential issue.

[seonghobae]

Current-parent reconciliation note: #1417 is fe6625d924fad95822ffe0472886acf1892bda46; this child is still ee8c21f5a1ab2258157a5ebfa10429c462d9ddda. The merge-forward preserves the child’s Rust-owned explained_share delta while carrying forward the parent’s newer input-digest / payload-replay contracts. No force push or destructive rebase is used.

[seonghobae]

Fresh recheck before the branch write: parent remains fe6625d924fad95822ffe0472886acf1892bda46; child remains ee8c21f5a1ab2258157a5ebfa10429c462d9ddda. Proceeding with the prepared two-parent merge tree.

[seonghobae]

The prepared merge tree preserves the current #1417 digest/payload-replay files and the child’s seven non-overlapping files; the three overlapping files were merged explicitly so input_digest hardening and explained_share coexist.

[seonghobae]

No branch ref has moved yet; the next mutation is the non-force merge-forward commit/ref update only.