@bananapus/ownable-v6 0.0.17 → 0.0.19

package/STYLE_GUIDE.md

@@ -21,13 +21,13 @@ One contract/interface/struct/enum per file. Name the file after the type it con
 
 ```solidity
 // Contracts — pin to exact version
-pragma solidity ^0.8.26;
+pragma solidity 0.8.28;
 
 // Interfaces, structs, enums — caret for forward compatibility
 pragma solidity ^0.8.0;
 
-// Libraries — caret, may use newer features
-pragma solidity ^0.8.17;
+// Libraries — pin to exact version like contracts
+pragma solidity 0.8.28;
 ```
 
 ## Imports
@@ -86,12 +86,20 @@ contract JBExample is JBPermissioned, IJBExample {
 
     uint256 internal constant _FEE_BENEFICIARY_PROJECT_ID = 1;
 
+    //*********************************************************************//
+    // ------------------------ private constants ------------------------ //
+    //*********************************************************************//
+
     //*********************************************************************//
     // --------------- public immutable stored properties ---------------- //
     //*********************************************************************//
 
     IJBDirectory public immutable override DIRECTORY;
 
+    //*********************************************************************//
+    // -------------- internal immutable stored properties -------------- //
+    //*********************************************************************//
+
     //*********************************************************************//
     // --------------------- public stored properties -------------------- //
     //*********************************************************************//
@@ -100,10 +108,26 @@ contract JBExample is JBPermissioned, IJBExample {
     // -------------------- internal stored properties ------------------- //
     //*********************************************************************//
 
+    //*********************************************************************//
+    // -------------------- private stored properties -------------------- //
+    //*********************************************************************//
+
+    //*********************************************************************//
+    // ------------------- transient stored properties ------------------- //
+    //*********************************************************************//
+
     //*********************************************************************//
     // -------------------------- constructor ---------------------------- //
     //*********************************************************************//
 
+    //*********************************************************************//
+    // ---------------------------- modifiers ---------------------------- //
+    //*********************************************************************//
+
+    //*********************************************************************//
+    // ------------------------- receive / fallback ---------------------- //
+    //*********************************************************************//
+
     //*********************************************************************//
     // ---------------------- external transactions ---------------------- //
     //*********************************************************************//
@@ -112,10 +136,18 @@ contract JBExample is JBPermissioned, IJBExample {
     // ----------------------- external views ---------------------------- //
     //*********************************************************************//
 
+    //*********************************************************************//
+    // -------------------------- public views --------------------------- //
+    //*********************************************************************//
+
     //*********************************************************************//
     // ----------------------- public transactions ----------------------- //
     //*********************************************************************//
 
+    //*********************************************************************//
+    // ---------------------- internal transactions ---------------------- //
+    //*********************************************************************//
+
     //*********************************************************************//
     // ----------------------- internal helpers -------------------------- //
     //*********************************************************************//
@@ -134,17 +166,28 @@ contract JBExample is JBPermissioned, IJBExample {
 1. Custom errors
 2. Public constants
 3. Internal constants
-4. Public immutable stored properties
-5. Internal immutable stored properties
-6. Public stored properties
-7. Internal stored properties
-8. Constructor
-9. External transactions
-10. External views
-11. Public transactions
-12. Internal helpers
-13. Internal views
-14. Private helpers
+4. Private constants
+5. Public immutable stored properties
+6. Internal immutable stored properties
+7. Public stored properties
+8. Internal stored properties
+9. Private stored properties
+10. Transient stored properties
+11. Constructor
+12. Modifiers
+13. Receive / fallback
+14. External transactions
+15. External views
+16. Public views
+17. Public transactions
+18. Internal transactions
+19. Internal helpers
+20. Internal views
+21. Private helpers
+
+Use these additional section labels where they better match the contents of the block:
+- `internal functions` is accepted as equivalent to `internal helpers`
+- `events` and `structs` are acceptable in specialized contracts that define them explicitly
 
 Functions are alphabetized within each section.
 
@@ -326,7 +369,7 @@ Standard config across all repos:
 
 ```toml
 [profile.default]
-solc = '0.8.26'
+solc = '0.8.28'
 evm_version = 'cancun'
 optimizer_runs = 200
 libs = ["node_modules", "lib"]
@@ -565,8 +608,3 @@ CI checks formatting via `forge fmt --check`.
 ### Contract Size Checks
 
 CI runs `forge build --sizes` to catch contracts approaching the 24KB limit. When the repo's default `optimizer_runs` differs from what you want for size checking, use `FOUNDRY_PROFILE=ci_sizes forge build --sizes` with a `[profile.ci_sizes]` section in `foundry.toml`.
-
-
-## Repo-Specific Deviations
-
-None. This repo follows the standard configuration exactly.

package/USER_JOURNEYS.md

@@ -1,200 +1,119 @@
-# User Journeys -- nana-ownable-v6
+# User Journeys
 
-Concrete end-to-end flows through the JBOwnable system. Each journey traces the exact function calls, state changes, events, and edge cases.
+## Repo Purpose
 
----
+This repo adapts `Ownable`-style control to Juicebox project ownership and project-scoped operator permissions.
+It is an ownership adapter. It does not replace the underlying ownership or permission registries in
+[nana-core-v6](../nana-core-v6/USER_JOURNEYS.md).
 
-## Journey 1: Deploy a Project-Owned Contract
+## Primary Actors
 
-**Entry point**: `new MyHook(IJBPermissions permissions, IJBProjects projects, address(0), uint88 projectId)`
+- protocol or product teams that want `onlyOwner` to follow a project NFT
+- operators who need owner-like access without receiving the project itself
+- auditors checking whether delegated owner semantics strand or over-grant authority
 
-**Who can call**: Anyone (deployment is permissionless).
+## Key Surfaces
 
-**Parameters**:
-- `permissions` -- The `IJBPermissions` contract used for delegated access checks
-- `projects` -- The `IJBProjects` contract used to resolve project NFT ownership
-- `initialOwner` -- Set to `address(0)` because ownership is project-based
-- `initialProjectIdOwner` -- The ID of the Juicebox project whose NFT holder becomes the owner
+- `JBOwnable`: `Ownable`-style adapter whose owner follows a Juicebox project
+- `JBOwnableOverrides`: extension that lets a project-scoped permission satisfy `onlyOwner`
+- `owner()`, `transferOwnership(...)`, `transferOwnershipToProject(...)`, `setPermissionId(...)`: core ownership-resolution and migration paths
 
-**State changes**:
-1. `PROJECTS` immutable set to `projects`
-2. `PERMISSIONS` immutable set to `permissions` (inherited from `JBPermissioned`)
-3. Constructor validates that if `initialProjectIdOwner != 0`, then `address(projects) != address(0)` (reverts with `JBOwnableOverrides_ZeroAddressProjectsWithProjectOwner` if the project ID is non-zero but the projects contract is the zero address). There is no project existence check in the constructor.
-4. Constructor validates that at least one of `initialOwner` or `initialProjectIdOwner` is non-zero (reverts with `JBOwnableOverrides_InvalidNewOwner` if both are zero)
-5. `_transferOwnership(address(0), projectId)` executes:
-   - Sets `jbOwner = JBOwner({owner: address(0), projectId: projectId, permissionId: 0})`
-   - Calls `_emitTransferEvent(address(0), address(0), projectId)`
-6. `owner()` now resolves dynamically via `PROJECTS.ownerOf(projectId)`
+## Journey 1: Give A Contract To A Juicebox Project Instead Of A Wallet
 
-**Events**: `OwnershipTransferred(address indexed previousOwner, address indexed newOwner, address caller)` -- emitted as `OwnershipTransferred(address(0), PROJECTS.ownerOf(projectId), msg.sender)`
+**Actor:** downstream contract author.
 
-**Edge cases**:
-- If the project does not exist (ID > `PROJECTS.count()`), the constructor still succeeds -- the existence check is only enforced in `transferOwnershipToProject`, not the constructor. If the project NFT has not yet been minted, `PROJECTS.ownerOf()` reverts, and the try-catch in `owner()` returns `address(0)`, effectively locking the contract until the project is minted.
-- `owner()` returns the current NFT holder dynamically. If the NFT is transferred, ownership automatically follows -- no on-chain update to the JBOwnable contract is needed.
-- Deploying with both `initialOwner == address(0)` and `initialProjectIdOwner == 0` reverts with `JBOwnableOverrides_InvalidNewOwner`. To create an unowned contract, set an owner and call `renounceOwnership()` in the constructor body.
+**Intent:** make a contract follow Juicebox project ownership instead of a fixed EOA or multisig.
 
-**What to verify**:
-- `jbOwner.owner == address(0)` and `jbOwner.projectId == projectId` after construction
-- `jbOwner.permissionId == 0` (no delegated access until explicitly configured)
-- `owner()` returns the current NFT holder, not a cached value
+**Preconditions**
+- the downstream contract wants `onlyOwner` ergonomics
+- a project ID and `JBProjects` dependency are already known
 
----
+**Main Flow**
+1. Inherit `JBOwnable` or `JBOwnableOverrides`.
+2. Initialize ownership with the relevant project ID and `JBProjects` reference.
+3. Let `owner()` resolve through the current project NFT holder rather than a fixed address.
 
-## Journey 1b: Deploy an Address-Owned Contract
+**Failure Modes**
+- the contract assumes ordinary `Ownable` transfer semantics after adopting project-based ownership
+- the wrong project ID is configured
+- reviewers ignore the adapter and audit the downstream contract as if `owner` were fixed
 
-**Entry point**: `new MyHook(IJBPermissions permissions, IJBProjects projects, address initialOwner, uint88(0))`
+**Postconditions**
+- `owner()` now resolves through the configured project NFT instead of a fixed wallet
 
-**Who can call**: Anyone (deployment is permissionless).
+## Journey 2: Delegate Owner-Level Access To Operators
 
-**Parameters**:
-- `permissions` -- The `IJBPermissions` contract used for delegated access checks
-- `projects` -- The `IJBProjects` contract (can be `address(0)` when not using project-based ownership)
-- `initialOwner` -- The address that becomes the contract owner (must not be `address(0)`)
-- `initialProjectIdOwner` -- Set to `0` because ownership is address-based
+**Actor:** current project owner.
 
-**State changes**:
-1. `PROJECTS` immutable set to `projects`
-2. `PERMISSIONS` immutable set to `permissions` (inherited from `JBPermissioned`)
-3. Constructor validates that `initialOwner != address(0)` (reverts with `JBOwnableOverrides_InvalidNewOwner` if both `initialOwner` and `initialProjectIdOwner` are zero)
-4. `_transferOwnership(initialOwner, 0)` executes:
-   - Sets `jbOwner = JBOwner({owner: initialOwner, projectId: 0, permissionId: 0})`
-   - Calls `_emitTransferEvent(address(0), initialOwner, 0)`
+**Intent:** let an operator satisfy `onlyOwner` for one contract without transferring the project.
 
-**Events**: `OwnershipTransferred(address indexed previousOwner, address indexed newOwner, address caller)` -- emitted as `OwnershipTransferred(address(0), initialOwner, msg.sender)`
+**Preconditions**
+- the downstream contract uses `JBOwnableOverrides`
+- the team has chosen the permission ID that should count as delegated owner access
 
-**Edge cases**:
-- `owner()` returns `jbOwner.owner` directly (no `PROJECTS.ownerOf()` lookup since `projectId == 0`)
-- Ownership does NOT follow NFT transfers -- it is static until explicitly transferred via `transferOwnership()` or `transferOwnershipToProject()`
-- `PROJECTS` can be `address(0)` in this mode since it is never consulted for ownership resolution. However, `transferOwnershipToProject()` will revert if `PROJECTS` is `address(0)` (the `PROJECTS.count()` call reverts).
+**Main Flow**
+1. Choose the permission ID the downstream contract should respect.
+2. Grant that permission through `JBPermissions`.
+3. `JBOwnableOverrides` treats the operator as satisfying `onlyOwner` for that contract.
 
----
+**Failure Modes**
+- teams grant a broader permission than intended
+- downstream reviewers forget that `onlyOwner` may resolve through permissions instead of direct ownership
+- operators retain stale permissions after governance changes
 
-## Journey 2: Transfer Ownership to a Different Address
+**Postconditions**
+- the chosen operator can satisfy `onlyOwner` without receiving direct ownership of the project or contract
 
-**Entry point**: `JBOwnableOverrides.transferOwnership(address newOwner)`
+## Journey 3: Change The Delegated Permission ID Without Changing Ownership
 
-**Who can call**: The current owner (resolved via `PROJECTS.ownerOf()` if project-owned, or `jbOwner.owner` if address-owned), or any address with the configured `permissionId` (or ROOT) via `JBPermissions`.
+**Actor:** current effective owner.
 
-**Parameters**:
-- `newOwner` -- The address to transfer ownership to (must not be `address(0)`)
+**Intent:** rotate delegated owner policy without changing the underlying owner.
 
-**State changes**:
-1. `_checkOwner()` validates the caller against the resolved owner and `permissionId`
-2. Validates `newOwner != address(0)` (reverts with `JBOwnableOverrides_InvalidNewOwner`)
-3. `_transferOwnership(newOwner, 0)` executes:
-   - Records `oldOwner` (resolved from current `jbOwner`, with try-catch for burned project NFTs)
-   - Overwrites `jbOwner = JBOwner({owner: newOwner, projectId: 0, permissionId: 0})`
-   - Calls `_emitTransferEvent(oldOwner, newOwner, 0)`
+**Preconditions**
+- the contract already uses `JBOwnableOverrides`
+- all operators who need continued access can be regranted under the new permission ID
 
-**Events**: `OwnershipTransferred(address indexed previousOwner, address indexed newOwner, address caller)` -- emitted as `OwnershipTransferred(oldOwner, newOwner, msg.sender)`
+**Main Flow**
+1. Update the permission ID the adapter treats as owner-equivalent with `setPermissionId(...)`.
+2. Re-grant the new permission where needed.
+3. Re-audit operator assumptions because the old permission no longer satisfies `onlyOwner`.
 
-**Edge cases**:
-- If the contract was previously project-owned, `projectId` is now 0 (project ownership is cleared)
-- `permissionId` is reset to 0, revoking all previously delegated permissions. The new owner must call `setPermissionId()` to re-enable delegated access.
-- The previous owner (or their delegates) can no longer call `onlyOwner` functions
-- `newOwner` can immediately call `onlyOwner` functions without any additional setup
+**Failure Modes**
+- operator access disappears unintentionally after a permission-ID rotation
+- teams forget that old delegations stop working immediately
 
----
+**Postconditions**
+- the adapter now resolves delegated owner access through the new permission ID only
 
-## Journey 3: Transfer Ownership to a Juicebox Project
+## Journey 4: Transfer Or Burn Ownership Deliberately
 
-**Entry point**: `JBOwnableOverrides.transferOwnershipToProject(uint256 projectId)`
+**Actor:** current effective owner.
 
-**Who can call**: The current owner (resolved via `PROJECTS.ownerOf()` if project-owned, or `jbOwner.owner` if address-owned), or any address with the configured `permissionId` (or ROOT) via `JBPermissions`.
+**Intent:** move or remove control with full awareness of the consequences.
 
-**Parameters**:
-- `projectId` -- The ID of the Juicebox project to transfer ownership to (must be non-zero, fit in `uint88`, and refer to an existing project)
+**Preconditions**
+- the team understands whether admin recovery should remain possible
+- downstream integrations can tolerate the new owner model
 
-**State changes**:
-1. `_checkOwner()` validates the caller
-2. Validates `projectId != 0` and `projectId <= type(uint88).max` (reverts with `JBOwnableOverrides_InvalidNewOwner`)
-3. Validates `projectId <= PROJECTS.count()` (reverts with `JBOwnableOverrides_ProjectDoesNotExist`)
-4. `_transferOwnership(address(0), uint88(projectId))` executes:
-   - Records `oldOwner` (resolved from current `jbOwner`)
-   - Overwrites `jbOwner = JBOwner({owner: address(0), projectId: uint88(projectId), permissionId: 0})`
-   - Calls `_emitTransferEvent(oldOwner, address(0), uint88(projectId))`
+**Main Flow**
+1. Use `transferOwnership(...)` for an address owner or `transferOwnershipToProject(...)` for a project owner.
+2. Re-establish delegated permission policy if the new owner still wants operators.
+3. Renounce or burn only when permanent admin loss is intentional.
 
-**Events**: `OwnershipTransferred(address indexed previousOwner, address indexed newOwner, address caller)` -- emitted as `OwnershipTransferred(oldOwner, PROJECTS.ownerOf(projectId), msg.sender)`
+**Failure Modes**
+- ownership is burned even though the downstream contract still needs administration
+- teams forget that permission-ID delegation resets across ownership changes
 
-**Edge cases**:
-- The project existence check (`projectId <= PROJECTS.count()`) prevents transferring to a nonexistent project
-- The `uint88` cast does not truncate (the preceding `type(uint88).max` check ensures this)
-- `permissionId` is reset to 0 on transfer. The new project owner must call `setPermissionId()` to configure delegation.
-- If the project NFT is subsequently burned (hypothetically), `owner()` returns `address(0)` and the contract is effectively renounced
-- Unlike the constructor, `_emitTransferEvent` calls `PROJECTS.ownerOf(newProjectId)` without try-catch -- if the project does not exist, the transaction reverts. This is intentional: the `PROJECTS.count()` check above prevents this path.
+**Postconditions**
+- control moves to the chosen address or project, or is intentionally removed
 
----
+## Trust Boundaries
 
-## Journey 4: Delegate Access via Permission ID
+- this repo trusts `JBProjects` for project ownership and `JBPermissions` for delegated authority
+- downstream contracts still need their own audit because this adapter changes who satisfies `onlyOwner`
 
-**Entry point**: `JBOwnableOverrides.setPermissionId(uint8 permissionId)`
+## Hand-Offs
 
-**Who can call**: The current owner (resolved via `PROJECTS.ownerOf()` if project-owned, or `jbOwner.owner` if address-owned), or any address with the currently configured `permissionId` (or ROOT) via `JBPermissions`.
-
-**Parameters**:
-- `permissionId` -- The new permission ID to use for `onlyOwner` access delegation
-
-**State changes**:
-1. `_checkOwner()` validates the caller
-2. `_setPermissionId(permissionId)` writes `jbOwner.permissionId = permissionId`
-
-**Events**: `PermissionIdChanged(uint8 newId, address caller)` -- emitted as `PermissionIdChanged(permissionId, msg.sender)`
-
-**Granting the permission to operators** (external step, not on JBOwnable):
-- The owner calls `permissions.setPermissionsFor(account, JBPermissionsData({operator: operatorAddress, projectId: projectId, permissionIds: [permissionId]}))` on the `JBPermissions` contract
-- Operators can then call any `onlyOwner` function. `_checkOwner()` resolves the owner and calls `_requirePermissionFrom(resolvedOwner, projectId, permissionId)`, which passes if the operator has the matching permission.
-
-**Edge cases**:
-- `permissionId == 0` effectively disables delegation (permission ID 0 cannot be set in `JBPermissions`). Only the owner (or ROOT holders) can call `onlyOwner` functions.
-- If the owner transfers ownership, `permissionId` resets to 0. The new owner must re-configure delegation.
-- ROOT (permission ID 1) bypasses the configured `permissionId` check, but only when the operator has been granted ROOT **by the resolved owner** via `JBPermissions`. ROOT is not a global override -- it is scoped to the `account` (i.e. the resolved owner) that granted it. This is a feature of `JBPermissioned`, not specific to `JBOwnable`. After renouncement (resolved owner = `address(0)`), ROOT cannot help because no one can obtain permissions granted by `address(0)`.
-- The operator's access is not stored on the JBOwnable contract -- it lives in JBPermissions. Changing the `permissionId` on JBOwnable instantly changes which JBPermissions grants are recognized.
-
----
-
-## Journey 5: Renounce Ownership
-
-**Entry point**: `JBOwnableOverrides.renounceOwnership()`
-
-**Who can call**: The current owner (resolved via `PROJECTS.ownerOf()` if project-owned, or `jbOwner.owner` if address-owned), or any address with the configured `permissionId` (or ROOT) via `JBPermissions`.
-
-**Parameters**: None.
-
-**State changes**:
-1. `_checkOwner()` validates the caller
-2. `_transferOwnership(address(0), 0)` executes:
-   - Records `oldOwner` (resolved from current `jbOwner`)
-   - Overwrites `jbOwner = JBOwner({owner: address(0), projectId: 0, permissionId: 0})`
-   - Calls `_emitTransferEvent(oldOwner, address(0), 0)`
-
-**Events**: `OwnershipTransferred(address indexed previousOwner, address indexed newOwner, address caller)` -- emitted as `OwnershipTransferred(oldOwner, address(0), msg.sender)`
-
-**Edge cases**:
-- After renouncing, `transferOwnership`, `transferOwnershipToProject`, `setPermissionId`, and `renounceOwnership` all revert
-- There is no recovery mechanism. No admin backdoor. No timelock. Renouncement is permanent.
-- A second call to `renounceOwnership()` also reverts (because `_checkOwner()` fails)
-- Even ROOT holders cannot act as owner after renouncement. Although `_requirePermissionFrom(address(0), 0, 0)` is called with `includeRoot: true`, no operator can possess ROOT (or any permission) granted by `address(0)` -- `JBPermissions.setPermissionsFor` requires the caller to be the account or an existing ROOT operator of the account, and no one starts with permissions from `address(0)`
-
----
-
-## Journey 6: Implicit Renouncement via Project NFT Burn
-
-**Actor**: None (system behavior).
-
-**Who can call**: N/A -- this is an emergent behavior, not a direct function call.
-
-**Parameters**: None.
-
-**Precondition**: The contract is project-owned (`jbOwner.projectId != 0`). The project NFT is burned or otherwise invalidated (note: JBProjects V6 has no burn function, so this is a defensive scenario).
-
-**State changes**:
-1. `PROJECTS.ownerOf(projectId)` starts reverting (ERC-721 `ownerOf` reverts for burned tokens)
-2. `owner()` catches the revert via try-catch and returns `address(0)`
-3. `_checkOwner()` catches the revert and resolves owner to `address(0)`, causing `_requirePermissionFrom(address(0), projectId, permissionId)` to fail for any `msg.sender` -- no operator can possess permissions granted by `address(0)` (same reason as explicit renouncement in Journey 5)
-
-**Events**: None (no transaction occurs on the JBOwnable contract).
-
-**Edge cases**:
-- There is no way to "revive" ownership after the NFT is burned. However, re-minting an NFT with the same ID (if possible) would restore ownership.
-- The `jbOwner` struct is NOT cleared -- it still shows the old `projectId`. Only the resolved owner is `address(0)`.
-- This behavior is consistent between `owner()` and `_checkOwner()` (both use the same try-catch pattern)
+- Use [nana-core-v6](../nana-core-v6/USER_JOURNEYS.md) for the project-NFT and permission machinery this adapter depends on.
+- Use [nana-permission-ids-v6](../nana-permission-ids-v6/USER_JOURNEYS.md) if you need the shared numeric permission vocabulary for delegated `onlyOwner` checks.

package/foundry.toml

@@ -13,6 +13,8 @@ runs = 1024
 depth = 100
 fail_on_revert = false
 
+[lint]
+exclude_lints = ["pascal-case-struct", "mixed-case-variable"]
 [fmt]
 number_underscore = "thousands"
 multiline_func_header = "all"

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bananapus/ownable-v6",
-  "version": "0.0.17",
+  "version": "0.0.19",
   "license": "MIT",
   "repository": {
     "type": "git",
@@ -10,8 +10,8 @@
     "node": ">=20.0.0"
   },
   "dependencies": {
-    "@bananapus/core-v6": "^0.0.31",
-    "@bananapus/permission-ids-v6": "^0.0.15",
+    "@bananapus/core-v6": "^0.0.34",
+    "@bananapus/permission-ids-v6": "^0.0.17",
     "@openzeppelin/contracts": "^5.6.1"
   },
   "scripts": {

package/references/operations.md

@@ -0,0 +1,14 @@
+# Ownable Operations
+
+## Change Checklist
+
+- If you edit owner resolution, verify both direct ownership and project-owned cases.
+- If you edit permission handling, verify transfer-time reset behavior.
+- If an integration expects long-lived delegated access, confirm whether the transfer-reset rule invalidates that assumption.
+- If the change touches project ownership, check unminted-project and burn-lock regressions before assuming the happy-path tests are enough.
+
+## Common Failure Modes
+
+- Integrations assume delegated operators survive ownership transfer.
+- Bugs are blamed on this repo when the underlying project NFT ownership changed upstream.
+- A project-owned contract is treated like an address-owned contract and the wrong actor is allowed through `onlyOwner`.

package/references/runtime.md

@@ -0,0 +1,19 @@
+# Ownable Runtime
+
+## 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
+
+- 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: permission IDs reset on transfer, which is safer but easy to forget.
+
+## 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/regression/ZeroAddressValidation.t.sol`](../test/regression/ZeroAddressValidation.t.sol), and [`test/CodexUnmintedProjectHijack.t.sol`](../test/CodexUnmintedProjectHijack.t.sol) for the regressions most likely to matter in review.

package/src/JBOwnableOverrides.sol

@@ -45,6 +45,10 @@ abstract contract JBOwnableOverrides is Context, JBPermissioned, IJBOwnable {
     /// To restrict access to a specific address, pass that address as the `initialOwner` and `0` as the
     /// `initialProjectIdOwner`.
     /// @dev The owner can give owner access to other addresses through the `permissions` contract.
+    /// @dev If `initialProjectIdOwner` references a project ID that has not yet been minted, all ownership checks will
+    /// revert until that project is created, leaving the contract unusable. Deployers must ensure that the referenced
+    /// project is minted before or atomically with this contract's deployment — this is a deployment trust
+    /// assumption.
     /// @param permissions A contract storing permissions.
     /// @param projects Mints ERC-721s that represent project ownership and transfers.
     /// @param initialOwner The owner if the `initialProjectIdOwner` is 0 (until ownership is transferred).

package/src/structs/JBOwner.sol

@@ -7,7 +7,6 @@ pragma solidity ^0.8.0;
 /// `owner` address has owner access.
 /// @custom:member permissionId The permission ID which corresponds to owner access. See `JBPermissions` in `nana-core`
 /// and `nana-permission-ids`.
-// forge-lint: disable-next-line(pascal-case-struct)
 struct JBOwner {
     address owner;
     uint88 projectId;

package/test/CodexUnmintedProjectHijack.t.sol

@@ -0,0 +1,45 @@
+// SPDX-License-Identifier: UNLICENSED
+pragma solidity 0.8.28;
+
+import {Test} from "forge-std/Test.sol";
+
+import {MockOwnable} from "./mocks/MockOwnable.sol";
+
+import {JBPermissions} from "@bananapus/core-v6/src/JBPermissions.sol";
+import {JBProjects} from "@bananapus/core-v6/src/JBProjects.sol";
+import {IJBPermissions} from "@bananapus/core-v6/src/interfaces/IJBPermissions.sol";
+import {IJBProjects} from "@bananapus/core-v6/src/interfaces/IJBProjects.sol";
+
+contract CodexUnmintedProjectHijackTest is Test {
+    IJBProjects internal projects;
+    IJBPermissions internal permissions;
+
+    address internal deployer = makeAddr("deployer");
+    address internal attacker = makeAddr("attacker");
+    address internal intendedOwner = makeAddr("intendedOwner");
+
+    function setUp() public {
+        permissions = new JBPermissions(address(0));
+        projects = new JBProjects(address(this), address(0), address(0));
+    }
+
+    function test_unmintedProjectOwnerCanBeHijackedByFirstMinter() external {
+        vm.prank(deployer);
+        MockOwnable ownable = new MockOwnable(projects, permissions, address(0), 1);
+
+        assertEq(ownable.owner(), address(0), "owner should be unresolved before project 1 exists");
+
+        vm.prank(attacker);
+        uint256 hijackedProjectId = projects.createFor(attacker);
+
+        assertEq(hijackedProjectId, 1, "attacker should receive the configured project ID");
+        assertEq(ownable.owner(), attacker, "first minter becomes owner of the ownable contract");
+
+        vm.prank(attacker);
+        ownable.protectedMethod();
+
+        vm.prank(intendedOwner);
+        vm.expectRevert();
+        ownable.protectedMethod();
+    }
+}