@bananapus/permission-ids-v6 0.0.17 → 0.0.19

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 at the 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-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 code and updating dependent deployments |
 
-- 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 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 makes sure 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.
+This repo intentionally contains almost no logic. 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 stay stable once deployed contracts or integrations use them.
+- New IDs should be appended intentionally, not reused or repurposed.
+- Numeric stability matters more than naming convenience.
+- `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 tightly 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 rename or reorder here can silently break permissions across the ecosystem.
+- The real blast radius comes from deployed contracts that already use these values.
+- There is very little meaningful local runtime test surface in this repo.
 
 ## 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 hide the one-to-one mapping between bit position and meaning.
+
+## Source Map
+
+- `src/JBPermissionIds.sol`
+- `references/runtime.md`

package/AUDIT_INSTRUCTIONS.md

@@ -1,35 +1,55 @@
 # Audit Instructions
 
-This repo is only permission ID constants, but the constants are security-critical because many repos key access control off them.
+This repo is only permission ID constants, but those 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
+
+- assign duplicate IDs to different permissions
 - mismatch IDs that downstream repos assume are canonical
 - create ordering or collision hazards for future permission additions
 
 ## Scope
 
 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.
 2. No two distinct permissions share an ID.
 3. IDs match the expectations of all dependent repos in this workspace.
-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`.
+4. ID `23` (`SIGN_FOR_ERC20`) matches the value used by `nana-core-v6` for ERC-1271 signature delegation.
+5. IDs `36-40` used by `revnet-core-v6` 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,17 +2,22 @@
 
 `@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
 
-The library is intentionally simple: one Solidity file, no storage, no deployment, and no runtime logic. Its value comes from consistency.
+This library is intentionally simple: one Solidity file, no storage, no deployment, and no runtime logic. Its value is consistency.
 
-`JBPermissions` stores operator permissions as packed bits. This package names the bit positions so integrations do not drift across repos.
+`JBPermissions` stores operator permissions as packed bits. This package names those bit positions so integrations do not drift across repos.
 
 Use this repo as the single source of truth for permission numbers. Do not redefine permission IDs locally in downstream repos.
 
-If the question is "who can do this action?" you will still need `JBPermissions` in `nana-core-v6`. This repo only tells you what the numeric labels mean.
+If the question is "who can do this action?" you still need `JBPermissions` in `nana-core-v6`. This repo only tells you what the numbers mean.
 
 ## Current Permission Ranges
 
@@ -21,16 +26,42 @@ 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 |
-| `36-40` | revnet-core permissions (hidden tokens, loans) |
+| `28-30` | buyback hook and registry permissions |
+| `31` | router terminal registry permission |
+| `32-35` | sucker and omnichain deployment permissions |
+| `36-40` | revnet-core permissions |
 
 The exact constants live in `src/JBPermissionIds.sol`.
 
+Two IDs deserve extra 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.
+This repo is a naming registry, not a behavior repo. Its job is to make every other package use the same permission names for the same bit positions.
+
+## Read This File First
+
+1. `src/JBPermissionIds.sol`
+
+## Integration Traps
+
+- changing an existing numeric constant is an ecosystem breaking change
+- adding a new permission ID without coordinating downstream repos creates semantic drift even if code still compiles
+- wildcard project permissions are still dangerous even when the numeric IDs are correct
+
+## Where Meaning Lives
+
+- numeric permission labels: `JBPermissionIds.sol`
+- runtime permission checks: `nana-core-v6/src/JBPermissions.sol`
+- repo-specific uses of those IDs: the downstream repo 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
 
@@ -55,5 +86,6 @@ src/
 ## Risks And Notes
 
 - `ROOT` is intentionally powerful and should be granted sparingly
-- wildcard project scope is convenient but easy to misuse operationally
-- any change to this file has ecosystem-wide consequences because other repos assume the values are stable
+- wildcard project scope is convenient but easy to misuse
+- some IDs bundle configuration and irreversible locking authority, so their blast radius is larger than the short name suggests
+- any change to this file has ecosystem-wide consequences because other repos assume the values stay 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 covers the coordination risks in `JBPermissionIds`. The contract surface is tiny, but drift here can corrupt access control across the V6 ecosystem.
 
-## How to use this file
+## 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 a local code bug.
+- Treat every ID change as an ecosystem migration event.
+- Use `Invariants to verify` to keep append-only discipline explicit.
 
-## Priority risks
+## 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 ID, permission checks can silently authorize the wrong actions. | Single source of truth, append-only changes, and synchronized downstream updates. |
+| P1 | Reusing or reordering existing IDs | Renumbering breaks 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, routing, locking, or loan state. Misgrants are dangerous. | Explicit operator review and narrow-scoped 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 broad authority.** `ROOT` (ID `1`) grants all permissions, including permissions added in the future.
+- **Wildcard grants increase blast radius.** Any permission granted with `projectId = 0` applies to all projects owned by that account.
+- **Hook and router lock powers are bundled.** `SET_BUYBACK_HOOK` (`30`) and `SET_ROUTER_TERMINAL` (`31`) both cover setting and locking.
+- **Third-party extensions do not have an on-chain namespace.** IDs `41-255` are only socially coordinated, so external packages can collide without coordination.
+
+## 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 audits often rely on human-readable permission names.
+- **Cross-package imports must stay canonical.** Downstream repos should import this library instead of redefining numeric literals locally.
+- **Future IDs expand current `ROOT` power.** Any new permission automatically becomes available to existing `ROOT` operators.
+
+## 4. Invariants To Verify
+
+- Assigned IDs are append-only and never repurposed.
+- `0` stays unused as a permission ID.
+- Every documented ID in this repo matches the numeric checks in downstream 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 repo matters because every other package can import the same constants and mean the same thing.

package/SKILLS.md

@@ -2,8 +2,8 @@
 
 ## Use This File For
 
-- Use this file when you need the canonical numeric meaning of a Juicebox V6 permission constant or when reviewing changes that would affect permission numbering across the ecosystem.
-- Start here, then open the constant file directly.
+- Use this file when you need the canonical numeric meaning of a Juicebox V6 permission constant.
+- Start here when reviewing changes that could affect permission numbering across the ecosystem.
 
 ## Read This Next
 
@@ -20,11 +20,11 @@
 
 ## Purpose
 
-Single source of truth for Juicebox V6 permission ID constants. This repo has no runtime behavior; its value is ecosystem-wide coordination.
+This repo is the single source of truth for Juicebox V6 permission ID constants. It has no runtime behavior. Its value is ecosystem-wide coordination.
 
 ## Reference Files
 
-- Open [`references/runtime.md`](./references/runtime.md) when you need the stability expectations and why changes here are ecosystem-wide.
+- Open [`references/runtime.md`](./references/runtime.md) when you need the stability expectations and why changes here affect the whole ecosystem.
 
 ## Working Rules
 

package/USER_JOURNEYS.md

@@ -1,46 +1,103 @@
 # 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 that downstream repos should import so permissioned behavior stays clear 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 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 permissions without appreciating the blast radius
+- docs and tests describe a permission by nickname instead of 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 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 in authorization checks and docs.
+4. Check whether any granted IDs are really 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
+- reviewers rely on this repo alone and skip the 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 a new permission constant that 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
 
 - Use [nana-core-v6](../nana-core-v6/USER_JOURNEYS.md) for the runtime permission registry that stores and checks these IDs.
-- Use the relevant downstream repo when the question is about what a permissioned action actually does after authorization succeeds.
+- Use the relevant downstream repo when the question is about what a permissioned action does after authorization succeeds.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bananapus/permission-ids-v6",
-  "version": "0.0.17",
+  "version": "0.0.19",
   "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.