@bananapus/permission-ids-v6 0.0.18 → 0.0.20

package/ADMINISTRATION.md

@@ -11,20 +11,20 @@
 
 ## 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.
+`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-code level coordination only
+- Source-level coordination only
 
 ## Roles
 
 | Role | How Assigned | Scope | Notes |
 | --- | --- | --- | --- |
-| Maintainer | Source-code author | Ecosystem-wide | Can add or reorder constants only by editing and redeploying dependent code |
+| Maintainer | Source-code author | Ecosystem-wide | Can add or reorder constants only by editing code and updating dependent deployments |
 
 ## Privileged Surfaces
 
@@ -45,7 +45,7 @@ There are no privileged runtime functions. The only meaningful changes are sourc
 
 - 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.
+- If docs and code disagree on a permission number, trust the code and update the docs before further review.
 
 ## Recovery
 

package/ARCHITECTURE.md

@@ -2,17 +2,17 @@
 
 ## Purpose
 
-`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`.
+`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`.
 
 ## System Overview
 
-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.
+This repo intentionally contains almost no logic. Other repos import `JBPermissionIds` and compare permission bits against these constants.
 
 ## Core Invariants
 
-- Existing IDs must remain stable once consumed by deployed contracts or integrations.
+- 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; changing a value while keeping a familiar name is still a protocol break.
+- Numeric stability matters more than naming convenience.
 - `ROOT` must stay aligned with `JBPermissions` expectations in `nana-core-v6`.
 
 ## Modules
@@ -24,7 +24,7 @@ The repo intentionally contains almost no logic. Its value is stable coordinatio
 ## Trust Boundaries
 
 - This repo has no runtime authority by itself.
-- It is semantically coupled to `nana-core-v6` and every repo that performs permission checks.
+- It is tightly coupled to `nana-core-v6` and every repo that performs permission checks.
 
 ## Critical Flows
 
@@ -37,15 +37,15 @@ 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.
+- 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 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.
+- Do not add aliases that hide the one-to-one mapping between bit position and meaning.
 
 ## Source Map
 

package/AUDIT_INSTRUCTIONS.md

@@ -1,17 +1,19 @@
 # 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.
 
 ## 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
@@ -22,6 +24,7 @@ In scope:
 ## 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
 
@@ -37,8 +40,8 @@ This repo defines canonical numeric IDs that other repos treat as part of their
 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`.
 
 ## Attack Surfaces
 

package/README.md

@@ -11,13 +11,13 @@ 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
 
@@ -28,19 +28,19 @@ If the question is "who can do this action?" you will still need `JBPermissions`
 | `24-27` | 721 hook 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) |
+| `32-35` | sucker and omnichain deployment permissions |
+| `36-40` | revnet-core permissions |
 
 The exact constants live in `src/JBPermissionIds.sol`.
 
-Two IDs deserve special attention:
+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
 
@@ -48,15 +48,15 @@ This repo is a coordination artifact, not a behavior repo. Its value is that eve
 
 ## 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
+- 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 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
+- 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
 
@@ -86,6 +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
-- 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
+- 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,28 +1,28 @@
 # Permission IDs Risk Register
 
-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.
+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; the main danger is cross-repo disagreement, not local bugs.
+- 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.
+- 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 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. |
+| 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
 
 - **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.
+- **`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
 
@@ -32,19 +32,19 @@ This file focuses on the coordination risks in `JBPermissionIds`. The contract s
 
 ## 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.
+- **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
+## 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.
+- `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 value of the repo is that every other package can import the same constants and mean the same thing.
+`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

@@ -2,9 +2,7 @@
 
 ## Repo Purpose
 
-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.
+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
 
@@ -15,7 +13,7 @@ permissioned behavior stays legible and consistent.
 ## 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
+- 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
@@ -37,15 +35,15 @@ permissioned behavior stays legible and consistent.
 **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
+- 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
 
-**Actor:** auditor, operator, or curious integrator.
+**Actor:** auditor, operator, or integrator.
 
 **Intent:** decode opaque permission bits into named actions.
 
@@ -56,13 +54,13 @@ permissioned behavior stays legible and consistent.
 **Main Flow**
 1. Start with the permission bits granted on the project.
 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.
+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 in practice
-- reviewers assume this repo alone is enough and skip the actual guarded code
+- 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
@@ -71,7 +69,7 @@ permissioned behavior stays legible and consistent.
 
 **Actor:** maintainer extending the permission vocabulary.
 
-**Intent:** add one new permission constant in a way the rest of the ecosystem can reuse.
+**Intent:** add a new permission constant that the rest of the ecosystem can reuse.
 
 **Preconditions**
 - no existing constant already matches the new action
@@ -95,10 +93,11 @@ permissioned behavior stays legible and consistent.
 
 ## Trust Boundaries
 
-- this repo is trusted only as shared vocabulary; actual storage and enforcement live elsewhere
+- 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.18",
+  "version": "0.0.20",
   "license": "MIT",
   "repository": {
     "type": "git",