feat(liquidity-sdk-viem): add Vault V2 liquidity loader

.agents/pr-review-engine/agents/documentation.md

@@ -11,6 +11,7 @@ focus: |
   2. Markdown documentation accuracy across the repo (README, AGENTS.md, MISSION.md, docs/**, .agents/**).
   3. Pointer / link integrity for every internal reference touched by the diff.
   4. AGENTS.md ↔ persona backlink consistency.
+  5. Immutability of implemented TIBs already present on the target branch.
 canonical-rules: docs/jsdoc-style.md
 ---
 
@@ -45,8 +46,11 @@ Files in scope (read each one whose content is in the diff OR which references s
 - `.agents/pr-review-engine/SKILL.md`, `.agents/pr-review-engine/agents/*.md`, `.agents/pr-review-engine/references/*.md`, `.agents/commands/*.md`.
 - Any `*.md` colocated with a package (`packages/<pkg>/*.md`).
 
+Implemented TIBs already present on the target branch are exempt from current-code freshness and pointer-renaming checks below. Their implementation-time symbols, examples, and paths are historical evidence, even when the current code has moved on.
+
 For each Markdown file affected, flag:
 
+- **Implemented TIB rewrites.** A TIB already present on the target branch is a historical implementation-time record: do not update its prose, examples, symbols, or paths to follow later code. Changed decisions require a new superseding TIB; operational clarifications belong in a dated addendum. A TIB introduced for the current implementation may still be updated before it lands.
 - **Stale prose.** A statement that no longer matches the code after the diff — e.g. README documents a function that was removed/renamed; AGENTS.md lists a rule the code change just violated; an example that no longer compiles.
 - **Out-of-sync inventories.** A file enumerating personas, packages, slash commands, scripts, supported chains, etc. that no longer matches reality after the diff. E.g. a README that lists "supported chains: mainnet, base" while the diff just added arbitrum.
 - **Cross-doc consistency.** When the diff changes a rule in `AGENTS.md`, every persona that enforces it (per the backlink `> Applied by personas: …`) should reflect the new rule. When the diff renames a section heading in `AGENTS.md`, every doc that references that section by title needs an update.
@@ -59,7 +63,7 @@ For every Markdown link, path reference, or symbol pointer in the changed files
 - **Internal Markdown links must resolve.** `[label](./path/to/file.md)` — the path must exist. Anchors `#section-name` must match a heading in the target file (slugified — GitHub's convention).
 - **Path references in prose must resolve.** Lines like `Reference \`docs/jsdoc-style.md\`` or `Read \`.agents/pr-review-engine/agents/web3-security.md\`` are pointers; the file must exist.
 - **Frontmatter references must resolve.** Persona frontmatter (`applies:`, `trigger:`, `canonical-rules:`, `out-of-scope:` mentions) must reference real `AGENTS.md` sections, real flag names from `.agents/pr-review-engine/SKILL.md` Step 4, and real file paths.
-- **Renames cascade.** If the diff renames or moves a file (detect via `git diff --name-status --find-renames`), every reference to the old path in any tracked Markdown / persona / skill / command file must be updated. Grep for the old basename in the repo and surface unresolved hits.
+- **Renames cascade.** If the diff renames or moves a file (detect via `git diff --name-status --find-renames`), every reference to the old path in current Markdown / persona / skill / command files must be updated. Grep for the old basename in the repo and surface unresolved hits, excluding implemented TIBs already present on the target branch.
 - **Removed exports / removed files.** If the diff removes a public export or a file, grep the repo for references and flag any that survive.
 
 ## 4. AGENTS.md ↔ persona backlink consistency

.changeset/brave-vaults-reallocate.md

@@ -0,0 +1,17 @@
+---
+"@morpho-org/morpho-ts": minor
+"@morpho-org/blue-sdk": minor
+"@morpho-org/blue-sdk-viem": minor
+"@morpho-org/morpho-sdk": minor
+"@morpho-org/wdk-protocol-lending-morpho-evm": minor
+---
+
+Add the canonical `vaultV2BluePublicAllocatorAbi` to `morpho-ts`, move the shared `marketParamsAbi` source of truth there while preserving its `blue-sdk` re-export, and raise the `blue-sdk` peer range to the introducing `morpho-ts` minor. Add Vault V2 allocation-cap helpers and the updated `canPullFromIdle`/`canPullFromMarket`/WAD-scaled penalty config types to `blue-sdk`, add explicit-allocator deployless and fallback reads to `blue-sdk-viem`, and expose Vault V2 shared-liquidity discovery, planning, metrics, maximum-penalty filtering, and flat market/idle reallocations through `morpho-sdk` Blue flows.
+
+V2 bundles now pull the proportional loan-token penalty through GeneralAdapter1, grant the allocator an exact non-skippable allowance from Bundler3, pass the configured `uint64 penalty` in calldata, and keep the nonpayable allocator calls out of `tx.value`. The planner mirrors contract execution order for penalties, source deallocation, first vault accrual (including zero-elapsed loss recognition), and target allocation; freezes the resulting relative-cap denominator across later calls for that vault; keeps every adapter coherent with one canonical simulated state per Morpho market; rejects non-positive operation amounts and same-market moves across adapters; and uses the latest timestamp in its complete input snapshot by default.
+
+Use coherent versioned names across the V1 and V2 reallocation APIs, including `VaultV1ReallocationData`, `VaultV2ReallocationData`, `computeVaultV1Reallocations`, `computeVaultV2Reallocations`, `VaultV2BluePublicAllocatorOptions`, and Vault V2-prefixed Bundler actions. Preserve the published V1 names as deprecated aliases.
+
+Compatibility note: `VaultV2MorphoMarketV1AdapterV2.ids()` now declares its existing three-element result as `readonly [Hash, Hash, Hash]`. The runtime values and ordering are unchanged, and derived allocation identifiers are immutable descriptors. We intentionally accept this TypeScript assignability tightening in the minor release; callers that explicitly require a mutable `Hash[]` can copy the tuple with `[...adapter.ids(params)]`.
+
+Add an explicit `MorphoBorrowWithV2ReallocationsOptions` WDK opt-in for the combined V1/V2 reallocation union and its possible approval requirement while preserving the legacy `MorphoBorrowOptions` input and authorization-only requirement result type.

.changeset/calm-vault-v2-liquidity.md

@@ -0,0 +1,5 @@
+---
+"@morpho-org/liquidity-sdk-viem": minor
+---
+
+Add an independent REST-backed `VaultV2LiquidityLoader` alongside the existing Vault V1 loader. It validates successful API payloads at runtime, pins REST and RPC hydration to one indexed block, anchors live REST market totals to that block's timestamp to prevent double accrual, and fails explicitly on incomplete positions instead of treating missing state as zero. Raise its `blue-sdk`, `blue-sdk-viem`, `morpho-sdk`, and `morpho-ts` peer floors to the introducing versions.

AGENTS.md

@@ -156,6 +156,7 @@ A scannable list of patterns reviewers reject. Most are review-only today (per t
   - `@throws` for each typed error class an integrator may pattern-match on.
   - One `@example` block with realistic working code: imports, client setup, the call, expected return.
 - **AI-legibility is first-class.** Identical signatures across V1/V2 where protocols overlap. Discriminated unions with obvious `type` tags. Deterministic outputs verifiable byte-for-byte. Error messages read like instructions an agent can act on without guessing. Protocol-specific terms (`LLTV buffer`, `wNative`, `GeneralAdapter1`, `bundler3`, `PublicAllocator`, `MetaMorpho`, `Permit2`, `WAD`) live in the [`packages/morpho-sdk/AGENTS.md`](./packages/morpho-sdk/AGENTS.md) glossary.
+- **Implemented TIBs are historical records.** Do not rewrite a TIB already present on the target branch to follow later code, symbol, or path changes. Keep the TIB's implementation-time names and examples intact. A changed decision gets a new superseding TIB; an operational clarification gets a dated addendum. Only a TIB introduced for the current implementation may be kept in sync with that implementation before it lands.
 - **TypeDoc-generated reference** published per release.
 - **Feedback loop:** if the same question is asked twice, the answer goes into the relevant `AGENTS.md` or JSDoc on the export it concerns.