@bananapus/ownable-v6 0.0.36 → 0.0.38

package/README.md

@@ -12,7 +12,9 @@
 - [SKILLS.md](./SKILLS.md) — reusable patterns and gotchas for builders
 - [STYLE_GUIDE.md](./STYLE_GUIDE.md) — code style conventions
 - [AUDIT_INSTRUCTIONS.md](./AUDIT_INSTRUCTIONS.md) — guidance for auditors
-- [CHANGELOG.md](./CHANGELOG.md) — release notes
+- [CHANGELOG.md](./CHANGELOG.md) - V5 to V6 migration changelog
+- [references/runtime.md](./references/runtime.md) — owner-resolution, transfer, and delegation behavior by surface
+- [references/operations.md](./references/operations.md) — change checklist and common failure modes
 
 ## Overview
 
@@ -29,7 +31,7 @@ Use this repo when ownership should follow a Juicebox project. Do not use it if
 
 If the issue is in project ownership itself, start in `nana-core-v6` and `JBProjects`. This repo matters when another contract wants its admin surface to follow that project ownership.
 
-## Key Contracts
+## Key contracts
 
 | Contract | Role |
 | --- | --- |
@@ -37,7 +39,7 @@ If the issue is in project ownership itself, start in `nana-core-v6` and `JBProj
 | `JBOwnableOverrides` | Abstract base that holds owner resolution and delegated-permission logic. |
 | `IJBOwnable` | Interface for queries, transfers, permission ID changes, and events. |
 
-## Mental Model
+## Mental model
 
 This package is a small ownership adapter:
 
@@ -45,13 +47,13 @@ This package is a small ownership adapter:
 2. optionally allow a delegated permission to satisfy `onlyOwner` when the contract is project-owned
 3. preserve an `Ownable`-like interface for downstream contracts
 
-## Read These Files First
+## Read these files first
 
 1. `src/JBOwnable.sol`
 2. `src/JBOwnableOverrides.sol`
 3. `src/interfaces/IJBOwnable.sol`
 
-## Integration Traps
+## Integration traps
 
 - ownership may resolve to a project NFT holder instead of a fixed address, so caching `owner()` off-chain can go stale
 - `owner()` can resolve to `address(0)` if the referenced project NFT is invalid or unreadable, which effectively renounces the contract
@@ -60,13 +62,13 @@ This package is a small ownership adapter:
 - a project NFT round trip back to the owner who last set `permissionId` can reactivate that owner's still-granted delegates
 - ownership transfer and permission-ID updates are part of the security model, not just convenience helpers
 
-## Where State Lives
+## Where state lives
 
 - effective ownership configuration: `JBOwnableOverrides`
 - downstream contract state: the inheriting contract
 - project ownership truth: `nana-core-v6` when the owner target is a Juicebox project
 
-## High-Signal Tests
+## High-signal tests
 
 1. `test/Ownable.t.sol`
 2. `test/OwnableAttacks.t.sol`
@@ -90,7 +92,7 @@ forge build
 forge test
 ```
 
-## Repository Layout
+## Repository layout
 
 ```text
 src/
@@ -102,7 +104,7 @@ test/
   core, attack, invariant, mock, and regression coverage
 ```
 
-## Risks And Notes
+## Risks and notes
 
 - if ownership is tied to a project NFT and that NFT becomes unreachable, the contract is effectively locked
 - project-owned delegated access depends on a chosen permission ID, so bad permission selection is an operational risk
@@ -111,7 +113,9 @@ test/
   resolved owner still matches the owner who set it
 - transferring ownership to a project validates that the project exists at transfer time, but later project invalidation can still collapse effective ownership to `address(0)`
 
-## For AI Agents
+## For AI agents
 
 - Do not collapse project-based ownership into ordinary wallet-based ownership in your summary.
 - Read the attack and regression tests before making claims about burn-lock or unminted-project edge cases.
+
+If ownership should track a project NFT, reach for this; if a fixed wallet is enough, plain `Ownable` is simpler.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bananapus/ownable-v6",
-  "version": "0.0.36",
+  "version": "0.0.38",
   "license": "MIT",
   "repository": {
     "type": "git",
@@ -17,8 +17,8 @@
     "node": ">=20.0.0"
   },
   "dependencies": {
-    "@bananapus/core-v6": "^0.0.78",
-    "@bananapus/permission-ids-v6": "^0.0.28",
+    "@bananapus/core-v6": "^0.0.82",
+    "@bananapus/permission-ids-v6": "^0.0.30",
     "@openzeppelin/contracts": "5.6.1"
   },
   "scripts": {

package/references/operations.md

@@ -1,6 +1,6 @@
 # Ownable Operations
 
-## Change Checklist
+## Change checklist
 
 - If you edit owner resolution, verify both direct ownership and project-owned cases.
 - If you edit permission handling, verify explicit transfer resets, project NFT transfer staleness, and NFT round-trip
@@ -9,7 +9,7 @@
   transfers merely make it stale.
 - If the change touches project ownership, check unminted-project and burn-lock regressions before assuming the happy-path tests are enough.
 
-## Common Failure Modes
+## Common failure modes
 
 - Integrations assume delegated operators survive ownership transfer.
 - Bugs are blamed on this repo when the underlying project NFT ownership changed upstream.

package/references/runtime.md

@@ -1,20 +1,20 @@
 # Ownable Runtime
 
-## Core Roles
+## Core roles
 
 - [`src/JBOwnable.sol`](../src/JBOwnable.sol) is the concrete downstream inheritance surface.
 - [`src/JBOwnableOverrides.sol`](../src/JBOwnableOverrides.sol) owns owner resolution and delegated permission checks.
 
-## High-Risk Areas
+## High-risk areas
 
 - Effective-owner resolution: ownership may follow a project NFT rather than a fixed address.
 - Delegated `onlyOwner` permissions: the chosen permission ID changes who can administer a contract.
 - Transfer semantics: explicit ownable transfers reset permission IDs, while project NFT transfers preserve the stored
   ID and rely on `_permissionOwner` to decide whether it is effective.
 
-## Tests To Trust First
+## Tests to trust first
 
 - [`test/Ownable.t.sol`](../test/Ownable.t.sol) for baseline behavior.
 - [`test/OwnableEdgeCases.t.sol`](../test/OwnableEdgeCases.t.sol) and [`test/OwnableAttacks.t.sol`](../test/OwnableAttacks.t.sol) for edge and adversarial cases.
 - [`test/OwnableInvariantTests.sol`](../test/OwnableInvariantTests.sol) for broader invariants.
-- [`test/regression/BurnLockProtection.t.sol`](../test/regression/BurnLockProtection.t.sol), [`test/RegressionUnmintedProjectHijack.t.sol`](../test/RegressionUnmintedProjectHijack.t.sol), [`test/regression/PermissionIdNFTTransfer.t.sol`](../test/regression/PermissionIdNFTTransfer.t.sol), and [`test/audit/CodexNemesisPermissionReactivation.t.sol`](../test/audit/CodexNemesisPermissionReactivation.t.sol) for the regressions most likely to matter in review.
+- [`test/regression/BurnLockProtection.t.sol`](../test/regression/BurnLockProtection.t.sol), [`test/RegressionUnmintedProjectHijack.t.sol`](../test/RegressionUnmintedProjectHijack.t.sol), [`test/regression/PermissionIdNFTTransfer.t.sol`](../test/regression/PermissionIdNFTTransfer.t.sol), and [`test/regression/StaleDelegateReactivationOnProjectReturn.t.sol`](../test/regression/StaleDelegateReactivationOnProjectReturn.t.sol) for the regressions most likely to matter in review.

package/src/JBOwnable.sol

@@ -17,10 +17,8 @@ contract JBOwnable is JBOwnableOverrides {
     // -------------------------- constructor ---------------------------- //
     //*********************************************************************//
 
-    /// @dev To make a Juicebox project's owner this contract's owner, pass that project's ID as the
-    /// `initialProjectIdOwner`.
-    /// @dev To make a specific address the owner, pass that address as the `initialOwner` and `0` as the
-    /// `initialProjectIdOwner`.
+    /// @dev To make a Juicebox project's owner this contract's owner, pass its ID as `initialProjectIdOwner`.
+    /// @dev To make a specific address the owner, pass it as `initialOwner` and `0` as `initialProjectIdOwner`.
     /// @dev The owner can give other addresses owner access through the `permissions` contract.
     /// @param permissions A contract storing permissions.
     /// @param projects Mints ERC-721s that represent project ownership and transfers.

package/src/JBOwnableOverrides.sol

@@ -65,11 +65,10 @@ abstract contract JBOwnableOverrides is Context, JBPermissioned, IJBOwnable {
 
     /// @dev To restrict access to a Juicebox project's owner, pass that project's ID as the `initialProjectIdOwner` and
     /// the zero address as the `initialOwner`.
-    /// To restrict access to a specific address, pass that address as the `initialOwner` and `0` as the
-    /// `initialProjectIdOwner`.
+    /// To restrict access to a specific address, pass it as `initialOwner` and `0` as `initialProjectIdOwner`.
     /// @dev Project-based owners can give owner access to other addresses through the `permissions` contract.
-    /// Address-based owners cannot enable delegated owner access because `JBPermissions` project ID `0` is the
-    /// wildcard project namespace.
+    /// Address-based owners cannot delegate owner access because `JBPermissions` project ID `0` is the wildcard
+    /// project namespace.
     /// @dev If `initialProjectIdOwner` references an unminted project, `owner()` resolves to `address(0)` and
     /// owner-gated calls revert until that project is created. The first account to mint that project becomes the
     /// effective owner, so deployers must control the mint sequence.
@@ -208,8 +207,7 @@ abstract contract JBOwnableOverrides is Context, JBPermissioned, IJBOwnable {
         _setPermissionId(permissionId);
     }
 
-    /// @notice Transfers ownership of this contract to a new address (the `newOwner`). Can only be called by the
-    /// current owner.
+    /// @notice Transfers ownership of this contract to a new address. Can only be called by the current owner.
     /// @dev The `permissionId` is reset to 0 on transfer to prevent permission clashes for the new owner.
     /// The new owner must explicitly call `setPermissionId()` to configure owner-level permission delegation.
     /// @param newOwner The address to transfer ownership to.
@@ -222,8 +220,7 @@ abstract contract JBOwnableOverrides is Context, JBPermissioned, IJBOwnable {
         _transferOwnership({newOwner: newOwner, projectId: 0});
     }
 
-    /// @notice Transfers ownership to a Juicebox project — whoever holds that project's ERC-721 NFT becomes the
-    /// owner.
+    /// @notice Transfers ownership to a Juicebox project, whose ERC-721 NFT holder becomes the owner.
     /// @dev The `permissionId` is reset to 0 on transfer to prevent the previous owner's delegates from retaining
     /// access. The new project owner must call `setPermissionId()` to re-enable delegation.
     /// @dev The `projectId` must fit within a `uint88` and the project must already exist.