@bananapus/address-registry-v6 0.0.17 → 0.0.19

package/ADMINISTRATION.md

@@ -1,74 +1,67 @@
 # Administration
 
-Admin privileges and their scope in nana-address-registry-v6.
-
 ## At A Glance
 
 | Item | Details |
-|------|---------|
-| Scope | Permissionless deployer registration and lookup only. There is no privileged admin surface. |
-| Operators | Anyone can register address/deployer relationships; clients decide which deployers they trust. |
-| Highest-risk actions | Relying on stale cached registry data or treating registry entries as trust endorsements instead of raw claims. |
-| Recovery posture | Registry entries can be overwritten but not deleted. Operational recovery is client-side: re-check entries, maintain trusted deployer lists, or migrate consumers to a new registry. |
-
-## Routine Operations
+| --- | --- |
+| Scope | Permissionless provenance registration for `CREATE` and `CREATE2` addresses |
+| Control posture | Fully permissionless and adminless |
+| Highest-risk actions | Incorrect first registration or bad derivation assumptions in offchain tooling |
+| Recovery posture | No in-place recovery; replacement contract is the only fix for logic mistakes |
 
-- Re-check `deployerOf()` at time of use instead of caching it indefinitely.
-- Pair registry lookups with a separate trusted-deployer allowlist in clients or indexing infrastructure.
-- Treat every registration as permissionless input, not proof that the caller was authorized by the deployer.
+## Purpose
 
-## One-Way Or High-Risk Actions
+`nana-address-registry-v6` has no admin surface. It is a permissionless first-write provenance registry.
 
-- There is no pause, owner override, or deletion path.
-- A later registration can overwrite an earlier mapping for the same computed address.
-- The registry does not verify that code is deployed at the registered address.
+## Control Model
 
-## Recovery Notes
-
-- If client trust assumptions change, fix the client or indexer. The contract itself cannot block or roll back bad registrations.
-- If the ecosystem needs different trust guarantees, the recovery path is a new registry design and client migration, not an admin action here.
+- no owner
+- no governance
+- no pause
+- no upgrade
+- registration is permissionless and correctness comes from deterministic address derivation
 
 ## Roles
 
-None. `JBAddressRegistry` has no owner, no admin, and no access control. The contract does not inherit from `Ownable`, `AccessControl`, or any permissioned pattern.
+| Role | How Assigned | Scope | Notes |
+| --- | --- | --- | --- |
+| Anyone | No assignment | Global | Can register an address if they provide correct `CREATE` or `CREATE2` inputs |
+
+## Privileged Surfaces
 
-## Privileged Functions
+There are no privileged functions. `registerAddress(...)` is permissionless for both registration paths.
 
-### JBAddressRegistry
+## Immutable And One-Way
 
-| Function | Required Role | Permission ID | Scope | What It Does |
-|----------|--------------|---------------|-------|--------------|
-| `registerAddress(address deployer, uint256 nonce)` | None | N/A | Global | Computes a `create` address from deployer + nonce and stores the deployer mapping |
-| `registerAddress(address deployer, bytes32 salt, bytes bytecode)` | None | N/A | Global | Computes a `create2` address from deployer + salt + bytecode and stores the deployer mapping |
-| `deployerOf(address)` | None | N/A | Global | View function — returns the registered deployer for a given address |
+- registration is first-write only
+- there is no overwrite or delete path for `deployerOf[address]`
 
-Every function is callable by any address. There are no restricted operations.
+## Operational Notes
 
-## Registration Model
+- treat registration as provenance, not endorsement
+- register addresses from trustworthy operational pipelines because bad first registration is sticky even though anyone can submit the correct derivation inputs
 
-- **Fully permissionless.** Any address can register any deployer/nonce or deployer/salt/bytecode combination.
-- **No caller verification.** The registry does not check whether `msg.sender` is the deployer. It only verifies that the computed address is valid by storing the mapping.
-- **Overwritable.** A second registration for the same computed address overwrites the previous deployer mapping. Last writer wins.
-- **Permanent storage, no removal.** There is no `unregister` or `removeAddress` function. Entries can be overwritten but never deleted.
-- **No approval or queue.** Registrations take effect immediately in the same transaction.
+## Machine Notes
 
-## Client-Side Trust
+- do not treat registration as a safety certification or allowlist signal
+- `src/JBAddressRegistry.sol` is the only control-relevant runtime file; there is no hidden owner path
+- if offchain derivation and onchain registration disagree, resolve the derivation logic rather than assuming overwrite is possible
 
-The registry stores deployer mappings without making trust judgments. All trust decisions are delegated to clients:
+## Recovery
 
-- **No on-chain filtering.** The contract does not distinguish "trusted" from "untrusted" deployers. Clients must maintain their own allowlist of known deployer addresses and cross-reference against `deployerOf()`.
-- **Event-based discovery.** The contract emits an `AddressRegistered(address indexed addr, address indexed deployer, address caller)` event on every registration. Clients can monitor this event to discover new registrations in real time.
-- **Overwrite risk.** Since registrations are overwritable, a client that caches `deployerOf(addr)` at time T may see a different result at time T+1 if someone re-registers the same address with a different deployer/nonce or deployer/salt/bytecode combination. Clients should re-check at time of use rather than caching indefinitely.
-- **No validation of deployment.** The registry computes the expected address from the inputs but does not verify that a contract actually exists at that address. A registration can be created for an address that has not yet been deployed (or will never be deployed).
+- there is no admin recovery surface
+- if derivation logic were ever wrong, the contract would need replacement rather than intervention
 
 ## Admin Boundaries
 
-There are no admins. Specifically:
+- nobody can curate allowlists, edit entries, or block registration
+- nobody can use this registry to certify code safety
 
-- **No pause mechanism.** The registry cannot be paused or frozen.
-- **No upgrade path.** The contract is not proxied or upgradeable.
-- **No fee extraction.** The contract holds no funds and collects no fees.
-- **No blocklist.** No address can be prevented from registering.
-- **No migration.** There is no way to transfer state to a new registry contract.
+## Source Map
 
-The only trust assumption is on the frontend side: clients must maintain their own list of trusted deployers and use `deployerOf()` to check whether a contract was deployed by one of them. The registry itself makes no trust judgments.
+- `src/JBAddressRegistry.sol`
+- `src/interfaces/IJBAddressRegistry.sol`
+- `script/Deploy.s.sol`
+- `script/helpers/AddressRegistryDeploymentLib.sol`
+- `test/JBAddressRegistry_Fork.t.sol`
+- `test/regression/NonceTruncation.t.sol`

package/ARCHITECTURE.md

@@ -2,47 +2,83 @@
 
 ## Purpose
 
-`nana-address-registry-v6` is a tiny trust-attestation primitive. It records who deployed a contract by recomputing the deployed address from CREATE or CREATE2 inputs and storing the verified deployer on-chain.
+`nana-address-registry-v6` is a small provenance primitive. It records which deployer could have created a contract address by recomputing `CREATE` or `CREATE2` inputs and storing the verified result on-chain.
 
-## Boundaries
+## System Overview
 
-- The repo does not assess contract safety.
-- It does not manage upgrades, ownership, or deployment permissions.
-- It only answers one question: "which deployer could have created this address?"
+The repo is intentionally small. `JBAddressRegistry` accepts deterministic deployment inputs, reconstructs the resulting address, and records the deployer if that address has not already been registered. It does not judge code safety, manage upgrades, or gate deployments.
 
-## Main Components
+## Core Invariants
 
-| Component | Responsibility |
-| --- | --- |
-| `JBAddressRegistry` | Verifies deterministic address derivation and stores `deployerOf[address]` |
-| `IJBAddressRegistry` | Minimal public interface for registration and lookup |
+- registration is permissionless because correctness comes from deterministic derivation, not caller authority
+- a contract address can only be registered once
+- registration must fail until runtime code actually exists at the derived address
+- `CREATE` and `CREATE2` derivation must match EVM rules exactly
 
-## Runtime Model
+## Modules
+
+| Module | Responsibility | Notes |
+| --- | --- | --- |
+| `JBAddressRegistry` | Address derivation and first-write provenance storage | Main contract |
+| `IJBAddressRegistry` | Minimal lookup and registration interface | External surface |
+
+## Trust Boundaries
+
+- the registry attests to deterministic provenance, not code quality
+- it does not manage ownership, upgrades, or allowlists
+- external systems may trust its recorded provenance, so derivation correctness is the whole product
+
+## Critical Flows
+
+### Register
 
 ```text
 caller
-  -> provides deployer plus CREATE nonce or CREATE2 salt+bytecode
+  -> supplies deployer plus CREATE nonce or CREATE2 salt and bytecode
   -> registry recomputes the target address
-  -> registry stores the deployer for that address if it was not already registered
+  -> registry records the deployer if the address was previously unregistered
 ```
 
-## Critical Invariants
-
-- Registration is permissionless because correctness comes from deterministic address derivation, not caller authority.
-- Re-registration must stay impossible.
-- CREATE and CREATE2 derivations must match EVM address derivation exactly; this repo is useless if the reconstruction is even slightly wrong.
-
-## Where Complexity Lives
+## Accounting Model
 
-- Almost all of the risk is concentrated in a tiny amount of derivation logic.
-- The repo is simple enough that overengineering is a bigger risk than underengineering.
+No economic accounting lives here. The only important state is `deployerOf[address]`.
 
-## Dependencies
+## Security Model
 
-- None that matter semantically beyond Solidity's address derivation rules
+- the risk is concentrated in a small amount of address-derivation logic
+- the registry records the derived deployer, not the transaction caller
+- overengineering is more dangerous than minimal, auditable derivation code
 
 ## Safe Change Guide
 
-- Treat derivation logic as cryptographic plumbing. Prefer no change over clever change.
-- If you touch nonce handling or bytecode hashing, add or retain tests for both CREATE and CREATE2 paths.
-- Do not turn this registry into a trust oracle. Keep the scope narrow.
+- treat derivation code like cryptographic plumbing
+- keep the undeployed-address check and first-write-only rule intact
+- if nonce handling or bytecode hashing changes, keep `CREATE` and `CREATE2` tests aligned
+- do not expand the repo into an allowlist or trust-oracle system
+
+## Canonical Checks
+
+- `CREATE` and `CREATE2` derivation correctness:
+  `test/JBAddressRegistry.t.sol`
+- edge-path validation and first-write behavior:
+  `test/JBAddressRegistryEdge.t.sol`
+- pre-registration, frontrun, and undeployed-code defenses:
+  `test/audit/CodexFrontRunRegistrationDoS.t.sol`
+- provenance abuse and zero-deployer edge cases:
+  `test/audit/CodexUnauthorizedRegistrar.t.sol`
+  `test/audit/ZeroDeployerRegistration.t.sol`
+
+## Source Map
+
+- `src/JBAddressRegistry.sol`
+- `src/interfaces/IJBAddressRegistry.sol`
+- `test/JBAddressRegistry.t.sol`
+- `test/JBAddressRegistryEdge.t.sol`
+- `test/audit/CodexFrontRunRegistrationDoS.t.sol`
+- `test/audit/CodexUnauthorizedRegistrar.t.sol`
+- `test/audit/ZeroDeployerRegistration.t.sol`
+- `test/regression/NonceTruncation.t.sol`
+- `script/Deploy.s.sol`
+- `script/helpers/AddressRegistryDeploymentLib.sol`
+- `references/runtime.md`
+- `references/operations.md`

package/AUDIT_INSTRUCTIONS.md

@@ -1,52 +1,67 @@
 # Audit Instructions
 
-This repo is a small registry, but it participates in deployer verification across the ecosystem. Treat incorrect registration as a security boundary failure.
+This repo is a small registry, but it sits on a deployer-verification boundary across the ecosystem. Treat incorrect registration as a security failure.
 
-## Objective
+## Audit Objective
 
 Find issues that:
+
 - let callers register contracts under the wrong deployer
 - break determinism or uniqueness assumptions around registration
 - let a malicious deployer spoof provenance for contracts it did not create
-- create stale or truncation-related collisions in recorded mappings
+- create truncation-related collisions or stale mapping assumptions
 
 ## Scope
 
 In scope:
+
 - `src/JBAddressRegistry.sol`
 - `src/interfaces/IJBAddressRegistry.sol`
-- deployment scripts in `script/`
+- all deployment helpers in `script/`
+
+## Start Here
 
-## System Model
+1. `src/JBAddressRegistry.sol`
+2. `script/Deploy.s.sol`
+
+## Security Model
 
 The registry maps deployed addresses to the deployer that created them. Downstream repos use it to:
+
 - validate provenance for clones or deterministically deployed instances
 - discover whether a contract came from an approved deployer path
 
-## Critical Invariants
+## Roles And Privileges
+
+| Role | Powers | How constrained |
+|------|--------|-----------------|
+| Deployer | Register contracts as its outputs | Must prove authentic deployment provenance |
+| Registry reader | Trust provenance for privileged decisions | Must not observe spoofable or mutable history |
 
-1. Provenance cannot be forged
-Only the actual deployer path the registry intends to trust may create a successful registration for a contract.
+## Integration Assumptions
 
-2. One contract maps to one authoritative deployer record
-No aliasing or overwrite path should let a later caller replace provenance unexpectedly.
+| Dependency | Assumption | What breaks if wrong |
+|------------|------------|----------------------|
+| Approved deployers | Produce the addresses they claim | Downstream provenance gates become meaningless |
 
-3. Registration metadata is stable
-Nonce, salt, or address truncation must not allow collisions or stale reads.
+## Critical Invariants
 
-## Threat Model
+1. Provenance cannot be forged.  
+   Only the actual deployer path the registry intends to trust may create a successful registration for a contract.
+2. One contract maps to one authoritative deployer record.  
+   No aliasing or overwrite path should let a later caller replace provenance unexpectedly.
+3. Registration metadata is stable.  
+   Nonce, salt, or address truncation must not allow collisions or stale reads.
 
-Prioritize:
+## Attack Surfaces
+
+- registration entrypoints that rely on deployer provenance
+- overwrite and replay paths
+- deterministic deployment assumptions
 - zero-address or malformed registration attempts
-- deterministic deployment edge cases
-- overwrite or replay behavior
-- any assumption that `msg.sender` is sufficient proof without deployment linkage
 
-## Build And Verification
+## Verification
 
-Standard workflow:
 - `npm install`
 - `forge build`
 - `forge test`
-
-Tests already focus on zero deployers and nonce-truncation regressions. A meaningful finding here should show downstream trust in the registry becoming misplaced, not just a cosmetic mismatch.

package/README.md

@@ -1,17 +1,22 @@
 # Juicebox Address Registry
 
-`@bananapus/address-registry-v6` is a permissionless registry that records which deployer created a contract. It is meant to make deployer provenance visible on-chain, especially for hooks and helper contracts that users may need to trust before interacting with them.
+`@bananapus/address-registry-v6` is a permissionless registry that records deployer provenance for contracts when callers provide matching `create` or `create2` deployment inputs. It is meant to make deployer provenance visible on-chain, especially for hooks and helper contracts that users may need to trust before interacting with them.
 
-Architecture: [ARCHITECTURE.md](./ARCHITECTURE.md)
+Architecture: [ARCHITECTURE.md](./ARCHITECTURE.md)  
+User journeys: [USER_JOURNEYS.md](./USER_JOURNEYS.md)  
+Skills: [SKILLS.md](./SKILLS.md)  
+Risks: [RISKS.md](./RISKS.md)  
+Administration: [ADMINISTRATION.md](./ADMINISTRATION.md)  
+Audit instructions: [AUDIT_INSTRUCTIONS.md](./AUDIT_INSTRUCTIONS.md)
 
 ## Overview
 
-The registry supports both `create` and `create2` style deployments:
+The registry supports both `create` and `create2` deployments:
 
 - for `create`, it reconstructs the deployed address from the deployer and nonce
 - for `create2`, it reconstructs the deployed address from the deployer, salt, and deployment bytecode
 
-Because the address is computed deterministically, registrations do not require access control. Anyone can submit the correct deployment inputs, and the registry records the verified deployer for the computed address.
+Because the address is computed deterministically, registrations do not need access control. Anyone can submit the correct deployment inputs, and the registry records the deployer for the computed address after confirming code already exists there.
 
 Use this repo when deployer provenance matters. Do not confuse it with an allowlist, audit registry, or trust oracle.
 
@@ -31,7 +36,31 @@ The registry is intentionally narrow:
 2. bind that address to a deployer once
 3. expose the result for other systems and clients
 
-Anything beyond that is out of scope by design.
+Anything beyond that is out of scope.
+
+## Read These Files First
+
+1. `src/JBAddressRegistry.sol`
+2. `test/JBAddressRegistry.t.sol`
+3. `test/JBAddressRegistryEdge.t.sol`
+4. `test/audit/CodexFrontRunRegistrationDoS.t.sol`
+
+## Integration Traps
+
+- provenance is only useful if callers also know what the deployer is trusted for
+- permissionless registration is intentional, so integrations should verify the computed inputs rather than assume caller authority
+- `create` nonce reconstruction and `create2` salt-bytecode reconstruction are different trust paths and should be reasoned about separately
+
+## Where State Lives
+
+- deployer provenance: `JBAddressRegistry`
+- deployment truth: the target chain history and bytecode inputs outside this repo
+
+## High-Signal Tests
+
+1. `test/JBAddressRegistry.t.sol`
+2. `test/JBAddressRegistryEdge.t.sol`
+3. `test/audit/CodexUnauthorizedRegistrar.t.sol`
 
 ## Install
 
@@ -72,6 +101,11 @@ script/
 
 ## Risks And Notes
 
-- provenance is not the same thing as safety; a known deployer can still deploy unsafe code
-- registrations are first-write only, so bad operational processes around initial registration can be sticky
-- the `create` address path relies on nonce reconstruction and intentionally rejects unrealistic nonce ranges
+- provenance is not the same as safety; a known deployer can still deploy unsafe code
+- registrations are first-write only, so bad initial registration is sticky
+- the `create` path relies on nonce reconstruction and intentionally rejects unrealistic nonce ranges
+
+## For AI Agents
+
+- Describe this repo as a provenance registry, not as an allowlist or safety oracle.
+- Read the edge and audit tests before making claims about frontrunning or unauthorized registration.

package/RISKS.md

@@ -1,42 +1,58 @@
 # Juicebox Address Registry Risk Register
 
-This file focuses on the registry's core promise: recording claimed deployer linkage for deterministically derived contracts. The main risks are misuse, incorrect assumptions about what registration means, and collisions between social trust and on-chain truth.
+This file covers what `JBAddressRegistry` actually proves: deterministic address provenance claims. The main risk is not funds loss inside the registry. It is consumers reading too much into a registration entry.
 
-## How to use this file
+## How To Use This File
 
-- Read `Priority risks` first; the biggest risks here are almost all interpretive, not balance-sheet failures.
-- Use the detailed sections to distinguish what the registry proves from what users may incorrectly infer from it.
-- Treat `Invariants to Verify` as the minimal safety envelope for deterministic registration.
+- Read `Priority risks` first. Most failures here are interpretation and integration failures.
+- Distinguish "address can be derived from these inputs" from "this deployment is trusted."
+- Treat `Invariants to verify` as the narrow correctness envelope of the registry itself.
 
-## Priority risks
+## Priority Risks
 
 | Priority | Risk | Why it matters | Primary controls |
 |----------|------|----------------|------------------|
-| P1 | Over-trusting registration as approval | The registry proves deployer linkage, not code safety or ecosystem endorsement. Users can still trust malicious deployments. | Clear docs, UI labeling, and strict separation between proof of origin and proof of safety. |
-| P1 | Incorrect deployment-parameter assumptions | Deterministic verification is only as good as the deployment parameters supplied. Wrong assumptions create false negatives or confusing operator workflows. | Strong test coverage around CREATE and CREATE2 derivation and explicit documentation. |
-| P2 | Registry completeness assumptions | Useful contracts may remain unregistered; absence from the registry is not proof of absence or malice. | Operational guidance for clients and integrators to treat registration as additive evidence only. |
-
+| P1 | Over-trusting registration as safety approval | A registered deployer mapping does not mean the contract is audited, canonical, or safe. | UIs should label registration as provenance evidence only. |
+| P1 | First-writer capture of a valid provenance claim | The registry records the first valid claim for an address and never updates it. | Operational discipline for trusted deployers and curated allowlists for consumers. |
+| P2 | Completeness assumptions | Unregistered contracts can still be legitimate; absence from the registry is not proof of malice. | Treat registry data as additive metadata, not an allowlist. |
 
 ## 1. Trust Assumptions
 
-- **Self-registration.** Anyone can register any address. The registry does NOT verify that the caller actually deployed the contract. It only verifies that the computed address matches the provided deployer/nonce or deployer/salt/bytecode parameters.
-- **Frontend trust.** Frontends must maintain their own list of trusted deployers. The registry provides the mapping, not a trust judgment.
+- **Deterministic address formulas are correct.** The contract trusts its `CREATE` and `CREATE2` derivation logic to match EVM semantics.
+- **Consumers define trust externally.** The registry does not decide which deployers are trusted.
 
 ## 2. Known Risks
 
-- **False registration.** Anyone can call `registerAddress` with arbitrary deployer/nonce values, registering a computed address with a deployer that did not actually deploy it. Consumers must verify the deployer is trusted, not just that a mapping exists.
-- **No removal mechanism.** Once registered, an entry cannot be removed. Re-registration of the same address reverts with `JBAddressRegistry_AlreadyRegistered`.
-- **CREATE2 vs CREATE1 trust model.** CREATE1 registrations (`registerAddress(deployer, nonce)`) can be spoofed: anyone who knows the deployer address and nonce can register the computed address without being the deployer. CREATE2 registrations (`registerAddress(deployer, salt, bytecode)`) have the same trust model — knowing the parameters is sufficient to register. The function accepts raw deployment bytecode and hashes it internally (`keccak256(bytecode)`) for the CREATE2 address computation. In both cases, the registry only proves "this address COULD have been deployed by this deployer with these parameters", not "this deployer DID deploy this address". Consumers must verify the deployer is trusted independently.
-- **Frontend trust example.** A malicious actor could register `deployerOf[uniswapRouter] = attackerDeployer` if they find a `(deployer, nonce)` or `(deployer, salt, bytecode)` combination that computes to the Uniswap router address and register it before the legitimate deployer does. Only the first registration is accepted; subsequent attempts revert with `JBAddressRegistry_AlreadyRegistered`. Frontends that display "deployed by X" based on `deployerOf` should cross-reference against a curated allowlist of trusted deployers.
+- **Caller identity is irrelevant.** Anyone may call `registerAddress(...)`. The registry proves that an address matches supplied deployment parameters, not that the caller was the deployer.
+- **First registration wins.** Once `deployerOf[addr]` is set, later registrations revert.
+- **No pre-registration of future deployments.** `registerAddress(...)` requires code to already exist at the computed address.
+- **No removal or correction path.** The registry is intentionally append-only per address.
+- **Registration is provenance, not endorsement.** `deployerOf[hook] = someFactory` says nothing about code safety, upgradeability, audit status, or whether the deployer itself is trustworthy.
+- **Operational lag matters.** If a trusted deployer forgets to register immediately, someone else can publish the first valid claim for that address.
+
+## 3. Integration Risks
+
+- **Frontends should pair registry data with a trusted-deployer set.** Displaying `deployerOf` alone can mislead users into treating any registered provenance as official.
+- **`CREATE` and `CREATE2` claims are parameter-based.** In either mode, the right mental model is "the address is compatible with these inputs," not "the registry witnessed deployment."
+- **Off-chain explorers should preserve uncertainty.** "Registered deployer claim" is a safer label than "deployed by" unless the explorer also verified chain history.
+
+## 4. Invariants To Verify
+
+- `deployerOf[addr]` is set at most once
+- `CREATE` registrations only succeed for addresses derivable from the provided `(deployer, nonce)`
+- `CREATE2` registrations only succeed for addresses derivable from the provided `(deployer, salt, bytecode)`
+- `_addressFrom` remains correct for the supported nonce range and reverts outside that range
+
+## 5. Accepted Behaviors
+
+### 5.1 The registry does not authenticate the registrant
 
-## 3. Invariants to Verify
+This is intentional. `JBAddressRegistry` is a deterministic provenance registry, not a permissioned attestation service.
 
-- `deployerOf[addr]` always corresponds to a valid deployer/nonce pair that produces `addr` (if registered via `registerAddress`).
-- `create2` registrations: `deployerOf[addr]` corresponds to a valid deployer/salt/bytecode combination whose `keccak256(bytecode)` produces `addr` via the CREATE2 formula.
-- Registration idempotency: `deployerOf[addr]` reflects the first and only registration. Subsequent attempts to register the same address revert with `JBAddressRegistry_AlreadyRegistered`.
+### 5.2 Unregistered does not mean unsafe
 
-## 4. Accepted Behaviors
+The registry is useful metadata, but it does not cover every legitimate deployment. Consumers should not infer that an unregistered address is malicious just because no entry exists.
 
-### 4.1 RLP encoding correctness is well-tested and bounded
+### 5.3 The registry is retrospective, not a reservation layer
 
-The `_addressFrom` function manually implements RLP encoding for nonces up to uint64. The nonce is capped at uint64 max with an explicit revert, and the encoding logic is a well-tested pattern. This is not an open risk.
+This is intentional. A deterministic address can only be registered after code already exists there. Consumers should not expect `JBAddressRegistry` to signal future deployment intent or protect an undeployed `CREATE2` address from later first-writer capture.

package/SKILLS.md

@@ -3,7 +3,7 @@
 ## Use This File For
 
 - Use this file when the task involves deployer provenance, `create` or `create2` registration logic, or determining what the registry does and does not prove.
-- Start here, then open the registry contract or tests that match the registration mode under review.
+- Start here, then decide whether the issue is `create` address derivation, `create2` derivation, or misuse of provenance as a trust signal.
 
 ## Read This Next
 
@@ -11,8 +11,9 @@
 |---|---|
 | Repo overview and intended guarantees | [`README.md`](./README.md), [`ARCHITECTURE.md`](./ARCHITECTURE.md) |
 | Registry implementation | [`src/JBAddressRegistry.sol`](./src/JBAddressRegistry.sol) |
+| Runtime and operational assumptions | [`references/runtime.md`](./references/runtime.md), [`references/operations.md`](./references/operations.md) |
 | Interfaces and deployment | [`src/interfaces/`](./src/interfaces/), [`script/Deploy.s.sol`](./script/Deploy.s.sol) |
-| Edge, fork, or regression coverage | [`test/JBAddressRegistry.t.sol`](./test/JBAddressRegistry.t.sol), [`test/JBAddressRegistryEdge.t.sol`](./test/JBAddressRegistryEdge.t.sol), [`test/regression/`](./test/regression/) |
+| Edge and fork coverage | [`test/JBAddressRegistry.t.sol`](./test/JBAddressRegistry.t.sol), [`test/JBAddressRegistryEdge.t.sol`](./test/JBAddressRegistryEdge.t.sol), [`test/JBAddressRegistry_Fork.t.sol`](./test/JBAddressRegistry_Fork.t.sol) |
 
 ## Repo Map
 
@@ -30,10 +31,11 @@ Permissionless on-chain provenance registry that records which deployer created
 ## Reference Files
 
 - Open [`references/runtime.md`](./references/runtime.md) when you need the core guarantees, first-write semantics, or the difference between provenance and trust.
-- Open [`references/operations.md`](./references/operations.md) when you need deployment breadcrumbs, test pointers, or the common stale assumptions around what the registry can verify.
+- Open [`references/operations.md`](./references/operations.md) when you need deployment breadcrumbs, test pointers, or common stale assumptions about what the registry can verify.
 
 ## Working Rules
 
 - Start in [`src/JBAddressRegistry.sol`](./src/JBAddressRegistry.sol). This repo is intentionally small, so most questions should collapse quickly to the core contract.
 - Treat provenance and safety as separate questions. The registry only proves who deployed something.
+- Registration is first-write only and requires code to already exist at the computed address.
 - When a task involves wrong or missing registry data, verify the registration inputs before assuming a contract bug.

package/USER_JOURNEYS.md

@@ -1,43 +1,90 @@
 # User Journeys
 
-## Who This Repo Serves
+## Repo Purpose
 
-- deployers that want on-chain provenance for helper contracts and hooks
-- integrators checking who deployed an existing address
-- auditors verifying deterministic deployment claims
+This repo records deployer provenance for contracts whose address can be reconstructed from `create` or `create2` inputs. It does not say whether a deployment is safe, canonical, or approved. It only says who deployed it when the inputs are correct and someone registered them.
+
+## Primary Actors
+
+- deployers who want onchain provenance for hooks, clones, and helper contracts
+- integrators who need to verify who deployed an address before trusting it
+- auditors who want a deterministic provenance check instead of offchain screenshots
+
+## Key Surfaces
+
+- `JBAddressRegistry`: stores `deployerOf[address]` after reconstructing the target address from deployment inputs
+- `registerAddress(deployer, nonce)` and `registerAddress(deployer, salt, bytecode)`: the two provenance-registration paths
 
 ## Journey 1: Register A `CREATE` Deployment
 
-**Starting state:** you know the deploying address and nonce for a contract already created with `create`.
+**Actor:** deployer, operator, or auditor with the original deployment inputs.
+
+**Intent:** bind an already-deployed `create` address to the account that deployed it.
+
+**Preconditions**
+- the contract was deployed with `create`
+- the caller knows the deployer address and nonce used for the deployment
+- the address has not already been registered
 
-**Success:** the registry stores the verified deployer for the computed contract address.
+**Main Flow**
+1. Call `registerAddress(deployer, nonce)`.
+2. `JBAddressRegistry` reconstructs the deployed address from the deployer and nonce.
+3. If the computed address is valid and unused, the registry stores `deployerOf[address] = deployer`.
 
-**Flow**
-1. Call the `registerAddress` overload for `create` deployments with the deployer and nonce.
-2. `JBAddressRegistry` reconstructs the expected deployed address.
-3. If the reconstruction matches a real address and no one registered it before, the registry stores `deployerOf[address]`.
+**Failure Modes**
+- the nonce does not match the real deployment
+- the computed address has already been registered
+- the nonce exceeds the supported `uint64` range and registration reverts
+- the deployment assumptions are wrong and the reconstructed address is useless
 
 ## Journey 2: Register A `CREATE2` Deployment
 
-**Starting state:** you know the deployer, salt, and init code for a deterministic deployment.
+**Actor:** deployer, operator, or auditor with the original deterministic deployment inputs.
 
-**Success:** the registry records the verified deployer for the deterministic address without any privileged access.
+**Intent:** bind a `create2` deployment to its deployer without privileged access.
 
-**Flow**
-1. Call the `registerAddress` overload for `create2`.
-2. The registry hashes deployer, salt, and deployment bytecode to reconstruct the deterministic address.
-3. It stores the deployer for that address if the registration is valid and unused.
+**Preconditions**
+- the contract was deployed with `create2`
+- the caller knows the deployer, salt, and init code
+- the address has not already been registered
+
+**Main Flow**
+1. Call `registerAddress(deployer, salt, bytecode)`.
+2. The registry reconstructs the deterministic address from the standard `create2` formula.
+3. If the address is valid and unused, the registry records the deployer.
+
+**Failure Modes**
+- the bytecode or salt is wrong
+- the address was registered already
+- a third party publishes the first valid provenance claim before the expected deployer registers it
+- operators assume registration proves a contract exists there right now
+- consumers misread provenance as an allowlist or audit stamp
 
 ## Journey 3: Resolve Provenance For An Existing Address
 
-**Starting state:** an integration or auditor sees a contract address and wants to know who deployed it.
+**Actor:** integrator, frontend, or auditor.
+
+**Intent:** answer "who deployed this?" before trusting a hook, helper, or clone.
+
+**Preconditions**
+- the address was registered previously
+- the caller understands that an empty result means "unknown" rather than "unsafe"
+
+**Main Flow**
+1. Query `deployerOf[address]`.
+2. If a deployer is present, use it as provenance evidence for who originated the deployment.
+3. If no deployer is present, treat the address as unregistered and keep investigating elsewhere.
+4. Pair the result with an external trust list, transaction history, or audit context before relying on the contract.
+
+**Postconditions**
+- downstream reviewers know which deployer or factory to inspect next
+- the trust decision still happens outside this repo
 
-**Success:** the caller can query `deployerOf[address]` and get provenance if someone registered it correctly.
+## Trust Boundaries
 
-**Flow**
-1. Look up the address in the registry.
-2. If a deployer is present, use that as provenance evidence for who originated the deployment.
-3. Treat absence as "not registered," not as a trust verdict on the code.
+- this repo only proves registered deployer provenance from deterministic inputs
+- anyone can submit a valid claim, so the mapping authenticates deployment inputs rather than caller identity
+- it does not prove code quality, audit status, or governance approval
 
 ## Hand-Offs
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bananapus/address-registry-v6",
-  "version": "0.0.17",
+  "version": "0.0.19",
   "license": "MIT",
   "repository": {
     "type": "git",

package/references/operations.md

@@ -5,8 +5,10 @@
 - If you edit `create` reconstruction logic, verify nonce-boundary behavior.
 - If you edit `create2` behavior, verify bytecode hashing and salt assumptions.
 - If a user asks whether a contract is "safe," redirect the question to code provenance plus code review, not the registry alone.
+- If you change registration guards, re-read the audit tests before trusting a narrower unit proof.
 
 ## Common Failure Modes
 
 - Operators confuse deployer provenance with trustworthiness.
 - Registration is attempted with stale deployment inputs from another repo or environment.
+- The wrong party is allowed to bind or front-run a computed address because the first-write assumption was weakened.

package/references/runtime.md

@@ -15,3 +15,5 @@
 - [`test/JBAddressRegistry.t.sol`](../test/JBAddressRegistry.t.sol) for baseline behavior.
 - [`test/JBAddressRegistryEdge.t.sol`](../test/JBAddressRegistryEdge.t.sol) for boundary conditions.
 - [`test/JBAddressRegistry_Fork.t.sol`](../test/JBAddressRegistry_Fork.t.sol) for live assumptions.
+- [`test/regression/NonceTruncation.t.sol`](../test/regression/NonceTruncation.t.sol) for nonce-width and reconstruction regressions.
+- [`test/audit/ZeroDeployerRegistration.t.sol`](../test/audit/ZeroDeployerRegistration.t.sol), [`test/audit/CodexUnauthorizedRegistrar.t.sol`](../test/audit/CodexUnauthorizedRegistrar.t.sol), and [`test/audit/CodexFrontRunRegistrationDoS.t.sol`](../test/audit/CodexFrontRunRegistrationDoS.t.sol) for the abuse cases this repo is expected to resist.