@bananapus/core-v6 0.0.34 → 0.0.35

package/ARCHITECTURE.md

@@ -2,49 +2,73 @@
 
 ## Purpose
 
-`nana-core-v6` is the protocol root. It owns project identity, permissions, rulesets, token supply, treasury balances, payout limits, fee logic, and the hook interfaces that every extension repo composes with.
+`nana-core-v6` is the protocol root for the V6 stack. It owns project identity, rulesets, permissions, treasury balances, token issuance, fee behavior, payout limits, and the hook interfaces every extension repo composes with.
 
-If a change affects accounting, supply, fee behavior, terminal routing, or permission semantics, this is the repo that defines the source of truth.
+If a change affects accounting, supply, fee logic, terminal routing, or permission semantics, this repo is the source of truth.
 
-## Boundaries
+## System Overview
 
-- The core owns balance and supply transitions.
-- Extensions may adjust economics through hooks, but they should not invent competing ledgers.
-- The core deliberately avoids app-specific behaviors like NFT composition, DEX routing strategy, or bridge-specific message transport.
+`JBController`, `JBMultiTerminal`, and `JBTerminalStore` form the main execution and accounting pipeline. `JBDirectory`, `JBRulesets`, `JBProjects`, `JBTokens`, `JBPermissions`, `JBSplits`, and related contracts provide the routing, identity, and shared state that all downstream repos depend on. `JBTerminalStore` is terminal-scoped through `msg.sender`, so each terminal records its own balances and usage against the shared ruleset and price surfaces. Extensions may influence economics through hook interfaces, but they should not create competing ledgers.
 
-## Main Components
+## Core Invariants
 
-| Component | Responsibility |
-| --- | --- |
-| `JBMultiTerminal` | Entry point for payments, cash outs, payouts, balance additions, and fee handling |
-| `JBTerminalStore` | Bookkeeping and preview math for payment, payout, allowance, and cash-out paths |
-| `JBController` | Project launch, ruleset queueing, token minting and burning, split-group updates |
-| `JBDirectory` | Maps projects to controllers and terminals |
-| `JBRulesets` | Time-ordered ruleset lifecycle and approval-hook integration |
-| `JBTokens`, `JBERC20`, `JBProjects` | Token and project identity surfaces |
-| `JBSplits`, `JBFundAccessLimits`, `JBPrices`, `JBPermissions` | Shared state for distribution, limits, price conversion, and authorization |
+- Preview functions must remain behaviorally aligned with state-changing functions.
+- Data hooks run before settlement and may alter economics; pay and cash-out hooks run after settlement.
+- Reserved tokens and other pending supply affect supply-sensitive math before distribution.
+- Terminal balances, fee accounting, reclaim math, and surplus calculations must agree.
+- Fee logic taxes fund egress, not every internal rebalance. Same-terminal project routing is a special case and must stay coherent with fee-free surplus tracking.
+- Rulesets are time-ordered and approval-aware, and many deployer repos depend on predictable ID progression.
+- Permission checks are protocol validity checks, not UI affordances.
+
+## Modules
+
+| Module | Responsibility | Notes |
+| --- | --- | --- |
+| `JBMultiTerminal` | Payment, cash-out, payout, allowance, and fee entrypoint | Execution surface |
+| `JBTerminalStore` | Shared accounting and preview math | Economic source of truth |
+| `JBController` | Launch, queue rulesets, mint, burn, and split-group updates | Supply and configuration |
+| `JBDirectory`, `JBRulesets` | Project routing and time-based ruleset lifecycle | Coordination layer |
+| `JBProjects`, `JBTokens`, `JBERC20` | Identity and token surfaces | Ownership and tokenization |
+| `JBPermissions`, `JBSplits`, `JBFundAccessLimits`, `JBPrices` | Shared authorization and configuration state | Cross-repo dependencies |
 
-## Runtime Model
+## Trust Boundaries
+
+- This repo owns canonical balance and supply transitions.
+- Hook repos may adjust inputs and post-settlement side effects, but they should not replace the ledger defined here.
+- External price feeds, Permit2, and ERC-20 behavior are dependencies, but accounting truth stays in core.
+
+## Critical Flows
 
 ### Payment
 
 ```text
 terminal receives funds
-  -> terminal store reads the current ruleset and optional data hooks
-  -> store computes weight-based minting results
+  -> terminal store reads the active ruleset and optional data hooks
+  -> before-pay data hook can modify weight and return pay-hook specs
+  -> terminal store records payment against the terminal-scoped ledger
   -> controller mints beneficiary tokens and accrues reserved tokens
-  -> pay hooks execute only after settlement
+  -> pay hooks run only after settlement
 ```
 
 ### Cash Out
 
 ```text
 holder requests redemption
-  -> terminal store computes reclaim amount from surplus, supply, and tax settings
-  -> optional data hooks can adjust the calculation inputs
+  -> terminal store reads current ruleset, balances, and supply inputs
+  -> before-cash-out data hook can modify reclaim inputs and hook specs
+  -> terminal store records the cash out against the terminal-scoped ledger
   -> controller burns tokens
-  -> terminal pays the reclaim amount and routes protocol fees
-  -> cash-out hooks execute only after settlement
+  -> terminal pays reclaim value and routes protocol fees
+  -> cash-out hooks run only after settlement
+```
+
+### Launch And Queue Rulesets
+
+```text
+owner, operator, or omnichain ruleset operator
+  -> controller launches or queues rulesets
+  -> launch path also sets the controller in the directory and configures terminals
+  -> rulesets become the source of truth for subsequent pay, cash-out, and admin constraints
 ```
 
 ### Payouts And Allowances
@@ -53,32 +77,50 @@ holder requests redemption
 authorized caller
   -> consumes payout limits or surplus allowances
   -> funds move to splits, projects, hooks, or direct recipients
+  -> same-terminal project payouts stay inside terminal accounting, may accrue fee-free surplus, and must not accidentally mint against the payer's own balance
 ```
 
-## Critical Invariants
-
-- Preview functions must remain behaviorally aligned with state-changing functions.
-- Data hooks run before settlement and may alter the economics; pay and cash-out hooks run after settlement. That phase boundary is intentional.
-- Reserved tokens and pending reserves affect supply-sensitive math even before distribution.
-- Terminal balances, fee accounting, and surplus calculations must agree. Any drift here contaminates every product repo.
-- Rulesets are time-ordered and approval-aware; deployment wrappers depend on predictable ID progression and activation semantics.
-- Permission checks are not a UI concern. They are part of protocol state transition validity.
+## Accounting Model
 
-## Where Complexity Lives
+This repo owns the canonical ledger for balances, fees, supply-sensitive reclaim math, payout limits, allowances, reserved tokens, and preview calculations. Other repos may wrap or influence these values, but none should duplicate them.
 
-- `JBMultiTerminal`, `JBTerminalStore`, and `JBController` form one accounting pipeline and are easiest to misunderstand when read separately.
-- Preview paths deliberately mirror state-changing paths; keeping them aligned is a permanent maintenance burden.
-- Fee-free surplus, held fees, and payout/allowance interactions create edge cases that are small in code size but large in blast radius.
+`JBTerminalStore` keeps terminal balances, payout-limit usage, and surplus-allowance usage. That state is terminal-scoped, but not all reset boundaries are the same: payout-limit usage is tracked by ruleset cycle number, while surplus-allowance usage is tracked by `ruleset.id`. Auto-cycling a duration-based ruleset does not reset allowance usage; queueing a new ruleset does.
 
-## Dependencies
+## Security Model
 
-- `nana-permission-ids-v6` for the shared permission namespace
-- OpenZeppelin, PRBMath, Chainlink, and Permit2 for standards and math utilities
+- `JBMultiTerminal`, `JBTerminalStore`, and `JBController` should be reviewed as one pipeline.
+- `JBTerminalStore` is shared logic but terminal-scoped state. Misunderstanding that split causes bad accounting assumptions.
+- Small changes in fee or surplus logic can affect every downstream repo.
+- Same-terminal project payouts, fee-free surplus capping, and migration cleanup are coupled. Changing one without the others creates fee bypasses or overcharges.
+- `allowOwnerMinting` is not a universal mint kill switch. Terminals, the current data hook, and hook-authorized callers can still mint through the controller path.
+- Hook ordering and preview-execution alignment are permanent maintenance obligations.
 
 ## Safe Change Guide
 
-- Start any nontrivial change by tracing both the preview path and the state-changing path.
-- Read downstream hook repos before changing hook interfaces or metadata expectations.
-- Keep fee logic, balance logic, and surplus logic in sync; "small" tweaks here are almost always ecosystem-wide changes.
-- When adding permissions or changing who is checked against a permission, update ecosystem docs and downstream assumptions immediately.
-- If a change seems local inside core, assume it is not until proven otherwise.
+- Trace both preview and state-changing paths for any nontrivial change.
+- Read downstream hook repos before changing hook metadata or interface expectations.
+- Keep fee logic, balance logic, reclaim math, and surplus math synchronized.
+- If you change payouts between projects on the same terminal, re-check self-pay revert behavior, fee-free surplus accumulation, and the post-pay cap against recorded balance.
+- If you change ruleset rollover semantics, re-check which usage counters reset on cycle progression versus new ruleset IDs.
+- If permissions change, update shared docs and downstream assumptions at the same time.
+
+## Canonical Checks
+
+- fee-free surplus and same-terminal payout behavior:
+  `test/TestFeeFreeCashOutBypass.sol`
+- migration and terminal-accounting continuity:
+  `test/TestTerminalMigration.sol`
+- ruleset ordering and transition behavior:
+  `test/RulesetTransitions.t.sol`
+
+## Source Map
+
+- `src/JBController.sol`
+- `src/JBMultiTerminal.sol`
+- `src/JBTerminalStore.sol`
+- `src/JBDirectory.sol`
+- `src/JBRulesets.sol`
+- `src/JBPermissions.sol`
+- `test/TestFeeFreeCashOutBypass.sol`
+- `test/TestTerminalMigration.sol`
+- `test/RulesetTransitions.t.sol`

package/AUDIT_INSTRUCTIONS.md

@@ -2,7 +2,7 @@
 
 This is the core Juicebox V6 protocol. Most ecosystem invariants reduce to this repo eventually.
 
-## Objective
+## Audit Objective
 
 Find issues that:
 - break terminal solvency or internal accounting
@@ -45,7 +45,7 @@ That order mirrors how most high-severity issues emerge:
 - tokens are minted or burned
 - permissions and price context decide whether the move was legitimate
 
-## System Model
+## Security Model
 
 Core roles:
 - `JBMultiTerminal`: holds funds and executes pay, payout, cash-out, allowance, and fee-processing flows
@@ -67,6 +67,23 @@ Core ordering to keep in mind:
 - controller mint and burn operations happen around terminal flows, not as a separate settlement layer
 - hooks can turn what looks like a simple pay or cash-out into a multi-contract composition
 
+## Roles And Privileges
+
+| Role | Powers | How constrained |
+|------|--------|-----------------|
+| Project owner and operators | Configure rulesets, limits, routing, and permissions | Must stay inside the explicit permission model |
+| Terminal | Hold funds and execute settlement | Must remain solvent relative to internal accounting |
+| Controller | Mint, burn, and manage project lifecycle | Must not bypass project-scoped authorization |
+| Hooks and splits | Extend pay and cash-out behavior | Must not make previews and accounting irreconcilable |
+
+## Integration Assumptions
+
+| Dependency | Assumption | What breaks if wrong |
+|------------|------------|----------------------|
+| Price feeds | Currency conversions are fresh and coherent | Cross-currency flows misprice |
+| Hook ecosystem | External hooks obey documented interfaces | Settlement becomes unsafe after control transfer |
+| Directory and migration surfaces | Canonical routing changes are authentic | Funds or permissions shift to the wrong place |
+
 ## Critical Invariants
 
 1. Terminal solvency
@@ -93,22 +110,7 @@ When fee payment is deferred, later replenishment or migration behavior must not
 8. Preview coherence
 `previewPayFor` and `previewCashOutFrom` should not become meaningfully inconsistent with execution in ways downstream repos can exploit.
 
-## Threat Model
-
-Prioritize:
-- hook-driven reentrancy or state-ordering issues
-- price-feed failure and cross-currency conversions
-- fee-processing failure paths
-- migration and feeless-address edge cases
-- ruleset-boundary timing attacks
-- wildcard or root permission escalation
-
-The highest-yield attacker mindsets here are:
-- a malicious hook that receives control after balances move but before the full user flow is conceptually finished
-- a project owner exploiting migration, limits, or feeless settings rather than breaking access control directly
-- a cross-currency user extracting value from rounding or stale price conversions
-
-## Hotspots
+## Attack Surfaces
 
 - `pay`, `cashOutTokensOf`, `sendPayoutsOf`, and `useAllowanceOf`
 - `preview*` paths when downstream repos treat them as execution truth
@@ -117,34 +119,19 @@ The highest-yield attacker mindsets here are:
 - controller migration and terminal migration
 - `setPermissionsFor` and any wildcard semantics
 
-## Sequences Worth Replaying
-
-1. `pay` with a data hook that returns altered weight and hook specs, then re-enter through a pay hook.
-2. `cashOutTokensOf` when `useTotalSurplusForCashOuts` or cross-terminal surplus logic matters.
-3. `sendPayoutsOf` into splits that route to another project, hook, or failing beneficiary.
-4. held-fee accumulation -> migration or balance depletion -> `processHeldFeesOf`.
-5. permission grants involving operators, wildcard project IDs, or later controller changes.
+Replay these sequences:
+1. `pay` with a data hook that alters weight or hook specs and then reenters through a pay hook
+2. `cashOutTokensOf` when cross-terminal surplus and `useTotalSurplusForCashOuts` matter
+3. `sendPayoutsOf` into splits that route to another project, hook, or failing beneficiary
+4. held-fee accumulation followed by migration or balance depletion
+5. permission grants involving operators, wildcard project IDs, or later controller changes
 
-## Finding Bar
+## Accepted Risks Or Behaviors
 
-The best findings in this repo usually prove one of these:
-- the store records more value than the terminal can safely honor
-- a limit is consumed too late, after externally controlled code can already profit
-- a migration or held-fee edge path changes who ultimately bears an obligation
-- permissions that look project-scoped become ecosystem-relevant through wildcard or routing semantics
+- Hooks are intentionally powerful extension points; safety depends on clear sequencing and bounded trust, not on avoiding composition.
 
-## Build And Verification
+## Verification
 
-Standard workflow:
 - `npm install`
 - `forge build`
 - `forge test`
-
-The current test suite already targets:
-- flash-loan and economic exploits
-- permissions invariants
-- ruleset transitions
-- fee and migration edge cases
-- multi-token and cross-currency surplus behavior
-
-The highest-value findings in this repo are the ones that make downstream hooks or deployers unsafe even when those repos are otherwise correct.

package/README.md

@@ -3,7 +3,12 @@
 `@bananapus/core-v6` is the core protocol package for Juicebox on EVM chains. It defines projects, rulesets, terminals, permissions, token issuance, cash outs, splits, price feeds, and the accounting surfaces that the rest of the V6 ecosystem builds on.
 
 Docs: <https://docs.juicebox.money>
-Architecture: [ARCHITECTURE.md](./ARCHITECTURE.md)
+Architecture: [ARCHITECTURE.md](./ARCHITECTURE.md)  
+User journeys: [USER_JOURNEYS.md](./USER_JOURNEYS.md)  
+Skills: [SKILLS.md](./SKILLS.md)  
+Risks: [RISKS.md](./RISKS.md)  
+Administration: [ADMINISTRATION.md](./ADMINISTRATION.md)  
+Audit instructions: [AUDIT_INSTRUCTIONS.md](./AUDIT_INSTRUCTIONS.md)
 
 ## Overview
 
@@ -18,7 +23,7 @@ The core package provides:
 - operator permissions through `JBPermissions`
 - on-chain price-feed routing through `JBPrices`
 
-Use this repo when you need the canonical protocol invariant. Do not duplicate its logic in downstream packages unless the repo is explicitly intended to wrap or extend the core surface.
+Use this repo when you need the canonical protocol accounting and execution surfaces. Do not duplicate its logic in downstream packages unless the repo is explicitly intended to wrap or extend the core surface.
 
 If you only read one repo before auditing the rest of the ecosystem, read this one.
 
@@ -31,7 +36,7 @@ The core protocol is easiest to reason about in four layers:
 3. accounting: `JBTerminalStore`
 4. permissions and external context: `JBPermissions`, `JBPrices`, feeless-address and deadline helpers
 
-Most integrations touch only layer 2. Most economically important bugs leak through layer 3.
+Many integrations touch only layer 2, while many economically important bugs are easiest to understand from layer 3.
 
 The shortest path through the repo is:
 
@@ -78,6 +83,14 @@ The shortest path through the repo is:
 
 When in doubt, read the state-owning contract before the contract that merely forwards into it.
 
+## High-Signal Tests
+
+1. `test/TestPayBurnRedeemFlow.sol`
+2. `test/TestTerminalPreviewParity.sol`
+3. `test/invariants/TerminalStoreInvariant.t.sol`
+4. `test/invariants/RulesetsInvariant.t.sol`
+5. `test/audit/CrossTerminalSurplusSpoof.t.sol`
+
 ## Install
 
 ```bash
@@ -125,3 +138,9 @@ script/
 - fee, surplus, and reclaim logic are economically sensitive and remain high-priority audit surfaces
 
 The fastest way to misunderstand V6 is to treat the core contracts like a simple crowdfunding terminal. They are closer to a configurable accounting and settlement substrate.
+
+## For AI Agents
+
+- Start with `JBController`, `JBMultiTerminal`, and `JBTerminalStore`; do not summarize core behavior from helper libraries alone.
+- Distinguish controller configuration from terminal execution and from store accounting.
+- If a behavior involves hooks, inspect the hook repo too before treating the preview or execution path as canonical.

package/RISKS.md

@@ -144,6 +144,7 @@ No `ReentrancyGuard` is used. The system relies on state ordering and the `Inade
 - **No state modification risk.** Preview functions cannot change balances, mint/burn tokens, or consume limits. They are safe to call from any context.
 - **Preview-execution divergence.** Preview functions and their corresponding real operations share computation logic but execute in different contexts. `previewPayFor` calls `STORE.previewPayFrom` which invokes the data hook's `beforePayRecordedWith` via `staticcall`. The real `pay` path invokes the same hook but state changes between preview and execution (other payments, cash outs, ruleset transitions) can change the data hook's response. Callers should treat preview results as estimates, not guarantees — especially for projects with stateful data hooks.
 - **Gas griefing via data hooks in previews.** Since `previewPayFor` and `previewCashOutFrom` invoke data hooks, a gas-expensive data hook can make preview calls prohibitively expensive. This affects frontends and indexers that rely on preview functions for quote display. Unlike the real operations (which have economic incentive to complete), preview calls have no built-in gas limit on the data hook invocation.
+- **Not all read-only cash-out estimates are hook-aware.** `JBTerminalStore.currentReclaimableSurplusOf` and `currentTotalReclaimableSurplusOf` intentionally do not run the data hook. They use the current ruleset's plain `cashOutTaxRate` and the controller-reported total supply, so they cannot reflect hook-provided overrides such as omnichain or custom `effectiveTotalSupply` logic. Integrators should use `previewCashOutFrom` or simulate `recordCashOutFor` when they need an estimate that matches hook-adjusted execution more closely.
 
 ## 7. Integration Risks
 
@@ -174,6 +175,12 @@ No `ReentrancyGuard` is used. The system relies on state ordering and the `Inade
 
 - `JBTerminalStore.recordAddedBalanceFor` has **no access control**. Any address can call it. The balance is keyed by `msg.sender` (the terminal address), so only a terminal can inflate its own recorded balance. This is safe as long as all terminals correctly track their actual holdings. A buggy or malicious terminal implementation could call `recordAddedBalanceFor` without actually receiving tokens, inflating the recorded balance above actual holdings.
 
+### Split and Owner-Payout Failure Semantics
+
+- **Failed split payouts still consume payout limit.** Core decrements balance and increments used payout limit before downstream split transfers are attempted. If a split payout later fails, the amount is returned to project balance, but the payout limit consumption is not rewound. This is intentional fail-open accounting: one bad split should not revert the whole payout fanout, but operators should not assume "returned to balance" also means "payout limit restored".
+- **Failed owner transfers also consume payout limit.** The leftover owner payout path uses the same pattern as split payouts: if the owner transfer fails, funds return to project balance, but the payout limit remains consumed for that cycle.
+- **Split hook reverts after token transfer strand tokens at the hook.** In reserved-token distributions, the controller transfers tokens to the split hook before calling `processSplitWith`. If that hook call then reverts, core emits `SplitHookReverted` but does not claw the tokens back. Integrators should treat split hooks as token-custody recipients, not pure callbacks.
+
 ## 8. Accepted Behaviors
 
 ### 8.1 Cross-terminal surplus is an explicit trust boundary

package/SKILLS.md

@@ -3,19 +3,23 @@
 ## Use This File For
 
 - Use this file when the task touches protocol core behavior: payments, cash-outs, terminals, controller actions, rulesets, splits, tokens, permissions, or price feeds.
-- Start here if you know the issue is in core, then open the specific contract that owns the state transition you are debugging.
+- Start here if you know the issue is in core, then identify the single state transition being changed before reading broadly. In this repo, most bugs reduce to controller lifecycle, terminal execution, store accounting, or ruleset state.
 
 ## Read This Next
 
 | If you need... | Open this next |
 |---|---|
-| Repo overview and protocol framing | [`README.md`](./README.md) |
+| Repo overview and protocol framing | [`README.md`](./README.md), [`ARCHITECTURE.md`](./ARCHITECTURE.md) |
 | Controller and project lifecycle behavior | [`src/JBController.sol`](./src/JBController.sol), [`src/JBProjects.sol`](./src/JBProjects.sol), [`src/JBTokens.sol`](./src/JBTokens.sol) |
 | Payment, cash-out, surplus, and fee accounting | [`src/JBMultiTerminal.sol`](./src/JBMultiTerminal.sol), [`src/JBTerminalStore.sol`](./src/JBTerminalStore.sol), [`src/JBFundAccessLimits.sol`](./src/JBFundAccessLimits.sol) |
 | Rulesets, permissions, directory, and prices | [`src/JBRulesets.sol`](./src/JBRulesets.sol), [`src/JBPermissions.sol`](./src/JBPermissions.sol), [`src/JBDirectory.sol`](./src/JBDirectory.sol), [`src/JBPrices.sol`](./src/JBPrices.sol) |
 | Shared math, metadata parsing, and constants | [`src/libraries/`](./src/libraries/), [`src/structs/`](./src/structs/), [`src/enums/`](./src/enums/) |
 | Periphery helpers and deployment | [`src/periphery/`](./src/periphery/), [`script/Deploy.s.sol`](./script/Deploy.s.sol), [`script/DeployPeriphery.s.sol`](./script/DeployPeriphery.s.sol) |
-| Invariants, fork tests, and security/economic regressions | [`test/formal/`](./test/formal/), [`test/fork/`](./test/fork/), [`test/audit/`](./test/audit/), [`test/helpers/`](./test/helpers/) |
+| Payment and cash-out entrypoint surface | [`references/entrypoints.md`](./references/entrypoints.md) |
+| Packed metadata, gotchas, errors, and hook return shapes | [`references/types-errors-events.md`](./references/types-errors-events.md) |
+| Cash-out, payment, and terminal accounting proofs | [`test/TestPayBurnRedeemFlow.sol`](./test/TestPayBurnRedeemFlow.sol), [`test/TestCashOut.sol`](./test/TestCashOut.sol), [`test/TestMultiTerminalSurplus.sol`](./test/TestMultiTerminalSurplus.sol), [`test/TestTerminalPreviewParity.sol`](./test/TestTerminalPreviewParity.sol) |
+| Permissions, rulesets, and invariants | [`test/TestPermissions.sol`](./test/TestPermissions.sol), [`test/PermissionEscalation.t.sol`](./test/PermissionEscalation.t.sol), [`test/TestRulesetQueueing.sol`](./test/TestRulesetQueueing.sol), [`test/ComprehensiveInvariant.t.sol`](./test/ComprehensiveInvariant.t.sol), [`test/PermissionsInvariant.t.sol`](./test/PermissionsInvariant.t.sol) |
+| Economic, exploit, and weird-token coverage | [`test/EconomicSimulation.t.sol`](./test/EconomicSimulation.t.sol), [`test/CoreExploitTests.t.sol`](./test/CoreExploitTests.t.sol), [`test/FlashLoanAttacks.t.sol`](./test/FlashLoanAttacks.t.sol), [`test/WeirdTokenTests.t.sol`](./test/WeirdTokenTests.t.sol), [`test/AuditFixes.t.sol`](./test/AuditFixes.t.sol) |
 
 ## Repo Map
 
@@ -40,5 +44,13 @@ The core Juicebox V6 protocol on EVM: a modular system for launching treasury-ba
 ## Working Rules
 
 - Open source before relying on any summary here. This skill is a router, not the ground truth.
-- For runtime bugs, start from the terminal/controller/store contract that owns the state transition.
+- For runtime bugs, start from the terminal/controller/store contract that owns the state transition. Most user-facing behavior is computed there, not in helpers or interfaces.
+- `JBMultiTerminal` and `JBTerminalStore` are a pair. If you change one without re-deriving the other’s assumptions, expect accounting drift.
+- Payment and cash-out previews are not optional convenience APIs. `previewPayFrom` and `previewCashOutFrom` are part of the protocol surface and need to stay aligned with execution semantics.
+- Payout limits reset by ruleset cycle number, but surplus allowances are keyed by `ruleset.id`, not cycle number. Do not assume they reset together.
+- Fee handling is nuanced. Re-check held fees, fee-free surplus tracking, and feeless-address behavior before changing payout or cash-out logic.
+- Fee-free surplus is a bounded anti-bypass mechanism, not a generic exemption bucket. Re-check lifecycle capping and migration/reset behavior before changing cash-out or payout flows.
 - For config or weird value-shape issues, open `references/types-errors-events.md` before changing structs or metadata packing.
+- Terminal previews, accounting, and fee behavior are tightly coupled. If one changes, assume at least one of the others needs verification.
+- Long-lived rulesets have a real cache boundary. If the issue involves extreme cycle counts, inspect `JBRulesets.updateRulesetWeightCache(...)` and the surrounding tests before touching weight math.
+- When a bug smells cross-repo, prove it is not really coming from a hook, router, or downstream deployer before patching core.