morluto/rea

Fork 0

mirror of https://github.com/morluto/rea.git synced 2026-11-05 06:45:22 +00:00

[PR #2124] [CLOSED] feat(domain): add opt-in address-normalized function text views #5045

New issue

Closed

opened 2026-10-31 01:00:24 +00:00 by bsakaguchi · 0 comments

bsakaguchi commented

2026-10-31 01:00:24 +00:00

Owner

📋 Pull Request Information

Original PR: https://github.com/morluto/rea/pull/2124
Author: @Zburgers
Created: 10/12/2026
Status: ❌ Closed

Base: main ← Head: feat/issue-1947-normalized-text-views

📝 Commits (10+)

f16537b feat(domain): add opt-in address-normalized function text views
f192686 fix(domain): preserve literals in normalized function views
d476f11 fix(domain): preserve normalized view semantics
4e8fbb0 test(domain): reflect unresolved normalized callees
40a778c fix(domain): preserve address space operands in normalized views
ce3504d test(javascript): align parameter provenance expectation
eba5ed9 test(ci): accept reusable release workflow jobs
bfddccd fix: reconcile main and review findings for PR #2124
8cbdee8 fix(comparison): preserve indirect operands and normalized unknown scopes
e036ba0 fix(comparison): preserve direct branch comments and captured main contracts

📊 Changes

23 files changed (+4214 additions, -70 deletions)

View changed files

📝 .agents/skills/reverse-engineer-anything/references/evidence-workflows.md (+9 -1)
📝 docs/mcp-contracts.md (+11 -0)
📝 src/contracts/sessionToolContracts.ts (+1 -1)
📝 src/domain/changedBehavior.ts (+6 -2)
📝 src/domain/functionComparison.ts (+18 -0)
➕ src/domain/functionComparisonAddressProjection.ts (+251 -0)
📝 src/domain/functionComparisonDimensions.ts (+3 -3)
📝 src/domain/functionComparisonNormalization.ts (+2 -1)
➕ src/domain/functionComparisonNormalizedViews.fixture.ts (+1677 -0)
➕ src/domain/functionComparisonNormalizedViews.test.ts (+1208 -0)
➕ src/domain/functionComparisonNormalizedViews.ts (+317 -0)
📝 src/domain/functionComparisonResults.ts (+10 -0)
📝 src/domain/functionComparisonSchemas.ts (+111 -2)
➕ src/domain/functionComparisonTextParsing.ts (+327 -0)
📝 src/domain/javascript/javascriptSemanticAnalysis.require_links.test.ts (+16 -0)
📝 src/domain/reconstructionVerification.ts (+23 -13)
📝 src/domain/reconstructionVerificationSchemas.ts (+6 -8)
📝 src/domain/residualUnknown.test.ts (+17 -0)
📝 src/domain/residualUnknown.ts (+9 -2)
📝 src/domain/staticRuntimeCorrelation.ts (+23 -14)

...and 3 more files

📄 Description

Summary

Exact function pseudocode and assembly can change when only addresses move. This adds opt-in, separate address-normalized text views to compare_functions, preserving the eight exact dimensions, their digests, summary counts, and overall status. Refs #1947.

Contract and normalization

include_normalized_views: true adds pseudocode_normalized and assembly_normalized, each with status, digests, text delta, masking rules/counts, limitations, and both source Evidence links. Omitting the option preserves the existing result and Evidence parameters.
Recognized address-derived identifiers require corroborating dossier facts and retain their provider-label prefix. Function-local labels and observed instruction/direct-branch addresses retain their exact entry-relative offsets.
External numeric uses require a corroborated direct callee/thunk target or matching instruction-site/operand reference facts. Ambiguous constants, indirect displacements, and named address spaces remain visible.
Quoted literals and comments are preserved. Unsupported raw strings, unfinished text, unavailable facets, incompatible providers, or an exceeded diff bound produce explicit unknown results.
Ordinals are assigned independently per side. Equal projected text does not establish target identity or call order. If equal text masks a callee or the procedure's own thunk target while exact calls is unknown, the normalized view is also unknown.
Normalized dimensions work in reconstruction claims, residual-unknown scopes, and static/runtime selectors. Consumers retain the selected limitations and validate every exact/normalized finding against the comparison's Evidence closure using shared domain helpers.
Assembly operand boundaries and occurrence counts are parsed once per touched line, with only the current line retained. Address-use counts come from parsed operand facts and exclude comments and quoted text; eight regressions fail on the prior parser and pass with the fix.

Evidence and validation

Current head: 8cde66673, including main at 44d98de23. Merge conflicts in the comparison consumers and documentation are resolved.

Native Windows, Node 24.18.0 / npm 11.16.0:

271 focused domain tests passed, including normalization, exact comparison, reconstruction/source coverage, correlation, changed behavior, and residual unknowns.
10 compiled MCP boundary tests passed.
The inherited Source tests failure (#3341) is reconciled with main's lexical-binding fix. Both explicit CommonJS and explicit-module controls pass; the superseded test expectation is removed.
npm run check, npm run docs:check (including five README consistency tests), build, push checks, and git diff --check passed.
Regressions cover literals/comments, changed constants/offsets, ambiguous operands, changed/swapped callees, own-function thunks, unavailable facets, provenance closure, normalized questions, and long imported assembly lines.
Completed comparisons with 1,000 numeric operands improved from roughly 1.0–1.4 seconds to 9–17 ms in warm runs; serialized results and token estimates were identical. Cold/warm elapsed time, CPU, peak memory, and measurement limits are recorded in the review-thread response.

Real Ghidra 12.1.4 verification at this head completed 24 compare-pairs and 3 Wallace comparisons on Windows 10 x64. Constant edits were detected in all 8 normalized views. Changed-call cases produced 3 changed and 5 unknown views, with zero false unchanged views, including the x64 -O2 thunk. Wallace matched expectations. Relocation-only coverage is limited: 4/12 function comparisons remain unchanged and 8/12 are unknown in both views. Unknown means equality could not be established, not that a change was detected. These are fixture-specific results. No fresh IDA, Hopper, or Linux provider run is claimed. Current-head CI test lanes passed.

Remaining limits

Caller dossiers contain callee identities and thunk targets, not callee bodies or cross-build correspondence evidence. Callee matching is tracked separately in #3506, following Pablo's recommendation: shared tokens should represent supported callee matches, with complete callee Evidence, thunk handling, and explicit ambiguity checks. Unmatched callees remain unknown under the current policy. A normalized body digest alone is not proof of procedure identity.

No provider reads, target execution, installation, or new persistence are added. Provider startup, transport/schema advertisement, and complete agent-task costs were not measured.

Author readiness

Human owner: @Zburgers

I reviewed the final diff and relevant existing code, understand the change and its edge cases, and take responsibility for the complete PR, including AI-assisted work.
I checked the evidence above, confirmed it supports the current change, and recorded meaningful validation gaps.
I declare this PR ready for initial maintainer review.

_{🔄 This issue represents a GitHub Pull Request. It cannot be merged through Gitea due to API limitations.}

## 📋 Pull Request Information **Original PR:** https://github.com/morluto/rea/pull/2124 **Author:** [@Zburgers](https://github.com/Zburgers) **Created:** 10/12/2026 **Status:** ❌ Closed **Base:** `main` ← **Head:** `feat/issue-1947-normalized-text-views` --- ### 📝 Commits (10+) - [`f16537b`](https://github.com/morluto/rea/commit/f16537b0f048fc1cf71cb650ee2c61b359fcb56d) feat(domain): add opt-in address-normalized function text views - [`f192686`](https://github.com/morluto/rea/commit/f1926869cb731c9097863ee7ba4094f1eb1b9c08) fix(domain): preserve literals in normalized function views - [`d476f11`](https://github.com/morluto/rea/commit/d476f119632cfafe233c6a9c44c38348d5ae81a7) fix(domain): preserve normalized view semantics - [`4e8fbb0`](https://github.com/morluto/rea/commit/4e8fbb043f5480e7ac15405cb4e6f4c19517194f) test(domain): reflect unresolved normalized callees - [`40a778c`](https://github.com/morluto/rea/commit/40a778cfd369278e3d30a2d67de8be6b82ad4778) fix(domain): preserve address space operands in normalized views - [`ce3504d`](https://github.com/morluto/rea/commit/ce3504d94ca0bb2517ee3dbf843b0932f26e58d3) test(javascript): align parameter provenance expectation - [`eba5ed9`](https://github.com/morluto/rea/commit/eba5ed9c3b626fe71bdbacff27b942314147ad7e) test(ci): accept reusable release workflow jobs - [`bfddccd`](https://github.com/morluto/rea/commit/bfddccdcaa7c0ad6dd672666f50440c09bc52e1a) fix: reconcile main and review findings for PR #2124 - [`8cbdee8`](https://github.com/morluto/rea/commit/8cbdee87f7805622d61ec9b85cc6c91e7a6931c4) fix(comparison): preserve indirect operands and normalized unknown scopes - [`e036ba0`](https://github.com/morluto/rea/commit/e036ba0142a03a1cd8a1addb5d5dba2d6ee0efb3) fix(comparison): preserve direct branch comments and captured main contracts ### 📊 Changes **23 files changed** (+4214 additions, -70 deletions) <details> <summary>View changed files</summary> 📝 `.agents/skills/reverse-engineer-anything/references/evidence-workflows.md` (+9 -1) 📝 `docs/mcp-contracts.md` (+11 -0) 📝 `src/contracts/sessionToolContracts.ts` (+1 -1) 📝 `src/domain/changedBehavior.ts` (+6 -2) 📝 `src/domain/functionComparison.ts` (+18 -0) ➕ `src/domain/functionComparisonAddressProjection.ts` (+251 -0) 📝 `src/domain/functionComparisonDimensions.ts` (+3 -3) 📝 `src/domain/functionComparisonNormalization.ts` (+2 -1) ➕ `src/domain/functionComparisonNormalizedViews.fixture.ts` (+1677 -0) ➕ `src/domain/functionComparisonNormalizedViews.test.ts` (+1208 -0) ➕ `src/domain/functionComparisonNormalizedViews.ts` (+317 -0) 📝 `src/domain/functionComparisonResults.ts` (+10 -0) 📝 `src/domain/functionComparisonSchemas.ts` (+111 -2) ➕ `src/domain/functionComparisonTextParsing.ts` (+327 -0) 📝 `src/domain/javascript/javascriptSemanticAnalysis.require_links.test.ts` (+16 -0) 📝 `src/domain/reconstructionVerification.ts` (+23 -13) 📝 `src/domain/reconstructionVerificationSchemas.ts` (+6 -8) 📝 `src/domain/residualUnknown.test.ts` (+17 -0) 📝 `src/domain/residualUnknown.ts` (+9 -2) 📝 `src/domain/staticRuntimeCorrelation.ts` (+23 -14) _...and 3 more files_ </details> ### 📄 Description ## Summary Exact function pseudocode and assembly can change when only addresses move. This adds opt-in, separate address-normalized text views to `compare_functions`, preserving the eight exact dimensions, their digests, summary counts, and overall status. Refs #1947. ## Contract and normalization - `include_normalized_views: true` adds `pseudocode_normalized` and `assembly_normalized`, each with status, digests, text delta, masking rules/counts, limitations, and both source Evidence links. Omitting the option preserves the existing result and Evidence parameters. - Recognized address-derived identifiers require corroborating dossier facts and retain their provider-label prefix. Function-local labels and observed instruction/direct-branch addresses retain their exact entry-relative offsets. - External numeric uses require a corroborated direct callee/thunk target or matching instruction-site/operand reference facts. Ambiguous constants, indirect displacements, and named address spaces remain visible. - Quoted literals and comments are preserved. Unsupported raw strings, unfinished text, unavailable facets, incompatible providers, or an exceeded diff bound produce explicit `unknown` results. - Ordinals are assigned independently per side. Equal projected text does not establish target identity or call order. If equal text masks a callee or the procedure's own thunk target while exact `calls` is unknown, the normalized view is also unknown. - Normalized dimensions work in reconstruction claims, residual-unknown scopes, and static/runtime selectors. Consumers retain the selected limitations and validate every exact/normalized finding against the comparison's Evidence closure using shared domain helpers. - Assembly operand boundaries and occurrence counts are parsed once per touched line, with only the current line retained. Address-use counts come from parsed operand facts and exclude comments and quoted text; eight regressions fail on the prior parser and pass with the fix. ## Evidence and validation Current head: `8cde66673`, including `main` at `44d98de23`. Merge conflicts in the comparison consumers and documentation are resolved. Native Windows, Node 24.18.0 / npm 11.16.0: - 271 focused domain tests passed, including normalization, exact comparison, reconstruction/source coverage, correlation, changed behavior, and residual unknowns. - 10 compiled MCP boundary tests passed. - The inherited Source tests failure (#3341) is reconciled with `main`'s lexical-binding fix. Both explicit CommonJS and explicit-module controls pass; the superseded test expectation is removed. - `npm run check`, `npm run docs:check` (including five README consistency tests), build, push checks, and `git diff --check` passed. - Regressions cover literals/comments, changed constants/offsets, ambiguous operands, changed/swapped callees, own-function thunks, unavailable facets, provenance closure, normalized questions, and long imported assembly lines. - Completed comparisons with 1,000 numeric operands improved from roughly 1.0–1.4 seconds to 9–17 ms in warm runs; serialized results and token estimates were identical. Cold/warm elapsed time, CPU, peak memory, and measurement limits are recorded in [the review-thread response](https://github.com/morluto/rea/pull/2124#discussion_r4269643968). [Real Ghidra 12.1.4 verification at this head](https://github.com/morluto/rea/pull/2124#issuecomment-6168685446) completed 24 compare-pairs and 3 Wallace comparisons on Windows 10 x64. Constant edits were detected in all 8 normalized views. Changed-call cases produced 3 changed and 5 unknown views, with zero false unchanged views, including the x64 -O2 thunk. Wallace matched expectations. Relocation-only coverage is limited: 4/12 function comparisons remain unchanged and 8/12 are unknown in both views. Unknown means equality could not be established, not that a change was detected. These are fixture-specific results. No fresh IDA, Hopper, or Linux provider run is claimed. Current-head CI test lanes passed. ## Remaining limits Caller dossiers contain callee identities and thunk targets, not callee bodies or cross-build correspondence evidence. [Callee matching is tracked separately in #3506](https://github.com/morluto/rea/issues/3506), following [Pablo's recommendation](https://github.com/morluto/rea/issues/1947#issuecomment-6169243713): shared tokens should represent supported callee matches, with complete callee Evidence, thunk handling, and explicit ambiguity checks. Unmatched callees remain unknown under the current policy. A normalized body digest alone is not proof of procedure identity. No provider reads, target execution, installation, or new persistence are added. Provider startup, transport/schema advertisement, and complete agent-task costs were not measured. ## Author readiness Human owner: @Zburgers - [x] I reviewed the final diff and relevant existing code, understand the change and its edge cases, and take responsibility for the complete PR, including AI-assisted work. - [x] I checked the evidence above, confirmed it supports the current change, and recorded meaningful validation gaps. - [x] I declare this PR ready for initial maintainer review. --- <sub>🔄 This issue represents a GitHub Pull Request. It cannot be merged through Gitea due to API limitations.</sub>

bsakaguchi

2026-10-31 01:00:24 +00:00

closed this issue
added the
pull-request
label

bsakaguchi referenced this issue

2026-11-01 21:42:50 +00:00

[PR #5045] [CLOSED] fix(setup): admit only strict JSON for Claude Desktop configuration #6757

No milestone

No project

No assignees

1 participant

Notifications

Due date

The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Dependencies

No dependencies set.

Reference

morluto/rea#5045

No description provided.

Rows
Columns