Files
reverse-engineering-anything/docs/bun-standalone.md
T
morlutoandCursor Agent e532d746f0 docs(limits): refresh the limit inventory and state the runtime-setting rule (#12655)
* docs(limits): refresh the limit inventory and state the runtime-setting rule

Recompute the inventory from ANALYSIS_SETTINGS and the numeric-limit
check, and make a hardcoded limit a runtime setting unless a fixed
ceiling has a stated format, protocol, or representation reason.

* docs(limits): distinguish runtime settings from per-call overrides

---------

Co-authored-by: Cursor Agent <cursoragent@cursor.com>
2026-11-20 01:43:07 +00:00

6.6 KiB

Bun standalone executables

inspect-artifact inventories embedded Bun module graphs in Mach-O __BUN,__bun, PE .bun, ELF .bun, and appended trailers. extract-artifact writes their stored module contents through the existing safe output tree. Neither operation executes the executable or decompiles bytecode.

rea inspect-artifact ./hello --json
rea extract-artifact ./hello --json

In MCP, open the executable with open_binary, then call inspect_artifact. Use detail: "summary" for large graphs and inspect_analysis_view to page retained Evidence. The root metadata's entry_point_logical_path is the reader-owned location of its entry module. Use it as an inventory logical_paths filter, then read selected node fields with the returned content identity. This also works for names mapped to indexed extraction paths. The complete Evidence stays retained; no source-name normalization is needed in the caller.

The root reports the carrier, layout, module count, entry point, raw flags and compile exec-argv. Each module retains its source name, loader and encoding values, entry-point status, sizes and SHA-256. Sourcemaps, bytecode and module-info regions are separate children. Source names such as /$bunfs/root/main.js remain in metadata; extraction uses a relative path. Unsafe or non-UTF-8 names receive an indexed path and retain their source spelling or bytes. Virtual names deeper than the selected path_parts allowance (default 256) also use an indexed path with an explicit limitation, preventing unbounded path-tree work while retaining the source fact. Duplicate names remain separate occurrences; ordinary extraction collision rules apply.

The recognized record shapes are the 36-byte Bun 1.3.3 layout and the 52-byte Bun 1.3.9 layout. These labels identify structural layouts, not a detected compiler version. Bun does not store an explicit revision identifier: unknown table sizes and ambiguous known layouts are unsupported. A future layout that is byte-for-byte compatible cannot be distinguished. Invalid pointers and truncated claimed sections are malformed. A named Mach-O section is also malformed when it declares zero-fill or falls outside its containing segment's file or virtual address range. A confirmed section graph requires a complete Mach-O load command table. An absent trailer without a named section does not establish a Bun graph. Unknown enum values remain raw, with a null name.

Sourcemaps are stored Bun regions, not necessarily standalone JSON source maps. Extracted contents retain their original encoding. Use JavaScript analysis only on compatible source files; bytecode is retained as evidence, not decoded.

Module parsing reads exact metadata ranges rather than loading stored asset bodies or whole pages around small pointers. A cache retains at most 256 KiB and 1,024 ranges for one reader preparation. Cumulative uncached metadata reads default to 256 MiB, checked before allocation or I/O. The module table, decoded strings and combined logical path tree have separate admission checks; by default at most 250,000 distinct path prefixes are admitted before inventory construction. Stored bodies are range-streamed for hashing and extraction. Header/suffix observations are reused only for the same admitted file state, with selected-path checks before publication.

Both artifact operations accept artifact_limits.bun. Its independent controls are payload_bytes, module_count, representation_bytes, metadata_read_bytes, recognition_table_bytes, recognition_load_command_bytes, path_parts and path_nodes. Failed recognition remains explicitly limited instead of proving absence. ELF section names are examined at their actual offsets, including names beyond a large section-name prefix. Select artifact_limits.expanded_bytes to change the aggregate referenced-plaintext work allowance. The reader validates the graph extent and suffix before applying payload_bytes. A declared extent outside its carrier or a suffix count that disagrees with the located payload is a format error.

For a reported metadata-read refusal, keep the same carrier and retry with --artifact-limits '{"bun":{"metadata_read_bytes":536870912}}' or the equivalent MCP artifact_limits object. Omitted fields keep defaults. The response names the effective limit and exact repair; accepted overrides are reported separately from caller selections. Changes apply on the next call without restarting REA. Summary and selected extraction do not change the producer's admission.

Module-graph admission ceilings are in Bun standalone module graphs. Shared artifact-reader admission stays in limits and recovery. Synthetic tests cover the carriers and malformed declarations. Run node scripts/verify-bun-standalone.mjs after npm run build:cached for local Bun verification, and add --docker to compile a Linux fixture with oven/bun:1.4.0. Bun and Docker are fixture producers only and are not installed by REA.

Layout references: Bun 1.3.3 serializer and Bun 1.3.9 serializer.

The current 52-byte record order can also be checked in the Bun 1.4.4 Rust serializer.

Bun standalone module graphs

inspect_artifact and extract_artifact accept per-call artifact_limits. The bun group defaults to 100,000 modules, independent 256 MiB payload, retained-representation and physical metadata-read allowances, 256 path parts and 250,000 logical path nodes. Recognition separately admits a 1 MiB ELF section table and 16 MiB Mach-O load commands. Exhausted recognition remains unknown rather than proving the carrier has no Bun graph. Inventory preserves native-root facts or another confirmed pack and reports the exact unexamined alternative inline; it does not assert Bun presence. ELF section names are examined with exact bounded reads, including names beyond the former prefix window.

For example, keep the same complete carrier and retry a reported recognition limitation with {"artifact_limits":{"bun":{"recognition_table_bytes":2097152}}}. The CLI spelling is --artifact-limits '{"bun":{"recognition_table_bytes":2097152}}'. No REA restart is needed. A smaller later selection is re-admitted; previously parsed facts cannot bypass it. The 256 KiB / 1,024-entry exact-range cache avoids full-page amplification and remains an internal optimization, not an agent resource setting. Shared logical path prefixes count once before nodes are added.