@bananapus/ownable-v6 0.0.36 → 0.0.37

package/README.md

@@ -13,6 +13,8 @@
 - [STYLE_GUIDE.md](./STYLE_GUIDE.md) — code style conventions
 - [AUDIT_INSTRUCTIONS.md](./AUDIT_INSTRUCTIONS.md) — guidance for auditors
 - [CHANGELOG.md](./CHANGELOG.md) — release notes
+- [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.37",
   "license": "MIT",
   "repository": {
     "type": "git",

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.