* fix(erlang): disclose BEAM bytes trailing the declared FOR1 form A conformant FOR1 container sizes its form to the whole file, so bytes past the form end are an unexamined appended or corrupt region. The inspector decoded chunks only within the form but still reported coverage.status "complete" with no mention of the surplus, so a caller could not distinguish a clean BEAM from one carrying foreign trailing bytes. Compute the trailing byte count, report coverage.status "partial" with a trailing_bytes field, and append a limitation naming the form end and the unexamined count. Clean containers stay "complete" with trailing_bytes 0. * fix(erlang): reparse retained BEAM Evidence without the trailing-bytes field Evidence retained by a build predating coverage.trailing_bytes has no such property, and projectErlangBeamView reparses that record with the strict erlangBeamSchema. A required field rejected those records with an input error before any summary or page could render, breaking the offline retained-Evidence flow even for clean files. Default coverage.trailing_bytes to 0 so historical records reparse while every new parse still emits the concrete count and preserves each record's stored status. * fix(erlang): keep retained BEAM trailing coverage unknown, not zero Defaulting coverage.trailing_bytes to 0 manufactured a "no trailer" reading for Evidence retained before the field existed, even when its retained bounds (artifact.bytes versus form.location.bytes) prove a trailer. Make the field optional so a pre-field record reparses as unknown instead of a fabricated zero, while every new parse still emits the concrete count. * fix(erlang): admit chunk extents before applying count limits * docs(erlang): explain trailing BEAM coverage --------- Co-authored-by: morluto <76467478+morluto@users.noreply.github.com>
6.6 KiB
Erlang BEAM files
inspect_erlang_beam / inspect-erlang-beam answers whether one selected
local file is a FOR1/BEAM IFF container, which chunks that form stores, and
which atom, export, import, lambda, and Code-header fields those chunks carry.
It reads the file without executing bytecode and does not require an Erlang
installation or BEAM emulator.
rea inspect-erlang-beam /absolute/path/to/app.beam --json
The CLI resolves relative paths against the caller's working directory. MCP requires an absolute filesystem path and preserves that exact selection:
{
"name": "inspect_erlang_beam",
"arguments": { "path": "/artifacts/app.beam" }
}
Observations
The inline Evidence result contains the artifact path, SHA-256, and byte length.
chunks lists every IFF chunk name, file range, and payload SHA-256.
Repeated names retain separate chunk occurrences. Decoded tables and the Code
header use the last occurrence of each name, matching OTP's loader; the chunk
inventory still exposes earlier payloads and their source ranges.
The BEAM form size bounds the parsed chunks. Bytes after the form remain part
of the artifact's byte length and SHA-256. They are unexamined by the chunk
reader, so the report sets coverage.status to partial and gives their exact
count in coverage.trailing_bytes. Older retained Evidence may omit the count.
When a selected AtU8 or Atom table is decoded, atoms is the 1-based name table and
module is atom 1. Both the pre-OTP 28 table and the OTP 28+ compact table
(negated count, compact-encoded name lengths) are read. exports, imports, and lambdas resolve atom indices to
those names when the table is present; unresolved indices keep function or
module null.
code reports the Code chunk instruction-set, opcode maximum, label count,
function count, and the instruction stream's file range. Missing optional
tables are null, not empty-everywhere.
A zero-byte AtU8 falls back to an available legacy Atom table, following
OTP 20.3's atom selection.
A nonempty AtU8 retains UTF-8 precedence, including an explicit zero atom
count; malformed nonempty data fails instead of falling back. An empty atom
chunk without an alternate table still fails its required count header.
Absent and zero-byte optional FunT chunks produce lambdas: null, while a
four-byte zero row count produces lambdas: []. This follows
OTP 29's positive-size lambda parsing rule.
Empty payloads retain their ranges and SHA-256 in the chunk inventory. These
rules apply to the last occurrence of each chunk name; an empty final occurrence
does not revive an earlier payload of that name. Nonempty truncated tables remain
format failures.
Select retained facts
Complete output remains the default. Request a summary with a beam view to
read a few facts in the first call while retaining the complete inspection:
{
"name": "inspect_erlang_beam",
"arguments": {
"path": "/artifacts/app.beam",
"detail": "summary",
"view": {
"kind": "beam",
"collection": "exports",
"names": ["module_info"],
"fields": ["function_index", "function", "arity", "label"],
"limit": 20
}
}
}
normalized_result.page.items contains the matching rows. source_index is
zero-based in the original collection and scoped to parent_evidence_id and
that collection. It does not replace the original one-based atom index or a
lambda's own index. Every matching function name survives, including different
arities. Names are exact retained display strings; raw indexes remain available
when names are unresolved or displayed names collide.
Collections are atoms, exports, imports, lambdas, and chunks. names
selects atom/chunk names or function names; imports additionally support exact
modules. Filters intersect. indices selects original collection indexes;
fields selects that collection's own fields. Empty selector arrays match
nothing, and fields: [] returns only source_index. Offset/limit page matching
rows in original order (defaults 0/64). Unfiltered pages slice the retained
collection; queries do not decode the file again.
For chunks, names matches the four-character IFF chunk tag (for example
"AtU8", "Code", "ExpT"); available fields are index, name,
location, and payload. For lambdas, names matches the resolved function
name from the atom table; null names (unresolved atom indices) are never
selected by a name filter. For atoms, names matches the decoded atom name
string.
beam keeps the module, form/Code bounds, original source coverage, and table
counts. A null count means no table was decoded; zero means a decoded empty
table. Missing tables and unresolved atom names remain explicit, and an empty
page does not establish runtime absence. Page coverage is separate from the
source's examined chunks and parser budgets.
CLI summary delivery requires a destination for the complete Evidence bundle:
rea inspect-erlang-beam /artifacts/app.beam --detail summary \
--view '{"kind":"beam","collection":"exports","names":["module_info"],"fields":["function","arity"]}' \
--evidence_output /reports/app-beam.evidence.json --json
rea inspect-analysis-view '{"source":{"kind":"evidence-file","path":"/reports/app-beam.evidence.json"},"view":{"kind":"beam","collection":"imports","modules":["erlang"]}}' --json
The bundle retains the complete report. Subsequent MCP queries may use
source: {kind: "retained-evidence", evidence_id: parent_evidence_id} or an
Evidence file. Retained and offline views still work after the original BEAM
file is deleted. Supplying view requires detail: "summary"; omitting it
returns only the structural summary. Selection changes delivery, not parsing or
coverage, and executes no bytecode.
Limits and failures
The selected file is limited to 64 MiB by default (512 MiB maximum). At most
64 chunks and 4096 atoms are examined by default, and at most 65536 export,
import, and lambda rows together. Malformed FOR1/BEAM headers, truncated
chunks, and AtU8 names that are not valid UTF-8 fail without partial success.
The reader checks each encountered chunk's payload and alignment padding against
the declared form before applying the chunk count limit.
This workflow does not execute bytecode, inflate LitT literals, or decode
Attr/CInf external-term payloads. Complete coverage describes this static
chunk and table report; it does not establish that an Erlang runtime can load
or execute the module.