chore(adr): add adr for reassign evolve

docs/madr/1-reassign-evolve.md

@@ -0,0 +1,105 @@
+# Reassign ANT to Evolve Implementation Kickoff on the ArNS Portal
+
+- Status: Proposed
+- Approvers: [Ariel], [Dylan], [Atticus], [Phil], [David]
+- Date: [2025-01-30]
+- Authors: [Atticus]
+
+## Context and Problem Statement
+
+Currently to evolve the ANT we use AOS `Eval` - this introduces the problem of
+evaluating what the current version of the code is. If we maintain a variable in
+the state of the process containing a version number, that tells us only what
+that version number is. At any point the user - owner - of the ANT may `Eval`
+new code into the process resulting in changes to the process that may not
+reflect what we expect the version number we assigned to reflect. To overcome
+this we dryrun interactions on APIs and analyze the results to see if the APIs
+perform as expected - this is very inefficient as dry run calls to CU's are
+expensive in networking client side, as well as for the CU.
+
+And so it is proposed to leverage the `Reassign-Name` handler in conjunction
+with `_boot` to fork the process state to a whole new ANT, assign that new ANT
+as the registered ANT to the specified ArNS name in the registry, and using the
+module ID of the process to identify process version and capabilities, and
+solely the module ID.
+
+## Decision Drivers
+
+- Improve the performance of ANT loading client side.
+- Ensure the upgrade process is more robust by using immutable module IDs.
+- Reduce computational load on CU infra.
+- Mitigate risks associated with reassigning ANT state and ARNS records.
+
+## Considered Options
+
+1. **Current Approach (Baseline)**
+   - Multiple dry runs per ANT.
+   - ETH compatibility checked via handler analysis.
+   - Upgrade involves loading Lua code.
+2. **Optimized Approach (Proposed Change)**
+   - Use the module ID to evaluate process version.
+   - Upgrade via spawning a new ANT and reassigning ARNS records.
+
+## Decision Outcome
+
+### Chosen Option: Optimized Approach
+
+The optimized approach reduces computational overhead and improves caching for
+better performance. It also shifts to a more robust upgrade mechanism using
+immutable module IDs rather than version detection heuristics. We can do this
+now that we compile and publish our own WASM binaries, rather than using an AOS
+binary and loading our code into it.
+
+### Positive Consequences
+
+- **Performance Improvement:** Reducing dry runs significantly speeds up ANT
+  loading.
+- **Immutable Module Versioning:** Eliminates issues with heuristic version
+  analysis.
+- **Reduced CU Load:** Fewer computations per ANT.
+
+### Negative Consequences
+
+- **Complicates Memory Usage on ANT Registry:** More ANTs means more state in
+  the ANT registry, which currently doesn't have a cleanup process.
+- **Potential Integration Issues:** Existing integrations relying on fixed ANT
+  IDs may break.
+- **State Limitations:** Large ANT states (e.g., >2000 undernames) may fail to
+  bootstrap on spawn, meaning we need to understand the limitations there and
+  decide what amounts we wish to support.
+
+## Pros and Cons of the Options
+
+### Current Approach
+
+- `+` Already implemented and functional.
+- `+` Ensures ETH compatibility via handler checks.
+- `-` Multiple dry runs increase computational cost.
+- `-` Upgrade process relies on mutable version checks.
+
+### Optimized Approach (Chosen)
+
+- `+` 3x faster ANT loading.
+- `+` Reduces CU consumption.
+- `+` Enables robust versioning.
+- `-` Introduces new risks related to state migration and memory management.
+
+## Links
+
+- [Ariel]: https://github.com/arielmelendez
+- [David]: https://github.com/djwhitt
+- [Dylan]: https://github.com/dtfiedler
+- [Atticus]: https://github.com/atticusofsparta
+- [Phil]: https://github.com/vilenarios
+
+## Notes
+
+- Further analysis is required for large ANT states.
+  - Records
+  - Controllers
+- Consider preemptive PRs for integration updates.
+  - for example permaweb deploy
+- Implement observation tools to track stale ANTs in the ANT registry
+  - Fastest solution is probably adding a `prune` handler to the ANT registry
+    that consumes process IDs and removes them, then use a cron job in gh
+    actions to pull the ArNS records and decide which ANT ids to prune

docs/madr/template.md

@@ -0,0 +1,97 @@
+# [short title of solved problem and solution]
+
+- Status: [proposed | rejected | accepted | deprecated | superseded by
+  [ADR-5](5-example.md)]
+- Approvers: [list everyone involved in the decision]
+- Date: [YYYY-MM-DD]
+- Authors: [list of authors]
+
+## Context and Problem Statement
+
+[Describe the context and the problem that needs to be solved, capturing the
+background and why this decision is necessary.]
+
+## Decision Drivers
+
+[Identify key factors that influence the decision, such as
+requirements, constraints, and other considerations.]
+
+- [driver 1]
+- [driver 2]
+- [driver 3]
+
+## Considered Options
+
+[List the options that were considered to address the problem, providing a brief
+overview of each.]
+
+- [option 1]
+- [option 2]
+- [option 3]
+
+## Decision Outcome
+
+[Describe the decision that was made, including why it was chosen over the
+other options.]
+
+### Positive Consequences
+
+[Highlight the benefits and positive outcomes expected from this decision.]
+
+- [consequence 1]
+- [consequence 2]
+
+### Negative Consequences
+
+[Identify any drawbacks or negative outcomes that might result from this decision.]
+
+- [consequence 1]
+- [consequence 2]
+
+## Pros and Cons of the Options
+
+[Compare the pros and cons of each considered option.]
+
+### [option 1]
+
+- `+` [pro 1]
+- `+` [pro 2]
+- `-` [con 1]
+- `-` [con 2]
+
+### [option 2]
+
+- `+` [pro 1]
+- `+` [pro 2]
+- `-` [con 1]
+- `-` [con 2]
+
+### [option 3]
+
+- `+` [pro 1]
+- `+` [pro 2]
+- `-` [con 1]
+- `-` [con 2]
+
+## Links
+
+[Include any relevant links to documents, discussions, or other resources that
+provide additional context or background information.]
+
+- [link 1](url)
+- [link 2](url)
+
+## Related Decisions
+
+[List any related ADRs or decisions that are connected to this one.]
+
+- [ADR-1](1-example.md) - [Title of ADR-1]
+- [ADR-2](2-example.md) - [Title of ADR-2]
+
+## Notes
+
+[Include any additional notes or comments that are relevant to the decision.]
+
+---
+
+[ADR Template]: https://adr.github.io/