[PR #3976] feat(go)!: inspect compiler-declared function entries #5979

Open
opened 2026-10-31 01:10:54 +00:00 by bsakaguchi · 0 comments
Owner

📋 Pull Request Information

Original PR: https://github.com/morluto/rea/pull/3976
Author: @rancy777
Created: 10/15/2026
Status: 🔄 Open

Base: main ← Head: codex/go-function-table


📝 Commits (1)

  • 3d6011c feat(go)!: inspect compiler-declared function entries

📊 Changes

18 files changed (+931 additions, -18 deletions)

View changed files

📝 docs/go-binaries.md (+47 -2)
📝 scripts/verify-go-binary.mjs (+63 -3)
📝 src/application/go/GoBinaryService.test.ts (+8 -0)
📝 src/application/go/GoBinaryService.ts (+18 -1)
📝 src/cli/goCommands.ts (+18 -3)
📝 src/contracts/go/goToolContracts.ts (+1 -1)
📝 src/domain/go/goBinary.ts (+73 -0)
➕ src/domain/go/goFunctionTable.ts (+44 -0)
📝 src/go/GoBinaryContainer.ts (+2 -0)
📝 src/go/GoBinaryImage.ts (+19 -2)
📝 src/go/GoBinaryProvider.ts (+20 -4)
📝 src/go/GoElfImage.ts (+8 -1)
➕ src/go/GoFunctionTable.ts (+294 -0)
📝 src/go/GoMachoImage.ts (+2 -0)
📝 src/go/GoPeImage.ts (+5 -1)
📝 tests/acceptance/goBinaryCli.test.ts (+53 -0)
➕ tests/boundary/go/goFunctionTable.test.ts (+212 -0)
➕ tests/fixtures/go/functions.ts (+44 -0)

📄 Description

Summary

Go inspection currently reports build metadata but cannot answer which compiler-declared functions remain in a stripped executable. Add opt-in function names, entry addresses and verified file offsets through the existing CLI/MCP workflow.

Problem and expected behavior

rea inspect-go-binary app --functions --json and MCP inspect_go_binary with functions: true should return artifact-bound function-table observations. Ordinary build-info requests should avoid function-table work and output. This is a standalone enhancement; no issue is linked.

Change and scope

Decode the Go 1.20 pclntab layout in ELF64 little-endian amd64 ET_EXEC images with unique, file-backed .gopclntab and .text sections. Validate ranges, ordering, record agreement, UTF-8 names and load mappings. Use the .text section address, as debug/gosym does; preserve the table header's separate declared text base, which is zero in the tested Go 1.27 binaries.

Function coverage is not-requested, complete for the examined table, or explicitly unavailable. Malformed function metadata preserves independently readable build info. Byte, representation and mapping-work budgets fail without partial success. No adjacent-entry function sizes, source mappings, types or inline-function recovery are claimed.

Contract and boundary impact

  • Semantic owner: container readers own section addresses and ELF type; GoFunctionTable owns decoding; domain contracts and the existing service carry facts to both adapters.
  • Scope: general static format inspection within the existing Go provider. A separate execution/injection/mutation/protection-recovery scope decision is not applicable.
  • CLI/MCP: optional --functions / functions: true; required functions coverage in normalized reports. Existing tool identity and count stay unchanged.
  • Formats: function entries cover the boundary above. PIE, sectionless images, PE/Mach-O functions, other architectures and layouts remain unavailable; build-info support is retained.
  • Evidence: original artifact SHA-256, table range, each row/record/name range and mapped entry offset. Names are observed compiler metadata, not authenticated behavior.
  • Authority: reads only the selected stable local file; no target execution, subprocess, temporary-file or network authority added to inspection. Verification separately runs Go and trusted test-owned oracle helpers, never fixture executables.
  • Packaging: no dependencies, binaries, build outputs or version changes. Ignored catalogs are generated and checked locally/CI.

Expected production effects:

  • Read existing files or captured data.
  • Launch or attach to a process.
  • Inject instrumentation or run scripts/code.
  • Change process memory, registers, files, or configuration.
  • Contact network services.
  • Recover protected code or work around protections.
  • Documentation or usability only; no target interaction.
  • Not sure yet; investigation or maintainer guidance needed.

Evidence and regression coverage

  • Added authored, nonexecutable ELF fixtures and coverage for Unicode names, malformed tables, conflicting mappings, invalid UTF-8, resource exhaustion and opt-in selection. Shared CLI/MCP tests verify matching Evidence and advertised schema validity.

  • Go 1.27.0 producer verification passed on Windows: 14 compiler-built/derived images, 28 public CLI/MCP cases across Linux, Windows and Darwin targets. Supported normal/stripped Linux amd64 samples matched all 1,797 function names, addresses and mapped offsets against debug/elf + debug/gosym; unsupported cases reported unavailable coverage.

  • Two additional normal/stripped Linux amd64 samples matched all 1,642 entries against an independent standard-library helper; inputs remained unchanged and MCP ping succeeded afterward.

  • Representative function observation: {"name":"main.加法","entry_address":"0x10600","file_offset":1536} in the authored fixture, alongside exact table-row, record and name-source coordinates.

  • Task-selection measurement on the same real sample: default CLI JSON 3,757 UTF-8 bytes versus 308,631 bytes with 1,642 entries. Two fresh-process runs were 848-863 ms / 816-866 ms respectively. OS cache was uncontrolled; this is no speedup or token-saving claim. Model tokens, process-family CPU and peak memory were not measured.

  • Observed, derived, and inferred claims remain distinguishable.

  • Artifact identity, source provenance, and failed attempts remain preserved.

  • Unsupported, incomplete, unavailable, or uncertain outcomes remain visible.

Validation performed

Executed with Node 24.18.0 and npm 11.16.0:

  • npm run build:cached - passed.
  • Focused Vitest Go boundary, Go service, MCP and CLI suites - 180 passed, 3 Windows skips.
  • Rust image/auditable-reader regressions for the shared container reader - 27 passed.
  • npm run check - passed (typecheck, lint, formatting, knip, metadata and architecture guards).
  • npm run docs:check - passed.
  • npm run verify:test-discovery - all 1,318 test files discovered exactly once.
  • node scripts/verify-go-binary.mjs with the absolute local Go command - passed, 14 images / 28 public cases. Matching published 6.5.0 Windows native controls were restored in an ignored directory and verified before this run; they are excluded from the commit.

Compatibility, safety, and release

  • Breaking output contract: reports and saved Evidence now require functions. Previously valid reports omitting it fail strict validation; re-inspect the artifact to obtain current Evidence. Old reports cannot establish requested function coverage, so no compatibility decoder is added. Existing calls without the flag remain valid and produce not-requested coverage.
  • Only Go 1.27.0 producer samples were verified; sharing Go 1.20's layout does not establish every release's coverage. No Hopper/Ghidra integration is changed or claimed.
  • Windows cannot preserve arbitrary non-UTF-8 argv bytes, so that compiler-produced verification case remains omitted; authored byte-string regressions pass. The Windows verifier cannot establish process-family lineage without a retained Job Object lease and reports that limitation explicitly. Full repository tests were not run.
  • Bounded static inspection adds no target-execution or protection-bypass workflow. No DLL, native component or generated output is included.

Author readiness

Human owner: @rancy777

  • 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.

Before merge

  • This PR addresses a concrete problem or an agreed enhancement.
  • Material scope and authority questions are resolved, and any required maintainer scope decision covers the final diff.
  • The PR has one focused outcome and the title follows type(scope): outcome.
  • Related issue is linked, or the reason for not linking one is stated above.
  • Tests cover changed observable behavior and meaningful failure paths.
  • Owning docs, contracts, and generated metadata are updated where needed.
  • User-visible CLI/MCP changes include representative output.
  • I checked the final diff for secrets, unrelated cleanup, and unsupported claims.

🔄 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/3976 **Author:** [@rancy777](https://github.com/rancy777) **Created:** 10/15/2026 **Status:** 🔄 Open **Base:** `main` ← **Head:** `codex/go-function-table` --- ### 📝 Commits (1) - [`3d6011c`](https://github.com/morluto/rea/commit/3d6011c2385b044eae073b45d0fc1529696dfd47) feat(go)!: inspect compiler-declared function entries ### 📊 Changes **18 files changed** (+931 additions, -18 deletions) <details> <summary>View changed files</summary> 📝 `docs/go-binaries.md` (+47 -2) 📝 `scripts/verify-go-binary.mjs` (+63 -3) 📝 `src/application/go/GoBinaryService.test.ts` (+8 -0) 📝 `src/application/go/GoBinaryService.ts` (+18 -1) 📝 `src/cli/goCommands.ts` (+18 -3) 📝 `src/contracts/go/goToolContracts.ts` (+1 -1) 📝 `src/domain/go/goBinary.ts` (+73 -0) ➕ `src/domain/go/goFunctionTable.ts` (+44 -0) 📝 `src/go/GoBinaryContainer.ts` (+2 -0) 📝 `src/go/GoBinaryImage.ts` (+19 -2) 📝 `src/go/GoBinaryProvider.ts` (+20 -4) 📝 `src/go/GoElfImage.ts` (+8 -1) ➕ `src/go/GoFunctionTable.ts` (+294 -0) 📝 `src/go/GoMachoImage.ts` (+2 -0) 📝 `src/go/GoPeImage.ts` (+5 -1) 📝 `tests/acceptance/goBinaryCli.test.ts` (+53 -0) ➕ `tests/boundary/go/goFunctionTable.test.ts` (+212 -0) ➕ `tests/fixtures/go/functions.ts` (+44 -0) </details> ### 📄 Description ## Summary Go inspection currently reports build metadata but cannot answer which compiler-declared functions remain in a stripped executable. Add opt-in function names, entry addresses and verified file offsets through the existing CLI/MCP workflow. ## Problem and expected behavior `rea inspect-go-binary app --functions --json` and MCP `inspect_go_binary` with `functions: true` should return artifact-bound function-table observations. Ordinary build-info requests should avoid function-table work and output. This is a standalone enhancement; no issue is linked. ## Change and scope Decode the Go 1.20 pclntab layout in ELF64 little-endian amd64 `ET_EXEC` images with unique, file-backed `.gopclntab` and `.text` sections. Validate ranges, ordering, record agreement, UTF-8 names and load mappings. Use the `.text` section address, as `debug/gosym` does; preserve the table header's separate declared text base, which is zero in the tested Go 1.27 binaries. Function coverage is `not-requested`, `complete` for the examined table, or explicitly `unavailable`. Malformed function metadata preserves independently readable build info. Byte, representation and mapping-work budgets fail without partial success. No adjacent-entry function sizes, source mappings, types or inline-function recovery are claimed. ## Contract and boundary impact - Semantic owner: container readers own section addresses and ELF type; `GoFunctionTable` owns decoding; domain contracts and the existing service carry facts to both adapters. - Scope: general static format inspection within the existing Go provider. A separate execution/injection/mutation/protection-recovery scope decision is not applicable. - CLI/MCP: optional `--functions` / `functions: true`; required `functions` coverage in normalized reports. Existing tool identity and count stay unchanged. - Formats: function entries cover the boundary above. PIE, sectionless images, PE/Mach-O functions, other architectures and layouts remain unavailable; build-info support is retained. - Evidence: original artifact SHA-256, table range, each row/record/name range and mapped entry offset. Names are observed compiler metadata, not authenticated behavior. - Authority: reads only the selected stable local file; no target execution, subprocess, temporary-file or network authority added to inspection. Verification separately runs Go and trusted test-owned oracle helpers, never fixture executables. - Packaging: no dependencies, binaries, build outputs or version changes. Ignored catalogs are generated and checked locally/CI. Expected production effects: - [x] Read existing files or captured data. - [ ] Launch or attach to a process. - [ ] Inject instrumentation or run scripts/code. - [ ] Change process memory, registers, files, or configuration. - [ ] Contact network services. - [ ] Recover protected code or work around protections. - [ ] Documentation or usability only; no target interaction. - [ ] Not sure yet; investigation or maintainer guidance needed. ## Evidence and regression coverage - Added authored, nonexecutable ELF fixtures and coverage for Unicode names, malformed tables, conflicting mappings, invalid UTF-8, resource exhaustion and opt-in selection. Shared CLI/MCP tests verify matching Evidence and advertised schema validity. - Go 1.27.0 producer verification passed on Windows: 14 compiler-built/derived images, 28 public CLI/MCP cases across Linux, Windows and Darwin targets. Supported normal/stripped Linux amd64 samples matched all 1,797 function names, addresses and mapped offsets against `debug/elf` + `debug/gosym`; unsupported cases reported unavailable coverage. - Two additional normal/stripped Linux amd64 samples matched all 1,642 entries against an independent standard-library helper; inputs remained unchanged and MCP ping succeeded afterward. - Representative function observation: `{"name":"main.加法","entry_address":"0x10600","file_offset":1536}` in the authored fixture, alongside exact table-row, record and name-source coordinates. - Task-selection measurement on the same real sample: default CLI JSON 3,757 UTF-8 bytes versus 308,631 bytes with 1,642 entries. Two fresh-process runs were 848-863 ms / 816-866 ms respectively. OS cache was uncontrolled; this is no speedup or token-saving claim. Model tokens, process-family CPU and peak memory were not measured. - [x] Observed, derived, and inferred claims remain distinguishable. - [x] Artifact identity, source provenance, and failed attempts remain preserved. - [x] Unsupported, incomplete, unavailable, or uncertain outcomes remain visible. ## Validation performed Executed with Node 24.18.0 and npm 11.16.0: - `npm run build:cached` - passed. - Focused Vitest Go boundary, Go service, MCP and CLI suites - 180 passed, 3 Windows skips. - Rust image/auditable-reader regressions for the shared container reader - 27 passed. - `npm run check` - passed (typecheck, lint, formatting, knip, metadata and architecture guards). - `npm run docs:check` - passed. - `npm run verify:test-discovery` - all 1,318 test files discovered exactly once. - `node scripts/verify-go-binary.mjs` with the absolute local Go command - passed, 14 images / 28 public cases. Matching published 6.5.0 Windows native controls were restored in an ignored directory and verified before this run; they are excluded from the commit. ## Compatibility, safety, and release - **Breaking output contract:** reports and saved Evidence now require `functions`. Previously valid reports omitting it fail strict validation; re-inspect the artifact to obtain current Evidence. Old reports cannot establish requested function coverage, so no compatibility decoder is added. Existing calls without the flag remain valid and produce `not-requested` coverage. - Only Go 1.27.0 producer samples were verified; sharing Go 1.20's layout does not establish every release's coverage. No Hopper/Ghidra integration is changed or claimed. - Windows cannot preserve arbitrary non-UTF-8 argv bytes, so that compiler-produced verification case remains omitted; authored byte-string regressions pass. The Windows verifier cannot establish process-family lineage without a retained Job Object lease and reports that limitation explicitly. Full repository tests were not run. - Bounded static inspection adds no target-execution or protection-bypass workflow. No DLL, native component or generated output is included. ## Author readiness Human owner: @rancy777 - [ ] 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. ## Before merge - [ ] This PR addresses a concrete problem or an agreed enhancement. - [ ] Material scope and authority questions are resolved, and any required maintainer scope decision covers the final diff. - [ ] The PR has one focused outcome and the title follows `type(scope): outcome`. - [ ] Related issue is linked, or the reason for not linking one is stated above. - [ ] Tests cover changed observable behavior and meaningful failure paths. - [ ] Owning docs, contracts, and generated metadata are updated where needed. - [ ] User-visible CLI/MCP changes include representative output. - [ ] I checked the final diff for secrets, unrelated cleanup, and unsupported claims. --- <sub>🔄 This issue represents a GitHub Pull Request. It cannot be merged through Gitea due to API limitations.</sub>
Sign in to join this conversation.
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#5979
No description provided.