fix: enable historical dry-run evaluation in genesis-wasm CU

.dockerignore

@@ -0,0 +1,15 @@
+# Large runtime data — never needed at build time
+cache-*
+*.lmdb
+*.mdb
+
+# Local build artifacts (image builds from source)
+_build/
+
+# Secrets and local config (mounted as volumes at runtime)
+hyperbeam-key.json
+config.json
+
+# Dev tooling
+.git/
+scripts/

.gitignore

@@ -1,3 +1,4 @@
+config.*
 .rebar3
 _build
 _checkouts
@@ -42,4 +43,6 @@ mkdocs-site/
 mkdocs-site-id.txt
 mkdocs-site-manifest.csv
 
-!test/admissible-report-wallet.json
+!test/admissible-report-wallet.json
+!test/admissible-report.json
+!test/config.json

.vscode/launch.json

@@ -14,7 +14,7 @@
       "internalConsoleOptions": "openOnSessionStart",
       "module": "hb_debugger",
       "function": "start_and_break",
-      "args": "[${input:moduleName}, ${input:functionName}, [${input:funcArgs}]]"
+      "args": "[${input:moduleName}, ${input:functionName}, [${input:funcArgs}], <<\"${input:debuggerScope}\">>]"
     },
     {
       "name": "Attach to a 'rebar3 debugger' node.",
@@ -65,6 +65,11 @@
       "id": "funcArgs",
       "type": "promptString",
       "description": "(Optional) Pass arguments to the function:"
+    },
+    {
+      "id": "debuggerScope",
+      "type": "promptString",
+      "description": "(Optional) Additional modules/prefixes for debugger scope:"
     }
   ]
 }

.vscode/settings.json

@@ -1,5 +1,6 @@
 {
   "editor.detectIndentation": false,
   "editor.insertSpaces": true,
-  "editor.tabSize": 4
+  "editor.tabSize": 4,
+  "editor.rulers": [80]
 }

.vscode/tasks.json

@@ -14,7 +14,37 @@
     {
       "label": "Stop HyperBEAM",
       "type": "shell",
-      "command": "lsof -i tcp:10000 | tail -n 1 | awk '{print $2}' | xargs kill -9"
+      "command": "lsof -i tcp:8734 | tail -n 1 | awk '{print $2}' | xargs kill -9"
+    },
+    {
+      "label": "Generate a flame graph for a function.",
+      "type": "shell",
+      "command": "rebar3 as eflame shell --eval \"hb_debugger:profile_and_stop(fun() -> ${input:moduleName}:${input:functionName}(${input:funcArgs}) end).\"",
+      "group": "test",
+      "problemMatcher": "$erlang",
+      "presentation": {
+        "echo": true,
+        "reveal": "always",
+        "focus": false,
+        "panel": "new"
+      }
+    }
+  ],
+  "inputs": [
+    {
+      "id": "moduleName",
+      "type": "promptString",
+      "description": "Enter module:"
+    },
+    {
+      "id": "functionName", 
+      "type": "promptString",
+      "description": "Enter an exported function name:"
+    },
+    {
+      "id": "funcArgs",
+      "type": "promptString",
+      "description": "(Optional) Pass arguments to the function:"
     }
   ]
 }

AGENTS.md

@@ -0,0 +1,24 @@
+This repository contains HyperBEAM, an implementation of the AO-Core protocol.
+
+To familiarize yourself with AO-Core, read the `README.md` file.
+
+To understand how to write code for HyperBEAM, read `CONTRIBUTING.md` for 
+repository-level guidelines, and `docs/misc/hacking-on-hyperbeam.md` learn about
+its debugging tools and infrastructure.
+
+In addition to the rules outlined in `CONTRIBUTING.md`, you should abide by the
+following:
+
+1. Always be surgical in your edits. Minimize the line-of-code changes you make
+   during every single edit.
+2. Before adding new utilities, search for existing utilities that do something
+   similar. Candidates are often found in `hb_ao`, `hb_util`, and `hb_test_utils`.
+3. Ensure that you understand the differences between Erlang map terms and 
+   AO-Core's messages. Messages are built using maps under-the-hood, but may also
+   be lazy-loaded (linkified), giving them different semantics.
+4. Before submitting any code as 'complete', you **must** validate that your
+   new changes do not break any existing tests across the full suite. You are 
+   never being asked to write a 'toy' implementation of features or changed. Your
+   code must actually work in-production.
+5. Always attempt to leave the codebase in a better state than you found it. More
+   precise, clear, and minimal -- while maintaining the existing featureset.

CONTRIBUTING.md

@@ -0,0 +1,131 @@
+# Contributing to HyperBEAM.
+
+There are three basic rules for writing and merging PRs to HyperBEAM:
+1. The PR must not introduce additional test failures, flakes, or
+   removal/defeating of existing tests unless agreed by multiple maintainers.
+2. Modifications to the 'kernel layer' must never be made where modifications to
+   the 'application layer' would suffice.
+3. Merged code must abide by the existing style in the repo. Just write and merge
+   code that blends in. This rule sounds unimportant, but over time it is what makes
+   the code maintainable and understandable by a larger set of developers.
+   Spaghetti/mixed styles lowers comprehension, which in a security sensitive
+   environment => bugs => lost value. No broken windows if we can help it.
+
+# The HyperBEAM Style Guide.
+
+**Rule one of style guide club:** _We do not talk about style guide club._
+
+We are here to build a fully decentralized alternative to cyberspace as it 
+is currently constructed. We are not interested in long conversations about
+where to put commas or spaces.
+
+**Rule two of style guide club:** _Blend in._
+
+Rule one does not imply that we do not care about the quality of the codebase.
+Far from it: We know that we will be maintaining this code for decades to come.
+It is important that we are all aligned on style and patterns, but less important
+what those styles and patterns actually are. Having `length(Contributors)` 
+styles adds overhead to understanding the codebase, which over time hides bugs
+and reduces maintainability, but each stylistic choice is largely an opinion
+that -- despite strong feelings -- lacks criticality. Hence, rule two:
+Only write and merge code that actually _blends in_.
+
+Write your code as if you were the author of all of the existing code. If all 
+of the other code is written in a certain style, then copy it. If the style
+of the code in your PR would not _blend in_, then its style is objectively
+in violation of `style guide club`'s rules.
+
+In the event of disagreement, a simple rule should guide our decisions: What
+does the majority of the LoC in the codebase already do? Do that. Then get 
+back to hacking.
+
+If you don't like something about the style, simply contribute. If others
+disagree strongly, the existing style will be kept. If your contributions are
+seen by others as reasonable and inline with the canon, then it will gradually 
+become adopted as the standard in the codebase.
+
+**This concludes the rules of style guide club.**
+
+Remember: Cypherpunks write code!
+
+# A Rough Guide to the HyperBEAM `canon`
+
+You should pick up and continue the style of the codebase as you learn how it 
+works. There is no real substitute for paying attention. There are, however, a 
+few basic rules that are widely established and represent the core `canon` of the
+codebase. As of time of {{`git blame`}}, there is highest consensus around the
+following:
+
+- Always use `-` over `_` in binary key names.
+    - Why: In general we try to follow the HTTP semantics RFC 9110, so all keys
+      should be HTTP-Header-Case. This is the style that has been used for Arweave
+      data protocols since inception, so to avoid confusion we maintain it in
+      HyperBEAM. 
+    - Nuances:
+        - One weirdness we inherit from HTTP-land is that headers are actually
+          case-insensitive, despite the use of capitals in header descriptions,
+          over-the-wire they are lower-case in HTTP/2+. AO-Core shoots for the
+          same semantics for consistency.
+        - In device key resolutions that have multiple words (for example:
+          `i_like(Base, Req, Opts) -> {ok, <<"Turtles!">>}.`) you may be tempted
+          to call `~device@1.0/i_like`. Don't. Instead call `/i-like`.
+          `hb_ao_device` will normalize the keys and match for you.
+        - `hb_opts` uses all atoms for its message keys. This is a mistake. It
+          is nice to be able to lookup keys via atoms (normalizing as above) and
+          we should maintain this, but under the surface the keys should be
+          normal-form binaries. To avoid issues when this is translated, perform
+          `Opts` lookups with only atoms, or use binaries of normal-form if you
+          must.
+- Try to keep lines to around 80 characters-ish. This is not a strict rule because
+  sometimes an 81-85 character line would be very ugly and harder to follow if split.
+  Use your judgement.
+  - Why: Our objective is to keep the code readable. Monster lines, and machine-enforced
+    strict styles, both butcher this. Human/LLM judgement can help here.
+- Add a `%%% @doc` moduledoc to each new module you write, and comment every
+  function you write with a `%% @doc Description` above it. Inline comments are
+  prepended with a single `%`.
+  - Why: This helps humans and LLMs grok your code in the future. It also surfaces
+    useful information in tooltips etc upstream.
+  - Nuance: I do not know why the Erlang style uses `%%%` for moduledocs, `%%` for
+    functions, and `%` for inline comments, but it does. This can help with parsability
+    for some tooling and the effort-cost is minimal, so we use it.
+- Avoid 'waterfalls'-style statements, instead keeping every set of statements
+  nested such that the start and end of the block are indented inline with each
+  other.
+  - Why: This uses slightly more lines, but makes deeply nested code much more
+    readable and comprehensible.
+  - Examples:
+```erlang
+    BadForm = lists:map(
+        fun(X) ->
+            X * lists:sum(lists:fold(
+                fun(Y, Acc) ->
+                    Y * Acc
+                end,
+                [1,2,3]
+            ))
+        end
+    ),
+    GoodForm = lists:map(
+            fun(X) ->
+                X *
+                    lists:sum(
+                        lists:fold(
+                            fun(Y, Acc) ->
+                                Y * Acc
+                            end,
+                            [1,2,3]
+                        )
+                    )
+            end
+        )
+```
+There are a few areas where there is no consensus on patterns or style yet:
+- Expressing docs in the info/[0,1] call of devices. There are a few different
+  styles in different devices in the codebase -- if you want to add info response
+  'inline' docs try to pick one that already exists and see what works/doesn't.
+  We will need to unify them at some point.
+- `maybe ... end` vs nested `case` expressions. `maybe` seems useful and preferable
+  in at least some cases, but bubbling the right error -- rather than just an error --
+  the caller can sometimes be difficult due to the `else` pattern matching.
+  Experimentation with patterns here would be good.