Femtobun

Femtobun is a small programming-language experiment built for software agents. Its programs are compact typed graphs with stable numeric IDs, deterministic binary encoding, checked patches, explicit resource contracts, and native lowering through Clang. JSON exists as an inspection format, but formatting and key order carry no meaning.

Version 0.7 adds an agent-written intent source. A complete supported program is one canonical line such as checked_sum 1048576. The compiler generates the typed graph, stable IDs, interface, safety contract, and optimized native lowering. The agent writes application semantics rather than compiler bookkeeping.

Version 0.6 adds compiler-owned edit capsules. An agent receives one editable field, its current value, its domain, and its consumers, then replies with one integer. The compiler expands that response into the base hash, compare-and-swap operation, touch envelope, unchanged-node list, interface assertion, resource ceilings, and lowering assertion required by the v0.5 transaction verifier.

Version 0.5 adds a machine-discoverable agent interface without changing the four wire formats or generated kernels. Agents can query dependencies and consumers, preview a patch without writing, assert its semantic and resource footprint, receive structured repair hints, and opt into a reversible append-only transaction log.

Version 0.4 adds a checked reduction over caller-owned u64 values:

checked_sum(elements(values))

The result contains a wrapping total and a sticky overflow flag. The 40-byte canonical program performs one input pass, uses no heap memory, and writes two u64 result slots through this ABI:

void kernel(const uint64_t *data, uint64_t len, uint64_t *out);

This program powers Dustbun, a consumer folder-size viewer that runs a 296-byte WebAssembly module in the browser. Dustbun reads file metadata but never opens file contents, uploads a selection, or launches native code at runtime.

The same program also powers Boulderbun, a read-only native macOS large-file scanner. Its comparison build runs generated Femtobun C and a checked Swift loop in one process against the same file-size array, ABI, semantics, iteration counts, and alternating measurement rounds.

Version 0.3 added a practical access-log program. It accepts caller-owned bytes in Apache Common Log Format and produces a fixed summary of request volume, response bytes, malformed records, status classes, and HTTP methods:

clf_reduce(clf_parse(log))

The compiler fuses the graph into one forward parser. The native kernel does not allocate memory, retain visitor data, or create intermediate records. It writes sixteen u64 fields through this ABI:

void kernel(const uint8_t *data, uint64_t len, uint64_t *out);

Measured result

The checked-in v0.3 benchmark analyzes the Internet Traffic Archive's real 205,242,368-byte NASA Kennedy Space Center trace on an Apple M2 Max. Femtobun, C, Rust, and an independent Python oracle agree on all sixteen outputs, including 1,891,674 valid records, 41 malformed records, and 38,695,973,491 known response bytes.

Kernel	In-memory median	Empirical p05 to p95	Relative to C
Femtobun	179.465 ms	176.593 to 214.342 ms	1.1195x
C	200.915 ms	198.233 to 210.556 ms	1.0000x
Rust	208.169 ms	204.787 to 215.542 ms	0.9652x

Femtobun's observed median time was 10.68% lower than C in the in-memory track and 11.36% lower in a separate fresh-process track. The empirical ranges overlap, and this run does not establish statistical significance or general language superiority. All variants scan the complete runtime input and return the same aggregate. Their final machine code differs, but this run does not isolate which code-shape differences caused the timing gap.

The canonical module is 38 bytes. Its generated parser source is 11,914 bytes, its kernel object is 4,064 bytes, and its linked shared-driver executable is 34,408 bytes. These are separate representation layers. Median peak RSS was about 207 MB for all three variants because the measurement includes the 205.2 MB file mapping. Each kernel performs zero dynamic allocations.

bench/clf/README.md explains the grammar, dataset restrictions, method, and limitations. bench/clf/results.json contains 31 in-memory and 31 fresh-process samples per variant, five RSS observations, build commands, hashes, section sizes, and retained disassembly.

Version 0.2 remains as a controlled runtime-buffer comparison. Its Femtobun and C paths compile to the same object bytes and have no meaningful observed speed difference. Version 0 remains as a historical algorithmic-specialization experiment that replaced a range traversal with a closed form. See bench/buffer/README.md and REPORT.md. Version 0.4 preserves the earlier canonical module bytes, hashes, and semantics.

Try the Dustbun consumer application

Dustbun shows the logical size of a folder, groups space by filename type, and lists the ten largest files. The browser sends only numeric file sizes to Femtobun. Names stay in the interface, contents are never read, and the loopback server exposes static files only.

python3 -m unittest discover -s apps/dustbun/tests -v
python3 apps/dustbun/server.py

Open http://127.0.0.1:8766, then choose a folder. The checked-in WebAssembly kernel needs no compiler at runtime. See apps/dustbun/README.md for the exact Femtobun boundary, artifact hashes, build command, privacy model, and measurement limits.

Compare the native Boulderbun engines

Boulderbun scans any chosen folder, reports its logical size, and ranks the twelve largest regular files. It does not open file contents or offer deletion. The comparison build measures both engines in one process after one folder scan.

cd apps/boulderbun
./build-apps.sh
open ".build/apps/Boulderbun Compare.app"

Choose one folder. The app verifies that both engines return the same checked result, calibrates one shared iteration count, alternates which engine runs first, and reports the median and empirical p05-to-p95 range across nine rounds. See apps/boulderbun/README.md for the exact boundary and interpretation.

Try the Bunlog application

Bunlog turns the v0.3 kernel into a local tool. Choose or drop an Apache Common Log Format file to see request totals, response bytes, malformed lines, status classes, and method counts. Femtobun-only mode performs one practical analysis. Comparison mode runs Femtobun, C, and Rust against the same upload, rejects any aggregate mismatch, and reports calibrated time per pass and throughput.

python3 -m unittest discover -s app/tests -v
python3 app/server.py

Open http://127.0.0.1:8765 in a browser. The server binds only to IPv4 loopback, accepts one streamed upload at a time, rejects files above 256 MiB before reading the body, and launches every native build and call through sandbox/run. It returns only allowlisted aggregates and removes the temporary upload before reporting success. See app/README.md for the privacy boundary, toolchain requirements, and crash-recovery behavior.

Why agents get a different interface

Agents can create programs from compact intent source or address existing semantic objects directly. The compiler owns graph structure and safety bookkeeping in both paths.

• Canonical .fbi intent source describes a complete supported program in one line.
• build SOURCE OUTPUT expands intent into a verified .fbu module.
• source MODULE recovers intent only from an exact compiler-generated expansion.
• Stable numeric IDs identify inputs and graph nodes.
• Canonical .fbu bytes give every valid module one exact SHA-256 identity.
• capabilities describes the accepted IRs, operations, limits, assertions, and commands as JSON.
• query MODULE --node ID returns the transitive dependencies and consumers around one stable ID.
• analyze reports bounds, passes, allocation, complexity, ABI, and selected lowering.
• .fbp.json patches carry an exact base hash and compare-and-swap old values.
• Patch envelopes can freeze the public interface and restrict touched node IDs.
• Patch assertions can require exact changed IDs, unchanged IDs, output hash, schema, effects, resource ceilings, and lowering rule.
• apply --dry-run verifies the complete result and reports impact, contract, resource, and lowering deltas without writing.
• Optional transaction history records exact before and after modules; revert refuses unless the current module is the recorded result.
• diff reports semantic changes by ID instead of comparing formatting.
• Structured errors include stable codes plus repair hints and machine-readable details when available.
• capsule binds one editable value to the current module, and capsule-view emits a small model-facing request.
• apply-capsule accepts only {"v": integer} and reconstructs the complete checked v1 transaction inside the compiler.

The included v1 patch changes parity from even to odd by modifying node 20 only, while asserting that the interface, resource ceiling, effects, lowering rule, and every other stable ID stay unchanged. The tool verifies the complete proposed module before it writes the result. This is a concrete agent-edit protocol, not evidence that Femtobun already wins a controlled agent evaluation.

Historical agent manipulation baseline

The first controlled evaluation now exists. Qwen 2.5 Coder 32B Instruct and Kimi K2.7 Code each attempted two bounded edits in Femtobun, C, and Rust, with one repair allowed and hidden correctness checks.

Language	Passed	First-attempt passes	Mean tokens per trial
Femtobun	3/4	1/4	2,861.5
C	4/4	4/4	428.5
Rust	4/4	4/4	387.5

Femtobun's checked transactions made the permitted change and invariants explicit, but its v0.5 prompt was too large for these tiny edits. The full run cost an estimated $0.022077 across 15 model requests. See bench/agent/README.md for the method and limits, and bench/agent/results.json for the recorded evidence.

Agent-written source result

The v0.7 benchmark starts from an English requirement for the checked folder-size aggregation kernel. It provides no existing source and no edit target. Qwen 2.5 Coder 32B Instruct and Kimi K2.7 Code each generated complete Femtobun, C, and Rust programs. Every language used the same structured response shape and model settings. Hidden checks compiled and executed the result inside sandbox/run.

Language	Passed	First-attempt passes	Mean output tokens	Mean source bytes
Femtobun 0.7	2/2	2/2	14	20
C	2/2	1/2	366	635.5
Rust	2/2	1/2	223.5	423

Against Rust, the cheaper fully successful established-language result, Femtobun used 93.7% fewer model output tokens and 95.3% fewer source bytes. Prompt tokens are reported but excluded from this claim. Femtobun's generated source was checked_sum 1048576;. The parser normalized the optional terminator, generated a 322-byte graph projection and 39-byte module, then emitted and executed a 1,378-byte C kernel with zero declared heap use or dynamic allocations.

This is a real language-level reduction because the agent generated the complete program rather than an edit response. It is also deliberately narrow: checked_sum is a built-in semantic primitive, and the benchmark contains one task and two models. See bench/synthesis/README.md for the controls and limitations, and bench/synthesis/results.json for the responses, token usage, repairs, and hidden-check results.

Safe quick start

The commands in this README assume a source checkout. The wheel contains the femtobun package and fbu command, but not the repository's examples, application, benchmarks, or sandbox scripts.

The verify, run-buffer, and run-bytes commands below do not compile or run native code. The unit-test command skips native tests unless FBU_RUN_NATIVE_TESTS=1 is set:

python3 -m unittest discover -s tests -v
mkdir -p .sandbox-work/run
./fbu build examples/checked_sum.fbi .sandbox-work/run/checked_sum.fbu
./fbu source .sandbox-work/run/checked_sum.fbu
./fbu verify examples/checked_sum.fbu
./fbu run-buffer examples/checked_sum.fbu examples/sample_values.json
./fbu verify examples/clf_summary.fbu
./fbu run-bytes examples/clf_summary.fbu examples/apache_common.log

The numeric sample returns a checked total of 49 with no overflow. The log sample reports one valid GET, one 2xx response, and 2,326 response bytes.

On macOS, run native compilation and calls through the included sandbox:

FBU_RUN_NATIVE_TESTS=1 sandbox/run \
  --python -m unittest discover -s tests -v

Inspect the resource contract and emit reviewed C inside the sandbox:

sandbox/run ./fbu analyze examples/clf_summary.fbu
sandbox/run ./fbu emit-c \
  examples/clf_summary.fbu \
  .sandbox-work/run/clf.c

Apply the stable-ID parity patch:

./fbu capabilities
./fbu query examples/sum_even_squares.fbu --node 20
./fbu apply examples/sum_even_squares.fbu \
  examples/even_to_odd_v1.fbp.json --dry-run
./fbu apply examples/sum_even_squares.fbu \
  examples/even_to_odd_v1.fbp.json \
  .sandbox-work/run/sum_odd_squares.fbu \
  --history .sandbox-work/run/transactions.jsonl
./fbu history .sandbox-work/run/transactions.jsonl

Use the low-token capsule path for the same change:

mkdir -p .sandbox-work/run
./fbu capsule examples/sum_even_squares.fbu \
  --node 20 --field value > .sandbox-work/run/edit.json
./fbu capsule-view .sandbox-work/run/edit.json \
  --request "Set parity to odd."
printf '{"v":1}\n' > .sandbox-work/run/response.json
./fbu apply-capsule examples/sum_even_squares.fbu \
  .sandbox-work/run/edit.json .sandbox-work/run/response.json \
  --dry-run

The capsule file is trusted controller state and must stay outside the model's writable area. Only the compact view goes to the model. The model returns the response file.

Use the transaction_id returned by apply to restore the exact base module:

./fbu revert .sandbox-work/run/sum_odd_squares.fbu \
  .sandbox-work/run/transactions.jsonl TRANSACTION_ID \
  .sandbox-work/run/restored.fbu

Prepare the real trace outside the no-network sandbox, then reproduce the practical comparison:

python3 bench/clf/prepare_dataset.py
FBU_SANDBOX_WORK_DIR="$PWD/.sandbox-work/clf-benchmark" \
  sandbox/run --python bench/clf/run.py \
  --trials 31 --file-trials 31 --target-ms 200 --rss-runs 5

The sandbox denies network access, confines writes to its disposable work directory, disables core dumps, and imposes CPU, memory, process, descriptor, file-size, and wall-time limits. It is suitable for this reviewed repository and accidental compiler failures. It shares the macOS kernel and is not a VM or a boundary for hostile native code. See sandbox/README.md.

Requirements

• Python 3.9 or newer for the verifier, interpreter, graph tools, and tests.
• macOS for sandbox/run and the recorded benchmark procedure.
• Clang from Xcode or standalone Command Line Tools for fbu compile.
• A full Xcode installation selected through xcode-select or FBU_DEVELOPER_DIR for Bunlog and the recorded benchmark procedure.
• Rust for optional C versus Rust versus Femtobun comparisons. Femtobun-only Bunlog analysis does not require Rust.
• A current browser for Dustbun. Its checked-in kernel needs no build tool at runtime. Rebuilding that kernel requires Clang's wasm32 target and the rust-lld bundled with Rust.
• Swift 6 and the macOS 14 SDK or newer to build the two native Boulderbun applications.

The package has no runtime Python dependencies.

Repository map

femtobun/
  femtobun/              model, verifier, codec, lowering, patches, CLI
  examples/              intent source, v0 through v3 JSON and modules, and sample input
  tests/                 semantic, encoding, patch, native, and oracle tests
  apps/boulderbun/       matched native Femtobun and Swift large-file scanners
  apps/dustbun/          consumer folder-size viewer and WebAssembly build
  app/                   Bunlog loopback server, exact protocol, and browser UI
  bench/clf/             practical access-log comparison and evidence
  bench/buffer/          shared-driver C/Rust/Femtobun comparison and evidence
  bench/agent/           controlled model manipulation benchmark and evidence
  bench/synthesis/       from-scratch agent code-generation benchmark
  bench/                 historical v0 comparison
  sandbox/               macOS isolation profile and resource monitor
  SPEC.md                implemented intent source, v0 through v3 IR, and agent protocols
  REPORT.md              historical v0 specialization report
  VERIFICATION.md        recorded verification commands and artifact hashes

Current boundary

Femtobun 0.7 is a bounded domain language, not a general-purpose replacement for C or Rust. It demonstrates that compiler-owned intent can produce compact source while preserving the existing verified graphs and native kernels. The current vocabulary covers checked sums, Common Log Format summaries, and parity-filtered square sums.

The first from-scratch benchmark cleared the 90% output-token target against C and Rust for one supported folder-total kernel. The intent compiler does not yet support arbitrary functions, target discovery, multi-stage program composition, records beyond the fixed log summary, debugging, or general application code. The next milestone is typed composition and held-out synthesis tasks that were not named directly by a primitive. Until that evidence exists, Femtobun should be described as cheap for its supported agent-written programs, not as the best language for agents.

The name was coined for this project. Exact-name web searches on September 2, 2026 found no established programming language called Femtobun. This is not trademark or registry clearance.

License

Femtobun is available under the MIT License.