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