Skip to content

AGENTS.md

Latest commit

 

History

History
76 lines (61 loc) · 5.92 KB

AGENTS.md

File metadata and controls

76 lines (61 loc) · 5.92 KB
Raw

AGENTS.md — PON-BEAM Agentic Workflow & Engineering Rules

Purpose

Build PON-BEAM: a complete re-architecture of the BEAM virtual machine (Erlang/OTP) using Jean Marcelo Simão's Notification-Oriented Paradigm (PON). Each VM internal subsystem is redesigned as a reactive PON entity — eliminating polling, avoiding linear scans, and executing strictly via point-to-point notifications.

Repository Structure

pon-beam/
├── otp/                          # Erlang/OTP 30.0-rc0 fork
│   └── erts/emulator/beam/      # ERTS — Where C modifications live
├── formal/                       # 4-Pillar Formal Verification Suite (TLA+, Coq, Frama-C, PropEr)
├── harness/                      # Comparative benchmark harness
│   ├── config/                   # ERTS path configs (baseline.sh, ponbeam.sh)
│   ├── benchmarks/               # Erlang benchmark suites
│   │   ├── lib/                  # Base modules (pon_harness, pon_diff, pon_stats_reader)
│   │   └── pon_experiments/      # PON experiments (bench_*_vs_ponserver, smokes, pon_server)
│   ├── report/                   # Template and assets for HTML diff report
│   └── run.sh                    # Primary harness execution script
├── docs/                         # Specifications & engineering plans
├── book/                         # Interactive HTML book builder & chapter sources
├── Makefile                      # Primary build, benchmark, and verification entry point
└── AGENTS.md                     # This workflow guidelines file

Branch Strategy

  • otp-30.0-rc0-stock — Original, immutable OTP code. Never modify.
  • pon-beam — Active working branch where PON modifications are applied.

Implementation Phases

Each phase follows a complete cycle: Modify ERTS C code ➔ Compile ➔ Run Benchmark ➔ Generate Diff Report ➔ Commit.

Phase Subsystem Target Files Estimated Duration Acceptance Criteria
0 Fork Infrastructure Makefile.in, configure.ac, pon_*.h 1-2 weeks make TYPE=ponbeam produces functional beam.ponbeam.smp
1 PON-Receive erl_message.h, erl_process.c, pon_premise.h, erl_proc_sig_queue.c 4 weeks receive_mailbox_scan exhibits $O(1)$ latency — closed: jump O(1) medido (fase1_jump 2.4–181×, fase1_real 25–2023×, commit da3686db), escopo premissa única/cabeça concreta
2 PON-Timer erl_timer.c, pon_instigation.h 2 weeks Parity without regression (RPT-14): fase2_timer_churn/fair_timer ≥ 1.0×; "0.0% CPU idle waste" declared naive and replaced by parity
3 PON-Spawn erl_process.c 1 week Parity without regression (RPT-15): gates de custo + instigação causal (spawn_instigations/spawn_notifications); fair_spawn ≥ 1.0× — closed: regressão −26% eliminada, 0.98–1.28×; critério "latência ~2×" declared naive projection and replaced by parity
4 PON-Scheduler erl_process.c, erl_sched.h, pon_condition.h 6 weeks closed: paridade sem regressão + instigação causal (ErtsCondition eventfd+epoll, scheduler_idle_blocks); fase4_sched_* 1.00× — critério "0.0% CPU idle" declared naive and replaced by parity (RPT-04)
5 PON-ETS erl_db.c, erl_db_hash.c, pon_ets.h 6 weeks closed: watcher lateral funcional por instigação causal — fase5_ets_watcher notificação + 1 lookup 34–43µs vs polling 1000 lookups 282–374µs (~8.3×), fase5_stress_ets 1.00×; critério ets_read_repeat ~1000× declared naive projection (ETS stock já é hash O(1)) (RPT-05)
6 PON-Compiler sys_pon_premises.erl (pass), compile.erl, pon_premise.c 4 weeks closed: pass sys_pon_premises via +pon_beam + classificação no fetch (runtime fix); fase6_jump_receive O(1) plano 0.6–1.1 µs — 392.6× @10k; scan parity sem regressão (0.47–1.43×); f6test ALL PASS; byte-paridade (RPT-06)
7 PON-GC erl_gc.c, erl_gc.h 8 weeks gc_heap_scan exhibits $\sim 10\times$ scan reduction

Golden Rules

  1. Never modify the baseline. Original OTP code resides in otp-30.0-rc0-stock. All modifications occur on branch pon-beam.
  2. Wrap all C modifications in #ifdef PON_BEAM. The original code remains intact. PON-BEAM is a compilable overlay.
  3. Every phase delivers a differential benchmark. A phase is incomplete without an empirical diff proving performance gains. The harness automatically generates the HTML diff.
  4. Benchmark before and after. Always measure across both ERTS targets (stock vs ponbeam) with identical workloads.
  5. One commit per phase. Commit message format: feat(phase-N): <description> — validated.

Primary Commands

Command Action
make build-stock Compiles Stock OTP 30 baseline
make build-pon Compiles OTP with PON-BEAM ERTS
make build-pon-debug Compiles PON-BEAM with debug telemetry counters
make benchmark Runs full benchmark harness (includes 2× 10-min marathon)
make benchmark-fair Runs fair control group (quick, median-of-5 protocol)
./harness/run.sh --fase=N Runs scenarios of a single phase (e.g. --fase=1)
./harness/run.sh --only=name Runs a single scenario by name
make benchmark-list Lists available benchmarks
make verify-all Runs 4-Pillar Formal Verification suite (TLA+, PropEr, Frama-C)
make report Opens latest HTML diff report
make clean Cleans build artifacts

References

  • PON-BEAM Thesis: docs/EX-37-pon-beam-arquitetura-orientada-a-notificacoes.md
  • Engineering Plan: docs/EX-38-pon-beam-plano-de-engenharia.md
  • Formal Validation Suite: docs/RPT-16-pon-formal-validacao-suite.md (TLA+ 11/11, Coq 4/4, Frama-C 23/23, PropEr 14/14), docs/ART-01-validacao-formal-matematica.md
  • Notification-Oriented Paradigm: Simão & Stadzisz (2008–2009)