@bananapus/permission-ids-v6 0.0.17 → 0.0.18

package/ADMINISTRATION.md

@@ -1,147 +1,62 @@
 # Administration
 
-Admin privileges and their scope in nana-permission-ids-v6.
-
 ## At A Glance
 
 | Item | Details |
-|------|---------|
-| Scope | Reference library for the permission IDs consumed across the Juicebox V6 ecosystem. No contract in this repo has mutable runtime state. |
-| Operators | Maintainers who change the constant list in source and downstream repos that consume those constants. |
-| Highest-risk actions | Renumbering or repurposing a permission ID that downstream contracts already depend on. |
-| Recovery posture | Runtime admin recovery does not apply here. If the constants are wrong, downstream code and docs have to be updated and redeployed against the corrected source. |
-
-## Routine Operations
-
-- Treat `JBPermissionIds.sol` as a coordination artifact across repos, not a place for casual edits.
-- When adding a new permission, update the source library and the dependent repo docs together so operator guidance does not drift from code.
-- Re-check downstream permission assumptions after any change because multiple repos gate admin behavior through this single numbering scheme.
+| --- | --- |
+| Scope | Shared permission ID namespace for the wider ecosystem |
+| Control posture | Source-level coordination only |
+| Highest-risk actions | Reordering or reusing IDs already assumed by deployed contracts |
+| Recovery posture | Requires downstream code changes and redeployments where relevant |
+
+## Purpose
+
+`nana-permission-ids-v6` has no runtime admin surface. Its control significance is source-level: it defines the shared permission namespace used by the rest of the ecosystem.
+
+## Control Model
+
+- No owner
+- No runtime governance
+- No mutable onchain state
+- Source-code level coordination only
+
+## Roles
 
-## One-Way Or High-Risk Actions
+| Role | How Assigned | Scope | Notes |
+| --- | --- | --- | --- |
+| Maintainer | Source-code author | Ecosystem-wide | Can add or reorder constants only by editing and redeploying dependent code |
 
-- Changing an existing numeric assignment can silently invalidate permission checks in dependent repos.
-- The library itself has no admin keys, but stale docs around it can mislead operators about real powers elsewhere in the ecosystem.
+## Privileged Surfaces
 
-## Recovery Notes
+There are no privileged runtime functions. The only meaningful changes are source changes to `JBPermissionIds.sol`.
 
-- If the permission map drifts from deployed contracts, the fix is coordinated source and documentation updates in the dependent repos, plus redeployment where the old numeric assumptions are already live.
-- There is no on-chain migration knob in this repo because it only ships compile-time constants.
+## Immutable And One-Way
 
-## Overview
+- Once deployed contracts depend on a given ID mapping, that mapping is effectively immutable for those deployments.
+- Reusing or reordering IDs is a cross-repo breaking change.
 
-This repo defines permission ID constants. It contains no admin functions itself -- it is a reference library for the permission system used across the Juicebox V6 ecosystem. The constants in `JBPermissionIds` are consumed by contracts in nana-core-v6, nana-721-hook-v6, nana-buyback-hook-v6, nana-router-terminal-v6, and nana-suckers-v6 to gate privileged operations.
+## Operational Notes
 
-There are no ownable contracts, no upgrade mechanisms, and no mutable state. The library compiles to inline constants.
+- Add new permission IDs append-only.
+- Update downstream docs and call sites in the same change set.
+- Treat permission ID changes as protocol changes, not refactors.
 
-## Permission IDs
+## Machine Notes
 
-All 40 defined permission IDs and what they control:
+- Do not infer semantic compatibility from matching names if numeric IDs changed.
+- Treat `src/JBPermissionIds.sol` as append-only unless a breaking ecosystem-wide migration is intentional.
+- If docs and code disagree on a permission number, trust the code and update the docs before further admin review.
 
-| ID | Constant | Used By | What It Controls |
-|----|----------|---------|-----------------|
-| 1 | `ROOT` | All contracts (via `JBPermissions`) | Grants every permission. See [ROOT Permission](#root-permission). |
-| 2 | `QUEUE_RULESETS` | nana-core (`JBController`) | `JBController.queueRulesetsOf` -- queue new rulesets for a project. |
-| 3 | `LAUNCH_RULESETS` | nana-core (`JBController`) | `JBController.launchRulesetsFor` -- launch a project's initial rulesets. Also requires `SET_TERMINALS` (ID 15). |
-| 4 | `CASH_OUT_TOKENS` | nana-core (`JBMultiTerminal`) | `JBMultiTerminal.cashOutTokensOf` -- redeem tokens for surplus. Checked against the **token holder**, not the project owner. |
-| 5 | `SEND_PAYOUTS` | nana-core (`JBMultiTerminal`) | `JBMultiTerminal.sendPayoutsOf` -- distribute payouts to splits. |
-| 6 | `MIGRATE_TERMINAL` | nana-core (`JBMultiTerminal`) | `JBMultiTerminal.migrateBalanceOf` -- migrate a project's balance to another terminal. |
-| 7 | `SET_PROJECT_URI` | nana-core (`JBController`) | `JBController.setUriOf` -- set project metadata URI. |
-| 8 | `DEPLOY_ERC20` | nana-core (`JBController`) | `JBController.deployERC20For` -- deploy a new ERC-20 token for a project. |
-| 9 | `SET_TOKEN` | nana-core (`JBController`) | `JBController.setTokenFor` -- set an existing ERC-20 token for a project. |
-| 10 | `MINT_TOKENS` | nana-core (`JBController`) | `JBController.mintTokensOf` -- mint new project tokens. Only effective when the current ruleset allows owner minting. |
-| 11 | `BURN_TOKENS` | nana-core (`JBController`) | `JBController.burnTokensOf` -- burn tokens. Checked against the **token holder**. |
-| 12 | `CLAIM_TOKENS` | nana-core (`JBController`) | `JBController.claimTokensFor` -- claim internal credits as ERC-20. Checked against the **token holder**. |
-| 13 | `TRANSFER_CREDITS` | nana-core (`JBController`) | `JBController.transferCreditsFrom` -- transfer internal credits. Checked against the **token holder**. |
-| 14 | `SET_CONTROLLER` | nana-core (`JBDirectory`) | `JBDirectory.setControllerOf` -- set a project's controller. |
-| 15 | `SET_TERMINALS` | nana-core (`JBDirectory`) | `JBDirectory.setTerminalsOf` -- set a project's terminals. **Warning:** can remove the primary terminal. |
-| 16 | `ADD_TERMINALS` | nana-core (`JBDirectory`) | `JBDirectory.setPrimaryTerminalOf` -- add a new terminal when `setPrimaryTerminalOf` implicitly adds it. |
-| 17 | `SET_PRIMARY_TERMINAL` | nana-core (`JBDirectory`) | `JBDirectory.setPrimaryTerminalOf` -- set the primary terminal for a token. |
-| 18 | `USE_ALLOWANCE` | nana-core (`JBMultiTerminal`) | `JBMultiTerminal.useAllowanceOf` -- spend surplus allowance to an arbitrary address. |
-| 19 | `SET_SPLIT_GROUPS` | nana-core (`JBController`) | `JBController.setSplitGroupsOf` -- configure payout and reserved token splits. |
-| 20 | `ADD_PRICE_FEED` | nana-core (`JBController`) | `JBController.addPriceFeedFor` (which internally calls `JBPrices.addPriceFeedFor`) -- add a price feed for a project. |
-| 21 | `ADD_ACCOUNTING_CONTEXTS` | nana-core (`JBMultiTerminal`) | `JBMultiTerminal.addAccountingContextsFor` -- add accepted tokens to a terminal. |
-| 22 | `SET_TOKEN_METADATA` | nana-core (`JBController`) | `JBController.setTokenMetadataOf` -- set a project token's name and symbol. |
-| 23 | `SIGN_FOR_ERC20` | nana-core (`JBERC20`) | Sign messages on behalf of a project's ERC-20 token via ERC-1271. Used for Etherscan contract verification and other off-chain signature validation. |
-| 24 | `ADJUST_721_TIERS` | nana-721-hook (`JB721TiersHook`) | `JB721TiersHook.adjustTiers` -- add or remove NFT tiers. |
-| 25 | `SET_721_METADATA` | nana-721-hook (`JB721TiersHook`) | `JB721TiersHook.setMetadata` -- set NFT metadata URIs. |
-| 26 | `MINT_721` | nana-721-hook (`JB721TiersHook`) | `JB721TiersHook.mintFor` -- manually mint NFTs to a beneficiary. |
-| 27 | `SET_721_DISCOUNT_PERCENT` | nana-721-hook (`JB721TiersHook`) | `JB721TiersHook.setDiscountPercentOf` -- set discount percent on NFT tiers. |
-| 28 | `SET_BUYBACK_TWAP` | nana-buyback-hook (`JBBuybackHook`) | `JBBuybackHook.setTwapWindowOf` -- configure the TWAP oracle window. |
-| 29 | `SET_BUYBACK_POOL` | nana-buyback-hook (`JBBuybackHook`) | `JBBuybackHook.setPoolFor` -- set the Uniswap pool for buybacks. |
-| 30 | `SET_BUYBACK_HOOK` | nana-buyback-hook (`JBBuybackHookRegistry`) | `JBBuybackHookRegistry.setHookFor` and `lockHookFor` -- configure and permanently lock the buyback hook. |
-| 31 | `SET_ROUTER_TERMINAL` | nana-router-terminal (`JBRouterTerminalRegistry`) | `JBRouterTerminalRegistry.setTerminalFor` and `lockTerminalFor` -- configure and permanently lock the router terminal. |
-| 32 | `MAP_SUCKER_TOKEN` | nana-suckers (`JBSucker`) | `JBSucker.mapToken` -- map an ERC-20 to its remote chain counterpart. Immutable once the outbox tree has entries. |
-| 33 | `DEPLOY_SUCKERS` | nana-suckers (`JBSuckerRegistry`) | `JBSuckerRegistry.deploySuckersFor` -- deploy sucker contracts for cross-chain bridging. |
-| 34 | `SUCKER_SAFETY` | nana-suckers (`JBSucker`) | `JBSucker.enableEmergencyHatchFor` -- enable the emergency hatch to recover stuck tokens. |
-| 35 | `SET_SUCKER_DEPRECATION` | nana-suckers (`JBSucker`) | `JBSucker.setDeprecation` -- set deprecation status (ENABLED, DEPRECATION_PENDING, SENDING_DISABLED, DEPRECATED). |
-| 36 | `HIDE_TOKENS` | revnet-core (`REVHiddenTokens`) | `REVHiddenTokens.hideTokensOf` -- hide (burn) tokens on behalf of a holder. Checked against the **token holder**. |
-| 37 | `OPEN_LOAN` | revnet-core (`REVLoans`) | `REVLoans.borrowFrom` -- open a loan on behalf of a token holder. Checked against the **token holder**. |
-| 38 | `REALLOCATE_LOAN` | revnet-core (`REVLoans`) | `REVLoans.reallocateCollateralFromLoan` -- reallocate loan collateral on behalf of a loan NFT owner. Checked against the **loan NFT owner**. |
-| 39 | `REPAY_LOAN` | revnet-core (`REVLoans`) | `REVLoans.repayLoan` -- repay a loan on behalf of a loan NFT owner. Checked against the **loan NFT owner**. |
-| 40 | `REVEAL_TOKENS` | revnet-core (`REVHiddenTokens`) | `REVHiddenTokens.revealTokensOf` -- reveal (re-mint) hidden tokens on behalf of a holder. Checked against the **token holder**. |
-
-IDs 0 and 41-255 are unused. ID 0 is reserved and cannot be set. IDs 41-255 are available for future ecosystem extensions.
-
-## ROOT Permission
-
-`ROOT` (ID 1) is a superuser permission. When an operator has ROOT for a given project, `JBPermissions` treats every permission check as passing for that project. It is the only permission that grants blanket access.
-
-Restrictions enforced by `JBPermissions`:
-
-- **Cannot be granted for the wildcard project ID (0).** Attempting to set ROOT with `projectId = 0` reverts with `JBPermissions_CantSetRootPermissionForWildcardProject()`. This prevents a single operator from controlling all projects owned by an account.
-- **ROOT operators cannot grant ROOT to others.** A ROOT operator can call `setPermissionsFor` on behalf of the account, but the new permission set must not include ROOT and must not target the wildcard project ID.
-- **ROOT is scoped per project.** Having ROOT for project 5 does not grant any permissions for project 6.
-
-## Wildcard Project ID
-
-When permissions are granted with `projectId = 0`, they apply to **every project** owned by the granting account. This is checked by `JBPermissions` as a fallback: if the operator does not have a specific permission for the target project, the contract checks whether the operator has that permission for `projectId = 0`.
-
-ROOT cannot be set for the wildcard project ID. All other permissions can.
-
-## How Permissions Are Checked
-
-Permissions are stored in `JBPermissions` as a 256-bit packed integer per (operator, account, projectId) tuple:
-
-```
-permissionsOf[operator][account][projectId] => uint256 (packed bits)
-```
-
-Each bit position corresponds to a permission ID. When a contract checks whether an operator has a permission, it calls `JBPermissions.hasPermission(operator, account, projectId, permissionId, includeRoot, includeWildcardProjectId)`, which:
+## Recovery
 
-1. Checks whether the operator has ROOT (bit 1) for the specific project -- if so, returns true.
-2. If `includeWildcardProjectId`, checks whether the operator has ROOT (bit 1) for the wildcard project (`projectId = 0`) -- if so, returns true.
-3. Checks whether the specific permission bit is set for the specific project -- if so, returns true.
-4. If `includeWildcardProjectId`, checks whether the specific permission bit is set for the wildcard project (`projectId = 0`) -- if so, returns true.
+- There is no runtime recovery surface.
+- A bad ID assignment is fixed only by downstream code changes and redeployments where needed.
 
-Steps 1-2 are skipped if `includeRoot` is false. Steps 2 and 4 are skipped if `includeWildcardProjectId` is false.
+## Admin Boundaries
 
-Contracts that use this system inherit from `JBPermissioned`, which provides the `_requirePermissionFrom(account, projectId, permissionId)` modifier. This modifier passes if the caller is the account itself or has the required permission via `JBPermissions`.
+- Nobody can patch deployed contracts to reinterpret old permission bits.
+- This repo cannot grant, revoke, or inspect permissions by itself.
 
-## High-Risk Permissions
+## Source Map
 
-Some permissions warrant extra caution when granting:
-
-- **`ROOT` (1):** Full access to all gated functions for a project.
-- **`SET_TERMINALS` (15):** Can remove the primary terminal, breaking payments and cashouts.
-- **`USE_ALLOWANCE` (18):** Can send surplus funds to any address.
-- **`SET_BUYBACK_HOOK` (30):** Can permanently lock the buyback hook configuration.
-- **`SET_ROUTER_TERMINAL` (31):** Can permanently lock the router terminal configuration.
-- **`MINT_TOKENS` (10):** Can inflate token supply (subject to ruleset allowing owner minting).
-
-## Holder vs. Owner Permissions
-
-Most permissions are checked against the **project owner** (the account that owns the project NFT). Several permissions are instead checked against the **token holder** or **loan NFT owner**:
-
-| Permission | Checked Against |
-|-----------|----------------|
-| `CASH_OUT_TOKENS` (4) | Token holder |
-| `BURN_TOKENS` (11) | Token holder |
-| `CLAIM_TOKENS` (12) | Token holder |
-| `TRANSFER_CREDITS` (13) | Token holder |
-| `HIDE_TOKENS` (36) | Token holder |
-| `OPEN_LOAN` (37) | Token holder |
-| `REALLOCATE_LOAN` (38) | Loan NFT owner |
-| `REPAY_LOAN` (39) | Loan NFT owner |
-| `REVEAL_TOKENS` (40) | Token holder |
-
-This means a token holder can grant an operator permission to cash out, burn, claim, transfer, hide, reveal, or borrow against their own tokens -- independent of the project owner's permissions. Loan NFT owners can similarly grant operators permission to repay or reallocate their loans.
+- `src/JBPermissionIds.sol`

package/ARCHITECTURE.md

@@ -2,41 +2,52 @@
 
 ## Purpose
 
-`nana-permission-ids-v6` is the shared permission namespace for the ecosystem. It exists so every repo can agree on what permission bit means what.
+`nana-permission-ids-v6` is the shared permission namespace for the V6 ecosystem. It ensures every repo agrees on what each permission bit means when interacting with `JBPermissions`.
 
-## Boundaries
+## System Overview
 
-- This repo intentionally contains almost no logic.
-- Its value is stability, not sophistication.
-- The constants here are coupled to checks spread across many sibling repos.
+The repo intentionally contains almost no logic. Its value is stable coordination across the stack. Other repos import `JBPermissionIds` and compare permission bits against these constants.
 
-## Main Components
+## Core Invariants
 
-| Component | Responsibility |
-| --- | --- |
-| `JBPermissionIds` | Defines the canonical `uint8` IDs used with `JBPermissions` |
+- Existing IDs must remain stable once consumed by deployed contracts or integrations.
+- New IDs should be appended intentionally, not reused or repurposed.
+- Numeric stability matters more than naming convenience; changing a value while keeping a familiar name is still a protocol break.
+- `ROOT` must stay aligned with `JBPermissions` expectations in `nana-core-v6`.
 
-## Runtime Model
+## Modules
 
-There is no runtime state. Other repos import this library and compare permission bits against these constants.
+| Module | Responsibility | Notes |
+| --- | --- | --- |
+| `JBPermissionIds` | Defines canonical `uint8` permission IDs | Entire repo value |
 
-## Critical Invariants
+## Trust Boundaries
 
-- Existing IDs must remain stable once consumed by deployed contracts and integrations.
-- New IDs should only be appended intentionally; repurposing an old ID is ecosystem-breaking.
-- `ROOT` stays special and must remain consistent with `JBPermissions` expectations.
+- This repo has no runtime authority by itself.
+- It is semantically coupled to `nana-core-v6` and every repo that performs permission checks.
 
-## Where Complexity Lives
+## Critical Flows
 
-- The code is trivial; the coordination burden is not.
-- Mistakes here look like harmless renames until they land in downstream permission checks.
+There is no runtime flow. Other repos import the library and use the constants in permission checks.
 
-## Dependencies
+## Accounting Model
 
-- Semantically coupled to `nana-core-v6` and every repo that performs permission checks
+No accounting lives here.
+
+## Security Model
+
+- The code is trivial, but the coordination burden is not.
+- A seemingly harmless rename or reorder here can silently break permissions across the ecosystem.
+- This repo's real blast radius comes from deployed contracts that have already baked these values into their runtime behavior.
+- There is no meaningful local runtime test surface in this repo today; correctness is mostly enforced by downstream compatibility and reviewer discipline.
 
 ## Safe Change Guide
 
-- Treat every ID change as a cross-repo protocol change.
-- When adding a permission, update the docs and downstream repos in the same change set.
-- Do not add convenience aliases that obscure the one-to-one mapping between bit position and meaning.
+- Treat any ID change as a cross-repo protocol change.
+- When adding a permission, update downstream repos and docs in the same change set.
+- Do not add aliases that obscure the one-to-one mapping between bit position and meaning.
+
+## Source Map
+
+- `src/JBPermissionIds.sol`
+- `references/runtime.md`

package/AUDIT_INSTRUCTIONS.md

@@ -2,7 +2,7 @@
 
 This repo is only permission ID constants, but the constants are security-critical because many repos key access control off them.
 
-## Objective
+## Audit Objective
 
 Find issues that:
 - assign duplicate IDs to different semantic permissions
@@ -14,6 +14,24 @@ Find issues that:
 In scope:
 - `src/JBPermissionIds.sol`
 
+## Start Here
+
+1. `src/JBPermissionIds.sol`
+2. downstream consumers in `nana-core-v6` and `revnet-core-v6`
+
+## Security Model
+
+This repo defines canonical numeric IDs that other repos treat as part of their permission model.
+- the file is small, but stale renumbering or collisions can silently widen or break access control elsewhere
+- correctness depends on cross-repo alignment, not local logic alone
+
+## Integration Assumptions
+
+| Dependency | Assumption | What breaks if wrong |
+|------------|------------|----------------------|
+| `nana-core-v6` | ERC-20 signature delegation still uses the documented ID | Signature authority checks mismatch |
+| `revnet-core-v6` | Loan and hidden-token permissions still use the documented IDs | Delegated actions widen, fail, or misroute |
+
 ## Critical Invariants
 
 1. Each permission semantic has one stable numeric ID.
@@ -22,14 +40,13 @@ In scope:
 4. ID 23 (`SIGN_FOR_ERC20`) is consumed by `nana-core-v6` (`JBERC20`) — verify it matches the value used for ERC-1271 signature delegation.
 5. IDs 36-40 (revnet-core delegation: `HIDE_TOKENS`, `OPEN_LOAN`, `REALLOCATE_LOAN`, `REPAY_LOAN`, `REVEAL_TOKENS`) are consumed by `revnet-core-v6` — verify they match the values used in `REVHiddenTokens` and `REVLoans`.
 
-## Threat Model
+## Attack Surfaces
 
-Prioritize stale or inconsistent constants, especially where wildcard grants or deployer permissions depend on a specific numeric value.
+- duplicate or reordered constants
+- stale cross-repo assumptions
+- permission additions that collide with previously assigned meanings
 
-## Build And Verification
+## Verification
 
-Standard workflow:
 - `npm install`
 - `forge build`
-
-A meaningful finding here should show a real downstream permission check becoming broader, narrower, or mismatched because of the constant set.

package/README.md

@@ -2,7 +2,12 @@
 
 `@bananapus/permission-ids-v6` is the shared constant library for Juicebox V6 operator permissions. It gives every repo in the ecosystem the same numeric meaning for the same permission name.
 
-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
 
@@ -21,17 +26,43 @@ If the question is "who can do this action?" you will still need `JBPermissions`
 | `1` | global `ROOT` permission |
 | `2-23` | core protocol permissions |
 | `24-27` | 721 hook permissions |
-| `28-30` | buyback hook permissions |
-| `31` | router terminal permission |
-| `32-35` | sucker and omnichain permissions |
+| `28-30` | buyback hook and registry permissions |
+| `31` | router terminal registry permission |
+| `32-35` | sucker and omnichain-deployment permissions |
 | `36-40` | revnet-core permissions (hidden tokens, loans) |
 
 The exact constants live in `src/JBPermissionIds.sol`.
 
+Two IDs deserve special attention:
+
+- `SET_BUYBACK_HOOK` covers both setting and permanently locking the configured buyback hook
+- `SET_ROUTER_TERMINAL` covers both setting and permanently locking the configured router terminal
+
 ## Mental Model
 
 This repo is a coordination artifact, not a behavior repo. Its value is that every other package can import the same names and mean the same thing.
 
+## Read This File First
+
+1. `src/JBPermissionIds.sol`
+
+## Integration Traps
+
+- changing an existing numeric constant is a breaking ecosystem change, not an internal refactor
+- adding a new permission ID without coordinating downstream repos creates semantic drift even if the code still compiles
+- wildcard project permissions remain dangerous even when the numeric IDs themselves are correct
+
+## Where Meaning Lives
+
+- numeric permission labels live in `JBPermissionIds.sol`
+- runtime permission checks live in `nana-core-v6/src/JBPermissions.sol`
+- repo-specific uses of those IDs live in the downstream package that imports them
+
+## For AI Agents
+
+- Treat this repo as a naming registry for permission bits, not as the runtime permission engine.
+- If asked whether an action is allowed, inspect the downstream repo that checks the ID in addition to this file.
+
 ## Install
 
 ```bash
@@ -56,4 +87,5 @@ src/
 
 - `ROOT` is intentionally powerful and should be granted sparingly
 - wildcard project scope is convenient but easy to misuse operationally
+- some IDs intentionally bundle configuration and irreversible locking authority, so their blast radius is larger than their names first suggest
 - any change to this file has ecosystem-wide consequences because other repos assume the values are stable

package/RISKS.md

@@ -1,36 +1,50 @@
 # Permission IDs Risk Register
 
-Constants-only library defining permission ID values used throughout the Juicebox V6 ecosystem. The main failure mode is not local arithmetic; it is ecosystem-wide semantic drift if contracts disagree on what a permission ID means.
+This file focuses on the coordination risks in `JBPermissionIds`. The contract surface is tiny, but any semantic drift here can corrupt access control across the entire V6 ecosystem.
 
 ## How to use this file
 
-- Read `Priority risks` first; these are the ways a tiny library can create very large blast radius.
-- Use the design notes to understand why stability and coordination matter more here than contract complexity.
-- Treat any change in this repo as an ecosystem migration event, not a routine edit.
+- Read `Priority risks` first; the main danger is cross-repo disagreement, not local bugs.
+- Treat every ID change as an ecosystem migration event.
+- Use `Invariants to Verify` to keep append-only discipline explicit.
 
 ## Priority risks
 
 | Priority | Risk | Why it matters | Primary controls |
 |----------|------|----------------|------------------|
-| P0 | Semantic drift across repos | If two repos interpret the same `uint8` differently, access control breaks silently across the ecosystem. | Single source of truth, strict review, and synchronized downstream updates. |
-| P1 | Reordering or repurposing existing IDs | Changing established IDs can create backward-incompatible authority bugs without any contract-level revert. | Append-only discipline and explicit migration communication. |
-| P2 | Incomplete ecosystem adoption | A new permission ID is only safe if every dependent repo and deploy script understands it. | Cross-repo review and deployment coordination. |
+| P0 | Semantic drift across repos | If two packages assign different meanings to the same numeric ID, permission checks silently authorize the wrong actions. | Single source of truth, append-only changes, and synchronized downstream updates. |
+| P1 | Reusing or reordering existing IDs | Renumbering breaks already-deployed contracts and off-chain tooling without any on-chain migration safety. | Never repurpose an assigned ID. Append only. |
+| P1 | Over-trusting high-impact IDs | Some IDs directly control funds, terminal routing, hook locking, or wildcard authority. Misgrants are catastrophic. | Explicit operator review and narrow-scoped permission grants. |
 
 ## 1. Known Risks
 
-- **ROOT permission (ID 1).** ROOT grants all permissions across every contract. Any address granted ROOT can perform any permissioned operation on any project. Should never be granted to untrusted addresses.
-- **SET_BUYBACK_HOOK includes lock (ID 30).** Gates both `setHookFor` and `lockHookFor`. An operator with this permission can permanently lock the buyback hook configuration.
-- **SET_ROUTER_TERMINAL includes lock (ID 31).** Gates both `setTerminalFor` and `lockTerminalFor`. An operator can permanently lock the router terminal.
-- **ID collision risk.** Permission IDs are manually assigned sequential uint8 values. Adding new IDs requires coordination to avoid collision. Library is append-only.
-- **No runtime enforcement.** This library only defines constants. Enforcement happens in consuming contracts. A mismatch between the ID used here and the ID checked in a consumer would silently fail.
-- **High-impact permission IDs (fund-moving).** IDs that control fund flow should receive the most audit scrutiny: `ROOT` (1, grants everything), `CASH_OUT_TOKENS` (4, triggers withdrawals), `SEND_PAYOUTS` (5, triggers payout distribution), `MIGRATE_TERMINAL` (6, moves balances), `SET_TERMINALS` (15, redirects all fund flows), `USE_ALLOWANCE` (18, draws from surplus), `SET_SPLIT_GROUPS` (19, controls where payouts go). Of these, ROOT + SET_TERMINALS + MIGRATE_TERMINAL are the most dangerous — they can redirect all of a project's funds.
-- **SIGN_FOR_ERC20 (ID 23).** Grants permission to sign messages on behalf of a project's ERC-20 token via ERC-1271. Used for Etherscan contract verification and other off-chain signature validation. Should only be granted to trusted addresses since it controls the token's signing authority.
-- **Wildcard `projectId=0` semantics.** When a permission is granted with `projectId=0`, it applies to ALL projects. This is used by system contracts (e.g., `REVLoans` gets `USE_ALLOWANCE` with `projectId=0`). A bug in a contract holding wildcard permissions affects every project in the ecosystem, not just one. Only system-level contracts should hold wildcard permissions.
-
-## 2. Design Notes
-
-- Permission 0 is reserved and cannot be set.
-- IDs are `uint8` (0-255), with 1-40 currently assigned.
-- IDs 36-40 are used by `revnet-core-v6` for operator delegation: `HIDE_TOKENS` (36), `OPEN_LOAN` (37), `REALLOCATE_LOAN` (38), `REPAY_LOAN` (39), `REVEAL_TOKENS` (40).
-- IDs 41-255 are available for ecosystem extensions. Third-party contracts can define their own permission IDs in this range, but must coordinate to avoid collisions. No on-chain registry exists for custom IDs — collision detection is purely social.
-- This library has zero dependencies -- it is the leaf of the dependency graph.
+- **No runtime enforcement here.** This library only defines constants. Safety depends on every consuming repo checking the intended ID.
+- **`ROOT` is ecosystem-wide god mode.** `ROOT` (ID `1`) grants all permissions, including permissions added in the future.
+- **Wildcard grants amplify blast radius.** Any permission granted with `projectId = 0` applies to all projects owned by that account. System contracts may need this, but operator mistakes become ecosystem-wide.
+- **Hook and router lock powers are bundled.** `SET_BUYBACK_HOOK` (ID `30`) controls both hook selection and hook locking. `SET_ROUTER_TERMINAL` (ID `31`) controls both terminal selection and terminal locking.
+- **No on-chain namespace for third-party extensions.** IDs `41-255` are socially available, not registry-managed. External packages can collide unless teams coordinate out of band.
+
+## 2. High-Impact IDs
+
+- **Fund-moving IDs.** `CASH_OUT_TOKENS` (`4`), `SEND_PAYOUTS` (`5`), `MIGRATE_TERMINAL` (`6`), `SET_TERMINALS` (`15`), `USE_ALLOWANCE` (`18`), and `SET_SPLIT_GROUPS` (`19`) can redirect or release value.
+- **Hook-routing IDs.** `SET_BUYBACK_POOL` (`28`), `SET_BUYBACK_HOOK` (`30`), and `SET_ROUTER_TERMINAL` (`31`) materially control execution routes and can lock those routes permanently.
+- **Revnet loan IDs.** `OPEN_LOAN` (`37`), `REALLOCATE_LOAN` (`38`), and `REPAY_LOAN` (`39`) are operationally powerful because they move collateral and debt state.
+
+## 3. Integration Risks
+
+- **Docs can lag deployed assumptions.** Off-chain tooling, UIs, and auditors often rely on human-readable permission names. A stale doc can be almost as dangerous as a stale constant if operators grant the wrong ID.
+- **Cross-package imports must remain canonical.** Downstream repos should import this library instead of redefining numeric literals locally.
+- **Future IDs inherit current trust assumptions.** Because `ROOT` covers future IDs, any new permission expands the capability of existing ROOT operators immediately after deployment.
+
+## 4. Invariants to Verify
+
+- Assigned IDs are append-only and never repurposed.
+- `0` remains unused as a permission ID.
+- Every documented ID in this repo matches the numeric checks in downstream consuming contracts.
+- New IDs added after `40` do not collide with existing ecosystem assignments.
+
+## 5. Accepted Behaviors
+
+### 5.1 This repo is coordination infrastructure, not an enforcement layer
+
+`JBPermissionIds` intentionally has no access control, storage, or runtime checks. The value of the repo is that every other package can import the same constants and mean the same thing.

package/USER_JOURNEYS.md

@@ -1,44 +1,102 @@
 # User Journeys
 
-## Who This Repo Serves
+## Repo Purpose
 
-- protocol and product engineers mapping actions to the right operator permission
-- auditors checking whether a downstream repo reused or drifted from the shared permission vocabulary
-- maintainers adding new permission surfaces without colliding with existing meaning
+This repo is the shared permission vocabulary for the V6 ecosystem.
+It does not store permissions or enforce them at runtime. It defines the constants downstream repos should import so
+permissioned behavior stays legible and consistent.
+
+## Primary Actors
+
+- engineers choosing which permission constant should guard a feature
+- auditors checking whether a repo drifted from the shared vocabulary
+- maintainers extending the permission map without numeric collisions
+
+## Key Surfaces
+
+- `JBPermissionIds`: library of canonical permission constants used across V6 repos
+- grouped constants for core, 721, router, buyback, sucker, Revnet, and related ecosystem actions
+- reserved ranges documented in `README.md`, including `ROOT = 1`, ecosystem-managed IDs through `40`, and socially coordinated extension space above that
 
 ## Journey 1: Map A Product Action To The Right Permission
 
-**Starting state:** a repo needs to guard an action with `JBPermissions`.
+**Actor:** downstream engineer.
 
-**Success:** the code imports the canonical constant instead of inventing a local numeric meaning.
+**Intent:** protect an action with the canonical permission constant instead of inventing a local number.
 
-**Flow**
-1. Find the action's domain in `JBPermissionIds`, such as core, 721 hook, buyback, router, or sucker permissions.
-2. Import the shared constant into the downstream repo.
-3. Check the relevant caller against that constant through `JBPermissions`.
+**Preconditions**
+- the action is governed by `JBPermissions`
+- the engineer knows which repo or domain owns the action
+
+**Main Flow**
+1. Find the action domain in `JBPermissionIds`, such as core, 721, router, buyback, or sucker permissions.
+2. Import the constant into the downstream repo.
+3. Use that constant in the runtime authorization check.
+4. Treat bundled high-impact IDs like `SET_BUYBACK_HOOK` and `SET_ROUTER_TERMINAL` as broader powers than their short names suggest because they also gate locking.
+
+**Failure Modes**
+- the repo hardcodes a number locally and drifts from the shared vocabulary
+- a repo picks the wrong existing constant because the action sounds similar but is not actually equivalent
+- a team grants `ROOT` or wildcard project permissions without appreciating that future IDs inherit that blast radius
+- docs and tests describe a permission by nickname rather than the imported constant
+
+**Postconditions**
+- the downstream action is guarded by the shared permission vocabulary instead of a local numeric convention
 
 ## Journey 2: Review An Existing Operator Setup
 
-**Starting state:** a project or audit needs to understand what a granted permission actually means.
+**Actor:** auditor, operator, or curious integrator.
+
+**Intent:** decode opaque permission bits into named actions.
 
-**Success:** the operator bitset can be read as named product actions instead of opaque integers.
+**Preconditions**
+- the operator bitset or granted permission IDs are already known
+- the reviewer understands that this repo names permissions but does not prove how each repo uses them
 
-**Flow**
+**Main Flow**
 1. Start with the permission bits granted on the project.
-2. Map each bit back to the shared constant defined here.
-3. Confirm that the downstream repo still uses that constant consistently at its authorization checks.
+2. Map each bit to its named constant here.
+3. Confirm the downstream repo still uses that constant consistently at its authorization checks and docs.
+4. Check whether any granted IDs are effectively funds-moving, routing, locking, or loan-management powers rather than low-risk admin toggles.
+
+**Failure Modes**
+- downstream code reuses a permission ID for a different meaning
+- reviewers decode the bit correctly but underestimate what the downstream repo lets that permission do in practice
+- reviewers assume this repo alone is enough and skip the actual guarded code
+
+**Postconditions**
+- the reviewer has a named permission map and knows which downstream repos still need inspection
 
 ## Journey 3: Add A New Ecosystem Surface Without Permission Drift
 
-**Starting state:** a new repo or feature needs a permission that does not fit any existing constant.
+**Actor:** maintainer extending the permission vocabulary.
 
-**Success:** the new constant is added once, in the right numeric range, and downstream packages can reuse it without ambiguity.
+**Intent:** add one new permission constant in a way the rest of the ecosystem can reuse.
 
-**Flow**
-1. Pick the next unused ID in the relevant ecosystem range.
+**Preconditions**
+- no existing constant already matches the new action
+- the maintainer understands the numeric ranges already in use
+
+**Main Flow**
+1. Choose the next unused ID in the relevant range.
 2. Add the named constant in `JBPermissionIds.sol`.
-3. Update downstream repos to import that constant instead of duplicating the number.
-4. Re-audit any docs or tests that explain the meaning of that permission.
+3. Update downstream repos to import the constant instead of duplicating the number.
+4. Refresh docs and tests that explain the permission.
+5. If the new ID goes above the ecosystem-managed range, coordinate externally so third-party packages do not collide on the same number.
+
+**Failure Modes**
+- a new repo defines its own numeric constant first and creates drift
+- a new constant is added in the wrong semantic range, making later review harder
+- a new ID silently expands what existing `ROOT` operators can do without that blast radius being reviewed
+- documentation updates lag behind the code change
+
+**Postconditions**
+- the new ecosystem surface has a reusable canonical permission ID with coordinated downstream adoption
+
+## Trust Boundaries
+
+- this repo is trusted only as shared vocabulary; actual storage and enforcement live elsewhere
+- downstream repos can still misuse a constant even when they import the right one
 
 ## Hand-Offs
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bananapus/permission-ids-v6",
-  "version": "0.0.17",
+  "version": "0.0.18",
   "license": "MIT",
   "repository": {
     "type": "git",

package/references/runtime.md

@@ -1,5 +1,7 @@
 # Permission IDs Runtime
 
+Use this file when you need to confirm the canonical numeric labels, not when you need to understand enforcement behavior.
+
 ## Core Role
 
 - [`src/JBPermissionIds.sol`](../src/JBPermissionIds.sol) defines the canonical numeric labels used by the rest of the ecosystem.
@@ -13,3 +15,4 @@
 
 - If you edit a constant, audit every dependent repo that imports it.
 - If you need to know who can exercise a permission, follow the usage into the enforcing repo rather than stopping here.
+- There are no repo-local tests here, so downstream compile and behavior audits matter more than this package in isolation.