docs: add validator agent guidance

.gitignore

@@ -35,7 +35,6 @@ _integration_test_bins/
 # AI related
 **/CLAUDE.md
 .claude/
-AGENTS.md
 
 # Local configs
 CODEBASE_MAP.md

AGENTS.md

@@ -0,0 +1,36 @@
+# Agent Guide
+
+This repository contains AI-agent guidance in `./agents/`. These files describe the validator's intended behavior, goals, protocol-level expectations, architecture, crate ownership, validation workflow, and documentation-memory rules.
+
+## Required acknowledgement
+
+At the start of any task that may change code, behavior, tests, documentation, configuration, or architecture, the agent **must first read the relevant files in `./agents/` and explicitly say so** before proceeding.
+
+Use wording like:
+
+> I found and read the relevant agent guidance in `./agents/` and will use it as the source of truth for this change.
+
+If the task is only a trivial file operation and no `./agents/` file is relevant, say that explicitly.
+
+## Start here
+
+Before working on any feature, bug fix, refactor, or behavioral change, read the relevant files:
+
+1. `agents/00_overview.md` — high-level validator purpose and runtime model.
+2. `agents/01_validator-goals.md` — system goals and correctness constraints.
+3. `agents/02_specification.md` — delegation, cloning, execution, commit, undelegation, Magic Actions, ephemeral accounts, RPC/router, and recovery behavior.
+4. `agents/03_architecture.md` — high-level repository architecture and crate interaction model.
+5. `agents/04_crate-map.md` — workspace crate purposes, dependencies, consumers, and where to start for common change areas.
+6. `agents/05_testing-and-validation.md` — required validation workflow, rs-check guidance, and integration test commands.
+7. `agents/06_agent-memory-and-docs.md` — required rules for capturing newly discovered durable behavior, workflows, pitfalls, and documentation corrections.
+8. Relevant crate-specific guide under `agents/crates/` when one exists, such as `agents/crates/magicblock-account-cloner.md` for `magicblock-account-cloner`, `agents/crates/magicblock-accounts.md` for `magicblock-accounts`, `agents/crates/magicblock-aml.md` for `magicblock-aml`, `agents/crates/magicblock-aperture.md` for `magicblock-aperture`, `agents/crates/magicblock-api.md` for `magicblock-api`, `agents/crates/magicblock-chainlink.md` for `magicblock-chainlink`, `agents/crates/magicblock-config.md` for `magicblock-config`, or `agents/crates/magicblock-metrics.md` for `magicblock-metrics`.
+
+Before changing code, consult the relevant `./agents` material to ensure the change does not violate the validator's goals, invariants, performance requirements, or specification. This acknowledgement is required; do not proceed silently after reading the files.
+
+The validator is performance-sensitive infrastructure. Changes must not degrade critical-path performance unless there is no viable alternative; if a tradeoff is unavoidable, call it out explicitly with the reason, expected impact, and any mitigation.
+
+When a feature is added, removed, or changed, the relevant file in `./agents/` **MUST be updated** to match the current implementation. These files cannot go out of sync with reality; if they do, they lose their usefulness for future agents and maintainers.
+
+When an agent discovers durable repository knowledge that is missing, incomplete, inaccurate, or stale in `./agents/`—including feature behavior, protocol details, crate responsibilities, validation/debugging workflows, pitfalls, or performance constraints—the agent **MUST** update the most relevant existing document or create a focused new document if none exists. If documentation cannot be updated, the agent must report the blocked follow-up explicitly.
+
+If anything is added to, removed from, renamed, or reorganized inside `./agents/`, update this `AGENTS.md` file in the same change so this entrypoint remains accurate.

agents/00_overview.md

@@ -0,0 +1,57 @@
+# MagicBlock Validator Overview
+
+This is the shortest orientation document for agents. It explains what this repository is for and points to the files that contain the deeper details. Avoid duplicating detailed protocol or crate architecture here.
+
+## What this validator is
+
+The MagicBlock validator is a specialized Solana Virtual Machine (SVM) runtime for Ephemeral Rollups (ERs). It executes transactions locally against delegated and ephemeral state, while preserving a path for state to be synchronized back to Solana.
+
+In practical terms, the validator:
+
+- accepts Solana-style RPC and transaction traffic,
+- clones required base-layer accounts/programs into local state,
+- executes transactions with MagicBlock-specific SVM rules,
+- persists local account and ledger state,
+- schedules commits/undelegations back to the base layer,
+- supports task scheduling, replication, metrics, and operator/admin flows.
+
+## Core concepts
+
+| Concept | Short meaning |
+|---|---|
+| Ephemeral Rollup | A low-latency SVM execution environment attached to Solana. |
+| Delegated account | A Solana state account locked by the Delegation Program and assigned to an ER validator for local execution. |
+| Ephemeral account | An ER-only account sponsored by delegated state. |
+| Commit | Synchronize ER state back to Solana while keeping the account delegated. |
+| Commit and undelegate | Synchronize ER state and return ownership to the original program on Solana. |
+| Magic Program | ER program used for commit scheduling, intent bundles, tasks, ephemeral accounts, and validator operations. |
+| Committor | Validator-side service that realizes scheduled base-layer intents. |
+
+## Which agent doc to read
+
+- `agents/01_validator-goals.md` — read when deciding whether a change is aligned with product/system goals.
+- `agents/02_specification.md` — read before changing protocol behavior: delegation, cloning, execution rules, commits, undelegation, Magic Actions, ephemeral accounts, RPC/router behavior, or recovery.
+- `agents/03_architecture.md` — read before changing service wiring or interactions between crates.
+- `agents/04_crate-map.md` — read to find which crate owns an area and which other crates may be affected.
+- `agents/05_testing-and-validation.md` — read before deciding how to validate a change.
+- `agents/06_agent-memory-and-docs.md` — read when a task may discover or change durable repository knowledge that future agents should remember.
+
+## Non-negotiable agent rules
+
+Before changing behavior, check the relevant agent docs and preserve the validator's goals, invariants, and performance expectations.
+
+The validator is performance-sensitive infrastructure. Do not degrade critical RPC, account sync, scheduling, execution, persistence, or settlement paths unless there is no viable alternative; if such a tradeoff is unavoidable, state it explicitly with expected impact and mitigation.
+
+When behavior changes, update the relevant `agents/` file in the same change. These docs must remain synchronized with the real implementation; stale guidance is worse than no guidance.
+
+When you discover durable knowledge that is missing or wrong in `./agents/`—for example a feature behavior, protocol invariant, crate responsibility, validation workflow, recurring pitfall, or performance constraint—update the most relevant existing document, or create a focused new one if no suitable document exists. If you cannot make the documentation update, report the exact follow-up before handing off.
+
+## Things to be especially careful with
+
+- Writable account access rules for delegated, ephemeral, confined, and explicitly allowed accounts.
+- Delegation and undelegation lifecycle transitions.
+- Commit intent durability and restart recovery.
+- Account cloning distinctions between delegated, undelegated/read-only, fee-payer, program, and large accounts.
+- Scheduler/account-lock correctness and executor parallelism.
+- Avoiding avoidable latency, throughput, allocation, lock-contention, or I/O regressions in hot paths.
+- Startup/shutdown ordering and persistent store flushing.

agents/01_validator-goals.md

@@ -0,0 +1,120 @@
+# MagicBlock Validator Goals
+
+This file states the goals that should guide implementation decisions. It intentionally avoids protocol details; use `agents/02_specification.md` for exact behavior and `agents/03_architecture.md` for crate/service interactions.
+
+## Primary goal
+
+The validator must provide a Solana-compatible, low-latency execution environment for delegated Solana state, then synchronize that state back to Solana safely through MagicBlock's commit and undelegation flows.
+
+A good change preserves:
+
+1. **Compatibility** — clients and programs should work like normal Solana where the ER model allows it.
+2. **ER correctness** — only accounts that are allowed to change in the ER may change in the ER.
+3. **Settlement safety** — commits, undelegations, and base-layer actions must be explicit, durable, and recoverable.
+4. **Performance** — critical RPC, account synchronization, scheduling, execution, persistence, and settlement paths must remain low-latency and high-throughput.
+
+## Product goals
+
+### Real-time execution
+
+The validator should support applications that need very low latency and high throughput.
+
+Prefer changes that:
+
+- keep RPC, scheduling, and execution paths lean,
+- avoid blocking critical loops,
+- preserve parallel execution for unrelated accounts,
+- avoid unnecessary allocations, lock contention, I/O, polling, cloning, serialization, and logging in hot paths,
+- maintain clear separation between async service work and CPU-bound transaction execution.
+
+Do not accept performance regressions unless there is no viable alternative. If correctness or safety requires a slower path, document the tradeoff, expected impact, and mitigation in the change handoff.
+
+### Low-cost user experience
+
+The ER is expected to support gasless-feeling or low-cost application flows.
+
+Prefer changes that:
+
+- do not blindly import base-layer fee assumptions into ER execution,
+- preserve fee-payer and sponsor behavior where the ER intentionally differs from Solana,
+- keep commit/settlement fees explicit in the commit pipeline.
+
+### Solana composability
+
+Delegated state should still compose with Solana programs and read-only Solana state.
+
+Prefer changes that:
+
+- keep standard program execution familiar,
+- preserve read access to cloned base-layer accounts/programs,
+- avoid fragmenting application state into incompatible ER-only copies unless the account is explicitly ephemeral.
+
+### Safe settlement
+
+Local ER state must have a safe path back to the base layer.
+
+Prefer changes that:
+
+- keep commit and undelegation scheduling explicit,
+- preserve commit ordering/nonce requirements,
+- recover pending settlement work after restart,
+- do not make local success look like base-layer settlement before the settlement pipeline has actually run.
+
+### High availability and observability
+
+The validator should remain operable in production-like deployments.
+
+Prefer changes that:
+
+- keep replication semantics intentional,
+- make failures observable,
+- avoid hiding commit, clone, scheduler, or RPC errors,
+- preserve metrics/admin/operator visibility.
+
+## Correctness goals
+
+### Account access
+
+The central correctness goal is that ordinary ER execution must not mutate arbitrary Solana state. Writable accounts must satisfy the MagicBlock access model described in `agents/02_specification.md`.
+
+### Lifecycle transitions
+
+Delegation, commit, commit-and-undelegate, and ephemeral account lifecycle transitions must remain coherent across:
+
+- local account flags/representation,
+- SVM execution,
+- Magic Program scheduling,
+- committor service execution,
+- restart recovery.
+
+### Persistence and recovery
+
+Persistent state is part of the system contract. Changes must not break recovery for:
+
+- local account state,
+- ledger/history,
+- pending commit intents,
+- scheduled tasks,
+- replica/primary state where applicable.
+
+## Non-goals
+
+Do not optimize for making the validator identical to a normal Solana validator when that conflicts with ER semantics.
+
+Do not bypass delegation records, access validation, commit nonces, or intent persistence to simplify implementation.
+
+Do not add protocol behavior in an isolated crate without updating the docs and checking the cross-crate architecture.
+
+## Change checklist
+
+Before finishing a feature, bug fix, or refactor, ask:
+
+1. Did I preserve the delegated/ephemeral writable-account invariant?
+2. Did I preserve the distinction between base-layer state, cloned local state, and ER-only state?
+3. Did I preserve commit and undelegation lifecycle behavior?
+4. Did I preserve restart recovery for any pending or persisted work?
+5. Did I avoid blocking critical scheduler/RPC/executor paths?
+6. Did I avoid degrading critical-path latency, throughput, memory use, lock contention, and I/O behavior?
+7. If a performance tradeoff was unavoidable, did I explicitly call out why, the expected impact, and mitigation?
+8. Did I update the relevant file in `agents/` if behavior changed?
+9. Did I update or create agent documentation for any newly discovered durable behavior, workflow, pitfall, invariant, crate responsibility, validation approach, or stale/missing guidance?