@bananapus/ownable-v6 0.0.17 → 0.0.18

package/ADMINISTRATION.md

@@ -1,95 +1,79 @@
 # Administration
 
-Admin privileges and their scope in nana-ownable-v6.
+## At A Glance
 
-## Roles
-
-| Role | Who | How Access Is Determined |
-|------|-----|------------------------|
-| **Direct Owner** | An EOA or contract stored in `JBOwner.owner` | Used when `JBOwner.projectId == 0`. Set at construction or via `transferOwnership(address)`. |
-| **Project Owner** | The holder of the `JBProjects` ERC-721 for `JBOwner.projectId` | Used when `JBOwner.projectId != 0`. Resolved dynamically via `PROJECTS.ownerOf(projectId)` on every call. |
-| **Permission Delegate** | Any address granted `JBOwner.permissionId` through `JBPermissions` | The owner (direct or project) calls `JBPermissions.setPermissionsFor(...)` to grant `permissionId` to an operator. That operator then passes the `_checkOwner()` / `_requirePermissionFrom()` check. |
-
-Only one of Direct Owner or Project Owner is active at a time, never both. Permission Delegates extend whichever mode is active.
-
-## Privileged Functions
+| Item | Details |
+| --- | --- |
+| Scope | Ownership resolution primitive used by downstream repos |
+| Control posture | Primitive only; control depends on the inheriting contract |
+| Highest-risk actions | Transferring ownership to the wrong address or project and assuming delegated operators survive transfer |
+| Recovery posture | Recovery depends on the inheriting contract and the still-recognized current owner |
 
-### JBOwnableOverrides (abstract base)
+## Purpose
 
-| Function | Required Role | Permission ID | Scope | What It Does |
-|----------|--------------|---------------|-------|--------------|
-| `renounceOwnership()` | Owner or delegate | `jbOwner.permissionId` | Per-contract | Sets `owner` to `address(0)` and `projectId` to `0`. Permanently disables all `onlyOwner`-guarded functions. Irreversible. |
-| `setPermissionId(uint8)` | Owner or delegate | `jbOwner.permissionId` | Per-contract | Changes which permission ID grants owner-equivalent access via `JBPermissions`. Resets the delegation surface -- previous delegates with the old ID lose access. |
-| `transferOwnership(address)` | Owner or delegate | `jbOwner.permissionId` | Per-contract | Transfers ownership to a new address. Resets `projectId` to `0` and `permissionId` to `0`. The new owner must call `setPermissionId()` to re-enable delegation. |
-| `transferOwnershipToProject(uint256)` | Owner or delegate | `jbOwner.permissionId` | Per-contract | Transfers ownership to a Juicebox project. Resets `owner` to `address(0)` and `permissionId` to `0`. Validates that the project exists (`projectId <= PROJECTS.count()`). |
+`nana-ownable-v6` does not introduce a new admin surface by itself. It defines how ownership is resolved for other repos. The important control question is how a contract's `owner()` is determined and how delegated permission IDs behave across ownership transfers.
 
-### JBOwnable (concrete contract)
+## Control Model
 
-`JBOwnable` inherits all functions above and adds no additional privileged functions. It provides the `onlyOwner` modifier for use by inheriting contracts.
+- Ownership can be address-based or project-based.
+- Delegated operator checks run through `JBPermissions`.
+- Transfer and renounce semantics are part of the primitive.
+- Permission delegation resets on ownership transfer.
 
-Any contract that inherits `JBOwnable` and applies the `onlyOwner` modifier to its own functions effectively creates additional privileged functions gated by the same ownership and permission model described here.
-
-## Ownership Model
+## Roles
 
-JBOwnable bridges Juicebox project ownership to the OpenZeppelin `Ownable` pattern through the `JBOwner` struct:
+| Role | How Assigned | Scope | Notes |
+| --- | --- | --- | --- |
+| Direct owner | Stored owner address | Per contract | Standard `Ownable`-like control |
+| Project owner | Holder of the referenced project NFT | Per contract | Dynamic ownership resolution |
+| Delegated operator | `JBPermissions` grant with the configured permission ID | Per contract and project | Only if the inheriting contract enables it |
 
-```
-JBOwner {
-    address owner;        // Direct owner address (when projectId == 0)
-    uint88  projectId;    // JB project whose NFT holder is owner (when != 0)
-    uint8   permissionId; // Permission ID for delegation via JBPermissions
-}
-```
+## Privileged Surfaces
 
-**Resolution logic** (in `_checkOwner()` and `owner()`):
+The meaningful control surfaces are inherited by downstream contracts:
 
-1. If `projectId != 0`, the owner is `PROJECTS.ownerOf(projectId)` -- resolved dynamically on every call. If `ownerOf()` reverts (e.g., hypothetical NFT burn), the resolved owner becomes `address(0)`, effectively renouncing the contract.
-2. If `projectId == 0`, the owner is `JBOwner.owner` directly.
-3. In both cases, `_checkOwner()` calls `_requirePermissionFrom(resolvedOwner, projectId, permissionId)`, which passes if `msg.sender` is the resolved owner OR has the configured `permissionId` granted through `JBPermissions`.
+- `setPermissionId(...)`
+- `transferOwnership(...)`
+- `transferOwnershipToProject(...)`
+- `renounceOwnership()`
+- `onlyOwner` checks that resolve either the direct owner or the current project NFT holder
 
-**Permission delegation** uses the nana-core `JBPermissions` contract. The owner calls `JBPermissions.setPermissionsFor(...)` to grant `permissionId` to an operator address. That operator can then call any `onlyOwner` function on this contract. The ROOT permission (ID 1) in `JBPermissions` grants all permission IDs, including whatever `permissionId` is configured here.
+## Immutable And One-Way
 
-**Ownership transfer resets `permissionId` to 0.** This prevents the previous owner's delegates from retaining access after a transfer. The new owner must explicitly call `setPermissionId()` to configure delegation.
+- Project ownership changes dynamically with project NFT transfers.
+- Delegated permission ID resets on ownership transfer.
+- Renouncing ownership is final unless the inheriting contract adds a separate recovery path.
 
-## Usage Pattern
+## Operational Notes
 
-Contracts inherit from `JBOwnable` to bridge Juicebox project ownership into the standard `onlyOwner` modifier pattern. The typical usage:
+- Treat project-based ownership as live routing, not a snapshot.
+- Do not assume an operator permission survives ownership transfer.
+- Treat `setPermissionId(...)` as a real authority change because it rewires which delegated permission bit counts as owner access.
+- Review the inheriting contract, not just this primitive, to understand the full admin surface.
 
-```solidity
-contract MyHook is JBOwnable {
-    function adjustTiers(...) external onlyOwner {
-        // Only the resolved owner (or a permission delegate) can call this
-    }
-}
-```
+## Machine Notes
 
-The `onlyOwner` modifier calls `_checkOwner()`, which resolves the current owner (via project NFT or direct address) and checks `_requirePermissionFrom()`. This means every `onlyOwner` function automatically supports:
-- Direct ownership (EOA or contract)
-- Project-based ownership (holder of the project NFT)
-- Permission delegation (via the configured `permissionId` through `JBPermissions`)
+- Do not conclude authority from this repo alone; follow the inheriting contract's `onlyOwner` surfaces.
+- Treat ownership transfer as potentially changing both the owner identity and the usable delegated permission ID.
+- If the current permission ID is undocumented, inspect `jbOwner.permissionId` before reasoning about delegated owner access.
+- If a downstream repo uses project-based ownership, re-evaluate owner resolution after every project NFT transfer.
 
-**Practical example:** `JB721TiersHook` inherits `JBOwnable`. During deployment, ownership is transferred to the project via `transferOwnershipToProject(projectId)`. The project NFT holder then becomes the hook's owner, and they can delegate specific hook permissions to operators via `JBPermissions`.
+## Recovery
 
-## Immutable Configuration
+- This primitive has no protocol-wide recovery surface.
+- If ownership was transferred to the wrong project or address, recovery depends on the inheriting contract still recognizing the current owner.
 
-| Property | Set At | Can Change? |
-|----------|--------|-------------|
-| `PERMISSIONS` (IJBPermissions) | Construction (via `JBPermissioned`) | No -- immutable |
-| `PROJECTS` (IJBProjects) | Construction | No -- immutable |
+## Admin Boundaries
 
-The `JBPermissions` and `JBProjects` contract references are baked in at deploy time and cannot be changed. If either contract is upgraded or replaced, the `JBOwnable` instance must be redeployed.
+- This repo does not create a new permission namespace.
+- It cannot make an inheriting contract safer than that contract's own privileged functions.
+- It cannot preserve delegated operators across ownership transfer by default.
 
-## Admin Boundaries
+## Source Map
 
-What admins **cannot** do:
-
-- **Change the `PERMISSIONS` or `PROJECTS` contracts.** These are immutable references set at construction.
-- **Set both `owner` and `projectId` simultaneously.** The `_transferOwnership` internal function reverts if both are non-zero.
-- **Transfer to `address(0)` via `transferOwnership()`.** This reverts with `JBOwnableOverrides_InvalidNewOwner`. Use `renounceOwnership()` instead.
-- **Transfer to a non-existent project.** `transferOwnershipToProject()` checks `projectId <= PROJECTS.count()` and reverts if the project does not exist.
-- **Transfer to `projectId` 0 via `transferOwnershipToProject()`.** Reverts with `JBOwnableOverrides_InvalidNewOwner`.
-- **Transfer to `projectId` exceeding `uint88`.** Reverts with `JBOwnableOverrides_InvalidNewOwner`.
-- **Undo `renounceOwnership()`.** Once ownership is renounced, all `onlyOwner` functions are permanently disabled. There is no recovery mechanism.
-- **Bypass `JBPermissions` for delegation.** Permission delegation is exclusively handled through the external `JBPermissions` contract; `JBOwnable` itself has no operator registry.
-- **Prevent project NFT transfers from changing ownership.** When owned by a project, whoever holds the `JBProjects` ERC-721 is the owner. There is no veto or lock mechanism within `JBOwnable`.
-- **Project ownership resolution can fail.** When owned by a project (`projectId != 0`), `owner()` calls `PROJECTS.ownerOf(projectId)`. If this call reverts (e.g., the project NFT is held by a contract that rejects ERC-721 queries), the resolved owner becomes `address(0)`, effectively and permanently renouncing the contract. This is an edge case but has no recovery path.
+- `src/JBOwnable.sol`
+- `src/JBOwnableOverrides.sol`
+- `src/structs/JBOwner.sol`
+- `test/OwnableInvariantTests.sol`
+- `test/OwnableEdgeCases.t.sol`
+- `test/regression/BurnLockProtection.t.sol`

package/ARCHITECTURE.md

@@ -1,63 +1,90 @@
-# nana-ownable-v6 — Architecture
+# Architecture
 
 ## Purpose
 
-Juicebox-aware ownership module. Extends OpenZeppelin's Ownable pattern to support ownership by either a Juicebox project (via ERC-721) or a direct address, with permission delegation through JBPermissions. The primary use case is contracts like `JB721TiersHook` that inherit `JBOwnable` so they can be owned by a Juicebox project rather than just an EOA -- ownership automatically follows the project's ERC-721 token without requiring manual transfers when the project changes hands.
+`nana-ownable-v6` adapts `Ownable` to the Juicebox model. A contract can be owned by an address or by a Juicebox project NFT, and delegated operators can satisfy `onlyOwner` through `JBPermissions`.
 
-## Contract Map
+## System Overview
 
-```
-src/
-├── JBOwnable.sol            — Concrete ownable with constructor
-├── JBOwnableOverrides.sol   — Abstract base with onlyOwner modifier logic
-├── interfaces/
-│   └── IJBOwnable.sol       — Interface for ownership queries and transfers
-└── structs/
-    └── JBOwner.sol          — Owner struct: {owner, projectId, permissionId}
-```
+The repo is an ownership primitive, not a policy layer. `JBOwnable` exposes a familiar inheritance surface. `JBOwnableOverrides` implements dynamic owner resolution, ownership transfer, renounce behavior, and delegated permission checks. Ownership can follow the current holder of a Juicebox project NFT instead of being fixed to an address.
 
-## Ownership Model
-
-```
-JBOwner {
-  address owner;       — Direct owner address (if projectId == 0)
-  uint88 projectId;    — JB project ID whose NFT holder is owner (if != 0)
-  uint8 permissionId;  — Permission ID that grants owner access via JBPermissions
-}
-
-Resolution order:
-1. If projectId != 0 → owner = JBProjects.ownerOf(projectId)
-2. If projectId == 0 → owner = JBOwner.owner address
-3. Additional access via JBPermissions.hasPermission(operator, owner, projectId, permissionId)
-```
+## Core Invariants
 
-## Key Operations
+- Project-owned contracts must resolve the owner dynamically from the current project NFT holder.
+- The delegated permission ID resets on ownership transfer.
+- Pointing ownership at an unminted project can temporarily lock the contract until that project exists.
+- A burned or otherwise unresolvable project NFT effectively renounces ownership.
+- This repo should stay a drop-in primitive, not grow product-specific access rules.
 
-### Ownership Transfer
-```
-Current owner → transferOwnership(newOwner)
-  → Can transfer to address or project ID
-  → Emits OwnershipTransferred
+## Modules
 
-Current owner → renounceOwnership()
-  → Sets owner to address(0), projectId to 0
-  → Permanently disables owner-only functions
-```
+| Module | Responsibility | Notes |
+| --- | --- | --- |
+| `JBOwnable` | Familiar `onlyOwner` inheritance target | Concrete surface |
+| `JBOwnableOverrides` | Resolution, transfer, renounce, and delegated-permission logic | Core behavior |
+| `JBOwner` | Packed owner state | Shared struct |
+| `IJBOwnable` | Public interface and events | Integration surface |
 
-## Design Decisions
+## Trust Boundaries
 
-### Project-as-owner instead of plain OpenZeppelin Ownable
-OpenZeppelin's `Ownable` binds ownership to a single address. In Juicebox, project ownership is represented by an ERC-721 (`JBProjects`), and the owner of that NFT can change over time. `JBOwnable` resolves ownership dynamically via `PROJECTS.ownerOf(projectId)`, so any contract owned by a project automatically tracks whoever holds the project NFT. This avoids the need to manually call `transferOwnership` on every peripheral contract when a project changes hands.
+- Ownership resolution depends on `JBProjects` and `JBPermissions` from `nana-core-v6`.
+- This repo does not create a new permission namespace.
+- Contracts that inherit from it may still add policy on top, but the resolution semantics here are infrastructure-level.
 
-### `permissionId` in the owner struct
-The `JBOwner` struct includes a `uint8 permissionId` that the owner can configure via `setPermissionId()`. This lets the owner delegate access to specific addresses through `JBPermissions` without transferring ownership itself. For example, a project owner can grant a multisig or automation contract the ability to call `onlyOwner` functions on a hook without giving up project ownership. The permission ID is reset to 0 on every ownership transfer to prevent stale permission grants from carrying over to new owners.
+## Critical Flows
 
-### Abstract base with concrete modifier
-`JBOwnableOverrides` is abstract and omits the `onlyOwner` modifier. The concrete `JBOwnable` adds it. This split exists because some inheriting contracts (like hooks deployed before a project NFT is minted) need to customize `_emitTransferEvent` -- the abstract base lets them override the event emission while reusing all ownership resolution and transfer logic.
+### Owner Check
 
-### Struct packing
-`JBOwner` packs `address owner` (160 bits), `uint88 projectId`, and `uint8 permissionId` into a single 256-bit storage slot. This means all ownership reads and writes cost one `SLOAD`/`SSTORE`, which matters because `_checkOwner` runs on every guarded call.
+```text
+onlyOwner modifier
+  -> load packed owner state
+  -> if project-owned, resolve the current project NFT holder
+  -> otherwise use the stored owner address
+  -> accept either the resolved owner or an operator with the configured JB permission
+```
 
-## Dependencies
-- `@bananapus/core-v6` — JBPermissioned, IJBProjects, IJBPermissions
-- `@openzeppelin/contracts` — Context
+## Accounting Model
+
+No treasury accounting lives here. The critical state is ownership resolution data and delegated permission ID.
+
+## Security Model
+
+- Ownership resolution edge cases are more important than surface API shape.
+- Permission delegation is simple conceptually but security-sensitive because it composes with a global permission registry.
+- Unresolvable project ownership is intentionally fail-closed. If `PROJECTS.ownerOf()` cannot resolve, `onlyOwner` should stop working rather than inventing fallback authority.
+
+## Safe Change Guide
+
+- Be conservative with transfer and renounce semantics.
+- If event emission or transfer behavior changes, inspect deployer wrappers and inheriting repos.
+- If project-based ownership semantics change, re-check unminted-project and unresolvable-project behavior explicitly.
+- Do not make delegated permission IDs sticky across ownership transfers.
+
+## Canonical Checks
+
+- baseline address-owner and project-owner behavior:
+  `test/Ownable.t.sol`
+- transfer, renounce, and hostile-call edge cases:
+  `test/OwnableEdgeCases.t.sol`
+  `test/OwnableAttacks.t.sol`
+- unminted-project and burn-lock safety:
+  `test/CodexUnmintedProjectHijack.t.sol`
+  `test/regression/BurnLockProtection.t.sol`
+- ownership-state invariants:
+  `test/OwnableInvariantTests.sol`
+
+## Source Map
+
+- `src/JBOwnable.sol`
+- `src/JBOwnableOverrides.sol`
+- `src/structs/JBOwner.sol`
+- `src/interfaces/IJBOwnable.sol`
+- `test/Ownable.t.sol`
+- `test/OwnableEdgeCases.t.sol`
+- `test/OwnableAttacks.t.sol`
+- `test/CodexUnmintedProjectHijack.t.sol`
+- `test/regression/BurnLockProtection.t.sol`
+- `test/regression/ZeroAddressValidation.t.sol`
+- `test/OwnableInvariantTests.sol`
+- `references/runtime.md`
+- `references/operations.md`

package/AUDIT_INSTRUCTIONS.md

@@ -1,187 +1,68 @@
-# Audit Instructions -- nana-ownable-v6
+# Audit Instructions
 
-You are auditing a Juicebox-aware ownership module that extends OpenZeppelin's Ownable pattern. A contract inheriting `JBOwnable` can be owned by a Juicebox project (via its ERC-721 NFT) or a direct address, with delegated access through `JBPermissions`. This is a foundational access control primitive used by hooks and extensions across the Juicebox V6 ecosystem. Read [RISKS.md](./RISKS.md) first -- it documents all known risks and trust assumptions. Then come back here.
+This repo provides ownership helpers that can follow Juicebox project NFTs instead of a fixed EOA. It is a small repo with disproportionate privilege impact.
 
-## Compiler and Version Info
+## Audit Objective
 
-| Setting | Value |
-|---------|-------|
-| Solidity version | ^0.8.26 |
-| EVM target | cancun |
-| Optimizer | enabled, 200 runs |
-| via-IR | not enabled |
-| Fuzz runs | 4,096 |
-| Invariant runs | 1,024 (depth 100) |
-
-Source: [`foundry.toml`](./foundry.toml)
+Find issues that:
+- let unauthorized actors satisfy owner checks
+- break ownership updates when a project NFT moves, burns, or locks
+- let override logic produce a different owner than the project system intends
+- leave dependent repos with stale or permanently wrong ownership views
 
 ## Scope
 
-**In scope -- all Solidity in `src/`:**
-```
-src/JBOwnable.sol                  # Concrete implementation with onlyOwner modifier (~76 lines)
-src/JBOwnableOverrides.sol         # Abstract base with all ownership logic (~244 lines)
-src/structs/JBOwner.sol            # Owner struct: {owner, projectId, permissionId} (~15 lines)
-src/interfaces/IJBOwnable.sol      # Interface (~47 lines)
-```
-
-**Out of scope:** Test files, JB Core contracts (`JBPermissioned`, `IJBPermissions`, `IJBProjects`), OpenZeppelin contracts, forge-std. Assume these dependencies are correct.
-
-## Architecture
-
-### Ownership Model
-
-The `JBOwner` struct packs into a single 256-bit storage slot:
-
-```solidity
-struct JBOwner {
-    address owner;       // 160 bits -- direct owner (used when projectId == 0)
-    uint88 projectId;    // 88 bits  -- JB project whose NFT holder is owner (used when != 0)
-    uint8 permissionId;  // 8 bits   -- JBPermissions ID for delegated access
-}
-```
-
-**Resolution rules:**
-1. If `projectId != 0`: owner = `PROJECTS.ownerOf(projectId)` (external call, try-catch wrapped)
-2. If `projectId == 0`: owner = `jbOwner.owner` (storage read)
-3. If the `ownerOf` call reverts (e.g., burned NFT): owner resolves to `address(0)`, effectively renouncing the contract
-
-**Delegated access:** `_checkOwner()` calls `_requirePermissionFrom(resolvedOwner, projectId, permissionId)` from `JBPermissioned`. This passes if `msg.sender == resolvedOwner` OR if `msg.sender` has the configured `permissionId` (or ROOT) in `JBPermissions`.
-
-### Inheritance Chain
-
-```
-JBOwnable (concrete)
-  extends JBOwnableOverrides (abstract)
-    extends Context (OpenZeppelin)
-    extends JBPermissioned (nana-core)
-    implements IJBOwnable (interface)
-```
-
-`JBOwnable` adds the `onlyOwner` modifier and implements `_emitTransferEvent`. `JBOwnableOverrides` contains all state management, transfer logic, and the `_checkOwner` function. Contracts that need custom `_emitTransferEvent` behavior inherit `JBOwnableOverrides` directly.
-
-### Key Functions
-
-| Function | Access | What it does |
-|----------|--------|--------------|
-| `owner()` | `public view` | Resolves and returns the current owner address. Makes an external call to `PROJECTS.ownerOf()` when project-owned. |
-| `transferOwnership(address newOwner)` | `onlyOwner` | Transfers ownership to a direct address. Reverts on `address(0)`. Resets `permissionId` to 0. |
-| `transferOwnershipToProject(uint256 projectId)` | `onlyOwner` | Transfers ownership to a JB project. Validates: non-zero, fits `uint88`, project exists (`<= PROJECTS.count()`). Resets `permissionId` to 0. |
-| `renounceOwnership()` | `onlyOwner` | Sets owner to `address(0)` and projectId to 0. Irreversible. |
-| `setPermissionId(uint8 permissionId)` | `onlyOwner` | Sets which JBPermissions ID grants delegated owner access. |
-| `_checkOwner()` | `internal view` | Resolves owner, then calls `_requirePermissionFrom`. Used by `onlyOwner` modifier. |
-| `_transferOwnership(address, uint88)` | `internal` | Core transfer logic. Updates `jbOwner`, resets `permissionId`, calls `_emitTransferEvent`. No access restriction. |
-
-## Priority Audit Areas
-
-### 1. Ownership Resolution Correctness (Highest Priority)
-
-The `owner()` and `_checkOwner()` functions both resolve ownership via the same pattern but are separate implementations (not shared helper). Verify:
-
-- **Consistency between `owner()` and `_checkOwner()`.** Both use try-catch on `PROJECTS.ownerOf()` and fall back to `address(0)` on revert. Verify they always agree on who the owner is. A divergence could allow someone to pass `_checkOwner()` while `owner()` returns a different address (or vice versa).
-- **Try-catch scope.** The try-catch catches ALL reverts from `PROJECTS.ownerOf()`, including out-of-gas. Could an attacker force an OOG in the external call to make `_checkOwner()` resolve to `address(0)`, then bypass access control? (This would require `_requirePermissionFrom(address(0), ...)` to pass, which should not be possible for any non-zero `msg.sender` unless they have ROOT permission for the project.)
-- **Zero-address as resolved owner.** When the resolved owner is `address(0)` (burned NFT or renounced), `_requirePermissionFrom(address(0), projectId, permissionId)` should revert for any caller. Verify this holds in `JBPermissioned` -- specifically that `msg.sender != address(0)` and no permission is granted to `address(0)`.
-
-### 2. Ownership Transfer State Machine
-
-Ownership transitions must be airtight:
-
-- **Mutual exclusivity.** `_transferOwnership(address newOwner, uint88 projectId)` reverts if both are non-zero. Verify there is no code path that sets both `jbOwner.owner` and `jbOwner.projectId` to non-zero values simultaneously.
-- **Permission reset.** Every ownership transfer resets `permissionId` to 0. Verify this happens in `_transferOwnership` (it does -- the entire `JBOwner` struct is overwritten). Verify there is no path to transfer ownership without going through `_transferOwnership`.
-- **Constructor validation.** The constructor rejects `(address(0), 0)` as initial owner (both zero). It also rejects `(non-zero projectId, address(0) projects)`. Verify these are the only two invalid initial states.
-- **Project existence check.** `transferOwnershipToProject` checks `projectId <= PROJECTS.count()`. Verify this prevents transferring to a non-existent project. Note: `PROJECTS.count()` returns the total number of projects ever created, and project IDs are sequential starting from 1.
-
-### 3. Permission Delegation Security
-
-`_checkOwner()` delegates to `_requirePermissionFrom(resolvedOwner, projectId, permissionId)`. Verify:
-
-- **When `permissionId == 0`.** Permission ID 0 is forbidden in `JBPermissions` (cannot be set). This means when `permissionId` is 0 (the default after any transfer), ONLY the resolved owner or ROOT holders can pass `_checkOwner()`. Delegated access is effectively disabled until `setPermissionId()` is called.
-- **ROOT override.** ROOT (permission ID 1) always grants access via `_requirePermissionFrom`. An address with ROOT for the relevant project can act as owner of any `JBOwnable` contract owned by that project, regardless of the configured `permissionId`. Verify this is intentional and documented.
-- **Wildcard project ID.** Permissions granted with `projectId = 0` in `JBPermissions` apply to all projects. Verify that a wildcard ROOT grant (which `JBPermissions` should reject) cannot be used to bypass `_checkOwner()`.
-
-### 4. Renunciation Edge Cases
-
-- **Renouncing when project-owned.** If `projectId != 0` and the NFT holder calls `renounceOwnership()`, both `owner` and `projectId` are set to 0. Verify the NFT holder can still call `renounceOwnership()` (passes `_checkOwner` with the project-resolved owner).
-- **Implicit renunciation via unreachable `ownerOf`.** JBProjects V6 has no burn function, so `PROJECTS.ownerOf()` cannot revert for a valid project ID under normal conditions. The try-catch in `owner()` and `_checkOwner()` is a defensive measure against hypothetical future changes to `JBProjects` or unexpected ERC-721 behavior. If `ownerOf` ever did revert, `owner()` would return `address(0)` and `_checkOwner()` would revert for all callers -- the contract would be effectively renounced without anyone calling `renounceOwnership()`. Verify this state is consistent and cannot be escaped.
-- **Double renounce.** After renouncing, calling `renounceOwnership()` again should revert because `_checkOwner()` will fail (resolved owner is `address(0)` and `msg.sender` cannot be `address(0)`).
-
-### 5. Storage Slot Packing
-
-The `JBOwner` struct fits in a single 256-bit slot: `address` (160) + `uint88` (88) + `uint8` (8) = 256. Verify:
-- The Solidity compiler lays out the struct as expected (no padding gaps).
-- The `_transferOwnership` function writes the entire struct atomically (`jbOwner = JBOwner({...})`), preventing partial-write inconsistencies.
-
-## Invariants to Verify
-
-1. **Mutual exclusivity**: At no point can both `jbOwner.owner != address(0)` and `jbOwner.projectId != 0`.
-2. **Transfer resets permission**: After any call to `_transferOwnership`, `jbOwner.permissionId == 0`.
-3. **Renounce is terminal**: After `renounceOwnership()`, `jbOwner.owner == address(0)` AND `jbOwner.projectId == 0` AND all subsequent `_checkOwner()` calls revert.
-4. **owner() consistency**: `owner()` and the resolved owner in `_checkOwner()` always agree.
-5. **No unauthorized transfer**: Only addresses passing `_checkOwner()` can call `transferOwnership`, `transferOwnershipToProject`, `renounceOwnership`, or `setPermissionId`.
-
-## Testing Setup
-
-```bash
-cd nana-ownable-v6
-npm install
-forge build
-forge test
-
-# Run attack scenarios
-forge test --match-contract OwnableAttacks -vvv
-
-# Run edge cases
-forge test --match-contract OwnableEdgeCases -vvv
+In scope:
+- `src/JBOwnable.sol`
+- `src/JBOwnableOverrides.sol`
+- `src/interfaces/`
+- `src/structs/`
 
-# Run invariant tests
-forge test --match-contract OwnableInvariant -vvv
+## Start Here
 
-# Run regression tests
-forge test --match-path test/regression/ -vvv
+1. `src/JBOwnable.sol`
+2. `src/JBOwnableOverrides.sol`
 
-# Write a PoC (create test/YourExploit.t.sol)
-forge test --match-path test/YourExploit.t.sol -vvv
-```
+## Security Model
 
-## Error Reference
+These contracts abstract “owner” as a project-based identity. Downstream repos use them to:
+- treat a Juicebox project owner as contract owner
+- apply per-project override rules
+- keep admin power aligned with project NFT ownership instead of a static address
 
-All custom errors are defined in `src/JBOwnableOverrides.sol`.
+## Roles And Privileges
 
-| Error | Trigger Condition |
-|-------|-------------------|
-| `JBOwnableOverrides_InvalidNewOwner()` | (1) Constructor called with both `initialOwner == address(0)` and `initialProjectIdOwner == 0`. (2) `transferOwnership()` called with `newOwner == address(0)`. (3) `transferOwnershipToProject()` called with `projectId == 0` or `projectId > type(uint88).max`. (4) `_transferOwnership(address, uint88)` called with both `newOwner != address(0)` and `projectId != 0`. |
-| `JBOwnableOverrides_ProjectDoesNotExist()` | `transferOwnershipToProject()` called with a `projectId` greater than `PROJECTS.count()` (the project has not been minted yet). |
-| `JBOwnableOverrides_ZeroAddressProjectsWithProjectOwner()` | Constructor called with `initialProjectIdOwner != 0` and `address(projects) == address(0)`. Prevents deploying with project-based ownership when no `JBProjects` contract is provided. |
+| Role | Powers | How constrained |
+|------|--------|-----------------|
+| Project NFT owner | Become the effective contract owner | Should update automatically with NFT transfers |
+| Override authority | Set alternative owner resolution where allowed | Must not outrank project ownership unexpectedly |
 
-## Previous Audit Findings
+## Integration Assumptions
 
-A Nemesis audit (Feynman + State Inconsistency methodology) was conducted on 2026-03-17. Full results are in `.audit/findings/nemesis-verified.md`.
+| Dependency | Assumption | What breaks if wrong |
+|------------|------------|----------------------|
+| Juicebox project ownership | NFT ownership reflects intended authority | Downstream admin checks drift from reality |
 
-**Result: 0 Critical | 0 High | 0 Medium | 2 Low (informational)**
+## Critical Invariants
 
-| ID | Severity | Summary |
-|----|----------|---------|
-| NM-001 | LOW | Constructor lacks explicit project existence check -- deploys with a non-existent `initialProjectIdOwner` revert with an opaque ERC-721 error instead of `JBOwnableOverrides_ProjectDoesNotExist()`. Developer experience only, no security impact. |
-| NM-002 | LOW | `_emitTransferEvent` in `JBOwnable` does not use try-catch for `PROJECTS.ownerOf()`, unlike `owner()` and `_checkOwner()`. This is a deliberate design tradeoff: write-path failures should revert (preventing incorrect event data), while read-path failures degrade gracefully. |
+1. Owner resolution is correct
+For any supported mode, `owner()` or equivalent checks must resolve to the intended authority and no one else.
 
-No other formal audit with finding IDs has been conducted.
+2. Burn and lock behavior is safe
+If project ownership is intentionally burned or locked, the helper must not accidentally reopen control or brick valid admin paths.
 
-## How to Report Findings
+3. Override precedence is coherent
+Overrides must not silently supersede project ownership in cases the design does not permit.
 
-**Severity guide:**
-- **CRITICAL**: Direct fund loss, permanent DoS, or broken core invariant. Exploitable with no preconditions.
-- **HIGH**: Conditional fund loss, privilege escalation, or broken invariant. Requires specific but realistic setup.
-- **MEDIUM**: Value leakage, griefing with cost to attacker, incorrect accounting, degraded functionality.
-- **LOW**: Informational, cosmetic, edge-case-only with no material impact.
+## Attack Surfaces
 
-For each finding:
+- owner resolution after project NFT transfer
+- zero-address, burn, and lock states
+- override configuration and precedence
+- downstream assumptions that cache owner state instead of re-reading it
 
-1. **Title** -- one line, starts with severity (CRITICAL/HIGH/MEDIUM/LOW)
-2. **Affected contract(s)** -- exact file path and line numbers
-3. **Description** -- what's wrong, in plain language
-4. **Trigger sequence** -- step-by-step, minimal steps to reproduce
-5. **Impact** -- what an attacker gains, what a user loses (with numbers if possible)
-6. **Proof** -- code trace showing the exact execution path, or a Foundry test
-7. **Fix** -- minimal code change that resolves the issue
+## Verification
 
-Go break it.
+- `npm install`
+- `forge build`
+- `forge test`

package/CHANGELOG.md

@@ -0,0 +1,39 @@
+# Changelog
+
+## Scope
+
+This file describes the verified change from `nana-ownable-v5` to the current `nana-ownable-v6` repo.
+
+## Current v6 surface
+
+- `JBOwnable`
+- `JBOwnableOverrides`
+- `IJBOwnable`
+- `JBOwner`
+
+## Summary
+
+- Project-backed ownership is more defensive than in v5. The current implementation tolerates invalid or burned project NFTs by handling `ownerOf` failures instead of surfacing them as unchecked behavior.
+- The project-ownership path validates its inputs more strictly before transferring control to a project.
+- The implementation files now compile on the v6 `0.8.28` baseline instead of the old floating `^0.8.23` setup.
+
+## Verified deltas
+
+- `JBOwnable` now emits ownership-transfer events through `_msgSender()` instead of raw `msg.sender`.
+- The transfer-event path is explicitly documented to revert when the new project does not exist, instead of silently tolerating a bad target.
+- The current imports point at `core-v6`, not `core-v5`.
+
+## Breaking ABI changes
+
+- There is no meaningful public function migration in `IJBOwnable`; the interface mostly preserved its shape.
+- The important migration is behavioral: project-backed ownership resolution and transfer validation are stricter.
+
+## Indexer impact
+
+- Event names are stable, but the `caller` field is now emitted through `_msgSender()` semantics in the implementation.
+- Meta-transaction-aware consumers should prefer the v6 behavior over raw-`msg.sender` assumptions.
+
+## Migration notes
+
+- If you depended on `owner()` reverting for invalid project-backed ownership states, revisit that expectation.
+- Rebuild imports against the v6 core package and the current ownable contracts. This repo is small, but the behavior is intentionally stricter than v5.