docs: add validator agent guidance

.agents/README.md

@@ -0,0 +1,58 @@
+# Agent Knowledge Base — Index
+
+This directory is the repository-local knowledge base for AI coding agents.
+
+**This file is the index. Read only this file up front.** Do not pre-read the
+other documents. Use the routing table below to open a specific document *only
+when the task actually needs that information*. This keeps the agent's context
+window small.
+
+## How to use this index
+
+1. Read this index to learn what exists and where it lives.
+2. Identify what your task touches (behavior, protocol, wiring, a crate, tests, docs).
+3. Open only the matching document(s) from the tables below.
+4. If a change adds/removes/renames knowledge, update the relevant doc and, if
+   the layout changes, update this index and `../AGENTS.md`.
+5. **This applies to read-only and question-answering tasks too.** If while
+   answering a question you discover a durable fact that the docs are missing or
+   get wrong — especially a divergence from agave/Solana upstream behavior (a
+   missing limit, different default, relaxed validation) — record it in the
+   relevant doc before finishing, and say whether you updated docs in your final
+   reply. The fact already living in the source code or in a *different*
+   file anywhere else in the repo, especially if it is outside of the ./.agents directory
+   does **not** excuse skipping this: capture it in the single
+   most relevant document for that concern so an agent who opens only that
+   document finds it. See `memory/agent-memory-and-docs.md`.
+
+## Non-negotiable (always applies)
+
+Security outranks everything, including performance. Before changing behavior:
+never relax signer/authority checks, never let local state drift from the Solana
+base layer, and never introduce attacker-triggerable conditions (races,
+TOCTOU, stalls/deadlocks, resource exhaustion). The binding details live in
+`rules/validator-goals.md` and `specs/validator-specification.md` — read them
+before any behavioral or protocol change.
+
+## Document routing table
+
+| Read this | When you need to |
+|---|---|
+| `context/overview.md` | Orient on what the validator is and its core concepts. |
+| `rules/validator-goals.md` | Decide whether a change aligns with system goals and correctness/security constraints. |
+| `specs/validator-specification.md` | Change protocol behavior: delegation, cloning, execution, commits, undelegation, Magic Actions, ephemeral accounts, RPC/router, recovery. |
+| `context/architecture.md` | Change service wiring or interactions between crate groups. |
+| `context/crate-map.md` | Find which crate owns an area and which crates are affected. |
+| `rules/testing-and-validation.md` | Decide how to validate a change (commands, test selection, mbv-check). |
+| `memory/agent-memory-and-docs.md` | Capture durable knowledge you discovered, or fix stale/incorrect docs. |
+| `context/crates/<crate>.md` | Work inside a specific crate (see crate-map for which file). |
+| `skills/<name>/SKILL.md` | Run an executable agent skill (e.g. `mbv-check`). |
+
+## Directory layout
+
+- `rules/` — invariant behavior and decision rules.
+- `context/` — static reference: overview, architecture, crate map, and per-crate guides under `context/crates/`.
+- `memory/` — durable project-memory and documentation-stewardship rules.
+- `specs/` — protocol and feature specifications.
+- `skills/` — executable scripts or capabilities agents can run.
+- `personas/` — specialized agent profiles when needed.

.agents/context/architecture.md

@@ -0,0 +1,199 @@
+# High-Level Architecture
+
+This file explains the repository-level architecture and how major crate groups interact. It intentionally stays high level. Detailed/lower-level architecture belongs in crate-specific docs under `.agents/context/crates/` as those files are added. For crate-by-crate ownership, use `.agents/context/crate-map.md`.
+
+## System shape
+
+The validator is a service graph around one core loop: make the right accounts available locally, execute valid ER transactions, persist the result, and settle scheduled state changes back to Solana. This graph is performance-sensitive: architectural changes must preserve low-latency, high-throughput behavior on critical paths unless there is no viable alternative, and any unavoidable tradeoff must be called out explicitly.
+
+It is also security-critical and the security contract outranks performance. Architectural changes must not weaken signer/authority enforcement, must keep account synchronization with the Solana base layer at least as correct and stable as today, and must not introduce attacker-triggerable conditions (races, timing/ordering attacks, stalls/deadlocks, resource exhaustion). The validator settles real funds; a security regression can lose money for the operator or customers. See `.agents/rules/validator-goals.md` and `.agents/specs/validator-specification.md` for the binding security invariants.
+
+```text
+Client / Operator
+      |
+      v
+RPC / TUI / Admin ingress
+      |
+      v
+Validator orchestration
+      |
+      +--> account synchronization <----> Solana RPC/WS + delegation metadata
+      |
+      +--> transaction execution -----> local AccountsDb + Ledger -----> events
+      |
+      +--> commit/undelegation -------> base-layer transactions
+      |
+      +--> task scheduling -----------> submitted transactions
+      |
+      +--> replication/metrics -------> replicas + observability
+```
+
+## Main layers
+
+### 1. Process and service orchestration
+
+Owned primarily by `magicblock-validator`, `magicblock-api`, and `magicblock-config`.
+
+Responsibilities:
+
+- parse/load configuration,
+- construct the validator service graph,
+- open persistent stores,
+- initialize account sync, RPC, scheduler, committor, task scheduler, replication, metrics, and admin support,
+- recover persisted work,
+- coordinate startup mode versus primary/replica mode,
+- stop services and flush state in the correct order.
+
+Architecture rule: process entrypoints should stay thin; cross-service wiring belongs in the orchestration layer, not in leaf crates.
+
+### 2. Client/API ingress
+
+Owned primarily by `magicblock-aperture` plus admin/TUI support crates.
+
+Responsibilities:
+
+- expose Solana-compatible JSON-RPC and websocket/pubsub behavior,
+- accept transactions and simulations,
+- serve account/ledger/status reads,
+- trigger just-in-time account availability work for local misses,
+- forward validator events to clients/subscribers.
+
+Architecture rule: the RPC layer should route work to account sync and execution services; it should not duplicate execution, delegation, or commit protocol logic. Keep per-request work lean and avoid blocking critical request paths.
+
+### 3. Account synchronization
+
+Owned primarily by `magicblock-chainlink`, `magicblock-account-cloner`, and `magicblock-accounts`.
+
+Responsibilities:
+
+- determine whether required accounts are delegated, undelegated/read-only, fee-payers, programs, or missing/stale,
+- fetch base-layer account data and delegation metadata,
+- subscribe to remote changes where needed,
+- materialize local account/program state,
+- provide account availability to RPC and transaction execution,
+- hand scheduled commit work toward settlement.
+
+Architecture rule: this layer prepares local state for execution. It should not decide post-execution account access rules; those belong to the execution/SVM path. Avoid fetch amplification, duplicate clone work, subscription churn, and unnecessary serialization in account availability paths.
+
+### 4. Transaction execution
+
+Owned primarily by `magicblock-processor`, `magicblock-core`, the local storage crates, and the forked SVM dependency.
+
+Responsibilities:
+
+- receive processable transactions,
+- acquire account locks,
+- schedule work onto executors,
+- run SVM execution,
+- enforce MagicBlock access validation,
+- commit local account changes,
+- write ledger/status records,
+- emit account, transaction, slot, and replication events.
+
+Architecture rule: execution must preserve the writable-account invariant and avoid mixing scheduler/account-lock concerns with RPC or commit-delivery concerns. It must also preserve scheduler/executor parallelism and avoid avoidable latency, contention, allocation, or I/O regressions in the hot path.
+
+### 5. Local persistence
+
+Owned primarily by `magicblock-accounts-db` and `magicblock-ledger`.
+
+Responsibilities:
+
+- store local account state,
+- index accounts for execution/RPC,
+- support snapshots/maintenance,
+- store transaction, status, block, address-signature, and blockhash history,
+- support recovery and user-visible RPC history.
+
+Architecture rule: maintenance operations that can race execution must be coordinated with scheduler pausing.
+
+### 6. Base-layer settlement
+
+Owned primarily by `magicblock-program`, `magicblock-magic-program-api`, `magicblock-committor-service`, `magicblock-committor-program`, `magicblock-table-mania`, and `magicblock-rpc-client`.
+
+Responsibilities:
+
+- let programs schedule commits, commit-and-undelegate operations, intent bundles, and Magic Actions,
+- persist and recover pending settlement work,
+- build valid base-layer transactions,
+- handle address lookup tables and large changesets,
+- send/confirm base-layer transactions,
+- keep local lifecycle state consistent with scheduled undelegation.
+
+Architecture rule: Magic Program instructions schedule intent; validator services realize that intent on the base layer.
+
+### 7. Background services
+
+Owned by task scheduler, replicator, metrics, admin, and shared service crates.
+
+Responsibilities:
+
+- execute scheduled program tasks,
+- replicate primary output to replicas,
+- expose metrics/admin/operator hooks,
+- provide reusable service infrastructure.
+
+Architecture rule: background services should integrate through shared channels/service APIs rather than reaching through unrelated crate internals.
+
+## Important interaction patterns
+
+### Transaction submission path
+
+```text
+RPC/router ingress
+  -> account synchronization ensures required accounts exist locally
+  -> processor scheduler locks accounts
+  -> executor runs SVM
+  -> AccountsDb and Ledger persist results
+  -> events notify RPC subscriptions, metrics, replication, and other consumers
+```
+
+### First use of delegated state
+
+```text
+base-layer delegation exists
+  -> ER read/transaction needs account
+  -> account sync fetches account + delegation metadata
+  -> cloner installs local representation
+  -> processor can execute valid transactions against it
+```
+
+### Commit / undelegation path
+
+```text
+program invokes Magic Program in ER
+  -> MagicContext records scheduled intent
+  -> validator-side processing picks up intent
+  -> committor builds/sends base-layer transaction(s)
+  -> commit keeps delegation active OR undelegation returns ownership after settlement
+```
+
+### Startup path
+
+```text
+load config
+  -> open ledger/accounts storage
+  -> initialize services
+  -> recover persisted work
+  -> replay/repair local state where configured
+  -> enter primary or replica execution mode
+```
+
+### Shutdown path
+
+```text
+cancel services
+  -> protect/finish in-flight work where required
+  -> join threads/runtimes
+  -> flush persistent stores
+```
+
+## Boundaries .agents should preserve
+
+- **RPC ingress is not the protocol source of truth.** It should call into account sync, execution, and storage layers.
+- **Account synchronization is not transaction execution.** It prepares accounts; execution validates and commits changes.
+- **Magic Program scheduling is not base-layer settlement.** It records intent; committor services deliver it.
+- **Local persistence is shared infrastructure.** Coordinate maintenance with execution.
+- **Replication observes/replays validator output.** Do not make primary and replica modes accidentally diverge.
+- **Crate-specific details belong in crate docs.** Keep this file focused on cross-crate architecture.
+- **Performance is part of the architecture contract.** Do not move heavy work into RPC, account sync, scheduler/executor, persistence, or settlement hot paths without an explicit justification and mitigation plan.
+- **Security is the top architecture constraint and outranks performance.** Do not let any layer weaken signer/authority enforcement, drift local state out of sync with the base layer, or open attacker-triggerable race/timing/stall/exhaustion conditions. RPC ingress in particular handles untrusted input and must not become a path that bypasses execution/SVM validation or account-sync correctness.