@agenticprimitives/contracts 0.1.0-alpha.2 → 1.0.0-alpha.10

package/src/mocks/MockUSDC.sol

@@ -0,0 +1,152 @@
+// SPDX-License-Identifier: MIT
+pragma solidity ^0.8.28;
+
+import "@openzeppelin/contracts/token/ERC20/ERC20.sol";
+import "@openzeppelin/contracts/utils/cryptography/ECDSA.sol";
+
+/**
+ * @title MockUSDC
+ * @notice Test USDC for the Base Sepolia x402 demos (spec 272, PAY-CON-3). 6 decimals, open mint +
+ *         faucet, and full EIP-3009 (`transferWithAuthorization` / `receiveWithAuthorization` /
+ *         `cancelAuthorization` / `authorizationState`) so the Wave-5 Coinbase-x402 interop adapter
+ *         is a no-redeploy add (X402-D2 / PAY-WIRE-4).
+ *
+ * @dev    DEV-ONLY: `mint`/`faucet` are open. NEVER a production asset. Wave-1 settlement is
+ *         delegation-native (the {PaymentEnforcer}-gated `transfer`), so EIP-3009 is present but
+ *         unused until Wave 5; shipping it now avoids a token redeploy.
+ */
+contract MockUSDC is ERC20 {
+    using ECDSA for bytes32;
+
+    // EIP-3009 type hashes
+    bytes32 public constant TRANSFER_WITH_AUTHORIZATION_TYPEHASH = keccak256(
+        "TransferWithAuthorization(address from,address to,uint256 value,uint256 validAfter,uint256 validBefore,bytes32 nonce)"
+    );
+    bytes32 public constant RECEIVE_WITH_AUTHORIZATION_TYPEHASH = keccak256(
+        "ReceiveWithAuthorization(address from,address to,uint256 value,uint256 validAfter,uint256 validBefore,bytes32 nonce)"
+    );
+    bytes32 public constant CANCEL_AUTHORIZATION_TYPEHASH =
+        keccak256("CancelAuthorization(address authorizer,bytes32 nonce)");
+
+    bytes32 private immutable _CACHED_DOMAIN_SEPARATOR;
+    uint256 private immutable _CACHED_CHAIN_ID;
+
+    /// @notice EIP-3009: authorizer => nonce => used-or-canceled.
+    mapping(address => mapping(bytes32 => bool)) public authorizationState;
+
+    event AuthorizationUsed(address indexed authorizer, bytes32 indexed nonce);
+    event AuthorizationCanceled(address indexed authorizer, bytes32 indexed nonce);
+
+    error AuthNotYetValid();
+    error AuthExpired();
+    error AuthUsedOrCanceled();
+    error InvalidSignature();
+    error CallerMustBePayee();
+
+    constructor() ERC20("Mock USD Coin", "USDC") {
+        _CACHED_CHAIN_ID = block.chainid;
+        _CACHED_DOMAIN_SEPARATOR = _computeDomainSeparator();
+    }
+
+    function decimals() public pure override returns (uint8) {
+        return 6;
+    }
+
+    // ── dev faucet ──
+    function mint(address to, uint256 amount) external {
+        _mint(to, amount);
+    }
+
+    function faucet(uint256 amount) external {
+        _mint(msg.sender, amount);
+    }
+
+    // ── EIP-3009 ──
+
+    function DOMAIN_SEPARATOR() public view returns (bytes32) {
+        return block.chainid == _CACHED_CHAIN_ID ? _CACHED_DOMAIN_SEPARATOR : _computeDomainSeparator();
+    }
+
+    function transferWithAuthorization(
+        address from,
+        address to,
+        uint256 value,
+        uint256 validAfter,
+        uint256 validBefore,
+        bytes32 nonce,
+        bytes calldata signature
+    ) external {
+        _requireValidAuthorization(from, nonce, validAfter, validBefore);
+        _verify(
+            from,
+            keccak256(
+                abi.encode(TRANSFER_WITH_AUTHORIZATION_TYPEHASH, from, to, value, validAfter, validBefore, nonce)
+            ),
+            signature
+        );
+        _markAuthorizationUsed(from, nonce);
+        _transfer(from, to, value);
+    }
+
+    function receiveWithAuthorization(
+        address from,
+        address to,
+        uint256 value,
+        uint256 validAfter,
+        uint256 validBefore,
+        bytes32 nonce,
+        bytes calldata signature
+    ) external {
+        if (to != msg.sender) revert CallerMustBePayee();
+        _requireValidAuthorization(from, nonce, validAfter, validBefore);
+        _verify(
+            from,
+            keccak256(
+                abi.encode(RECEIVE_WITH_AUTHORIZATION_TYPEHASH, from, to, value, validAfter, validBefore, nonce)
+            ),
+            signature
+        );
+        _markAuthorizationUsed(from, nonce);
+        _transfer(from, to, value);
+    }
+
+    function cancelAuthorization(address authorizer, bytes32 nonce, bytes calldata signature) external {
+        if (authorizationState[authorizer][nonce]) revert AuthUsedOrCanceled();
+        _verify(authorizer, keccak256(abi.encode(CANCEL_AUTHORIZATION_TYPEHASH, authorizer, nonce)), signature);
+        authorizationState[authorizer][nonce] = true;
+        emit AuthorizationCanceled(authorizer, nonce);
+    }
+
+    // ── internals ──
+
+    function _requireValidAuthorization(address from, bytes32 nonce, uint256 validAfter, uint256 validBefore)
+        private
+        view
+    {
+        if (block.timestamp <= validAfter) revert AuthNotYetValid();
+        if (block.timestamp >= validBefore) revert AuthExpired();
+        if (authorizationState[from][nonce]) revert AuthUsedOrCanceled();
+    }
+
+    function _markAuthorizationUsed(address from, bytes32 nonce) private {
+        authorizationState[from][nonce] = true;
+        emit AuthorizationUsed(from, nonce);
+    }
+
+    function _verify(address signer, bytes32 structHash, bytes calldata signature) private view {
+        bytes32 digest = keccak256(abi.encodePacked("\x19\x01", DOMAIN_SEPARATOR(), structHash));
+        if (digest.recover(signature) != signer) revert InvalidSignature();
+    }
+
+    function _computeDomainSeparator() private view returns (bytes32) {
+        return keccak256(
+            abi.encode(
+                keccak256("EIP712Domain(string name,string version,uint256 chainId,address verifyingContract)"),
+                keccak256(bytes("Mock USD Coin")),
+                keccak256(bytes("2")),
+                block.chainid,
+                address(this)
+            )
+        );
+    }
+}

package/src/naming/AgentNameRegistry.sol

@@ -1,11 +1,13 @@
 // SPDX-License-Identifier: MIT
 pragma solidity ^0.8.28;
 
+import "../governance/GovernanceManaged.sol";
+
 /**
  * @title AgentNameRegistry
  * @notice Hierarchical multi-root name registry for Smart Agents.
  *
- * Names are keyed by `node` (the ENS-style namehash:
+ * Names are keyed by `node` (the recursive namehash:
  * `keccak256(parentNode || labelhash)`). Each node has an owner (a Smart
  * Agent address), a resolver, an optional subregistry delegate that may
  * issue children, a parent pointer, the labelhash, and an optional
@@ -36,7 +38,11 @@ pragma solidity ^0.8.28;
  * discipline (a primary name only counts when the forward record
  * agrees).
  */
-contract AgentNameRegistry {
+/// @dev R6.8 — inherits `GovernanceManaged` to gain the
+///      `whenNotPaused` modifier on its mutating surface. The registry
+///      still owns its own per-node auth (`_requireParentAuth` /
+///      `msg.sender == owner`); governance only owns the pause flag.
+contract AgentNameRegistry is GovernanceManaged {
     // ─── H7-C.4 / CON-NAMING-001 — root-initializer gate ───────────────
     //
     // `initializeRoot` was permissionless: any mempool observer could
@@ -71,6 +77,12 @@ contract AgentNameRegistry {
     error NameExpired();
     error RootAlreadyInitialized();
     error EmptyLabel();
+    /// @notice AN-1-ONCHAIN (audit 2026-06-10) — the label is not in canonical form. The off-chain
+    ///         SDK `normalizeLabel` (NFC + lowercase + `[a-z0-9-]`, 1..63, no leading/trailing `-`) was
+    ///         bypassable by any DIRECT contract caller, allowing homoglyph / mixed-case / zero-width /
+    ///         embedded-dot squatting of names. The charset is now enforced ON CHAIN; because a valid
+    ///         label is already lowercase ASCII, raw-byte hashing equals hashing the normalized label.
+    error InvalidLabel();
     error ZeroOwner();
     /// @notice H7-C.4 / CON-NAMING-001 — `initializeRoot` may only be called
     ///         by the immutable `initializer` set at construction. Closes the
@@ -129,10 +141,13 @@ contract AgentNameRegistry {
 
     // ─── Constructor (H7-C.4) ───────────────────────────────────────
 
-    /// @notice Set the immutable root-initializer. The deploy script
-    ///         deploys the registry + calls `initializeRoot` in the same
-    ///         transaction so the TLD can't be frontrun.
-    constructor(address initializer_) {
+    /// @notice Set the immutable root-initializer + governance pointer.
+    ///         The deploy script deploys the registry + calls
+    ///         `initializeRoot` in the same transaction so the TLD
+    ///         can't be frontrun. R6.8 added `governance_` so the
+    ///         registry can read the system pause flag through
+    ///         `GovernanceManaged._pausedSafe()`.
+    constructor(address initializer_, address governance_) GovernanceManaged(governance_) {
         if (initializer_ == address(0)) revert ZeroOwner();
         initializer = initializer_;
     }
@@ -151,6 +166,25 @@ contract AgentNameRegistry {
         return keccak256(abi.encodePacked(bytes32(0), keccak256(bytes("agent"))));
     }
 
+    /// @notice AN-1-ONCHAIN — enforce the canonical single-label charset on chain. Mirrors the SDK
+    ///         `normalizeLabel`: a single label of 1..63 bytes drawn from `[a-z0-9-]`, with no leading
+    ///         or trailing `-`. Reverts `EmptyLabel` / `InvalidLabel`. Reusable from `register` +
+    ///         `initializeRoot` so NO write path can anchor a non-canonical (squattable) label.
+    function _validateLabel(bytes memory b) internal pure {
+        uint256 len = b.length;
+        if (len == 0) revert EmptyLabel();
+        if (len > 63) revert InvalidLabel();
+        // no leading / trailing hyphen (0x2d)
+        if (b[0] == 0x2d || b[len - 1] == 0x2d) revert InvalidLabel();
+        for (uint256 i = 0; i < len; i++) {
+            uint8 c = uint8(b[i]);
+            bool ok = (c >= 0x61 && c <= 0x7a) // a-z
+                || (c >= 0x30 && c <= 0x39) // 0-9
+                || c == 0x2d; // -
+            if (!ok) revert InvalidLabel();
+        }
+    }
+
     // ─── Root Initialization (multi-root) ───────────────────────────
 
     /**
@@ -170,7 +204,7 @@ contract AgentNameRegistry {
         // TLD. The deploy script bundles deploy+init in one transaction so no
         // frontrun window exists.
         if (msg.sender != initializer) revert NotInitializer(msg.sender, initializer);
-        if (bytes(label).length == 0) revert EmptyLabel();
+        _validateLabel(bytes(label)); // AN-1-ONCHAIN: canonical charset on chain
         if (rootOwner == address(0)) revert ZeroOwner();
         rootNode = namehashRoot(label);
         if (_records[rootNode].registeredAt != 0) revert RootAlreadyInitialized();
@@ -219,8 +253,8 @@ contract AgentNameRegistry {
         address newOwner,
         address resolverContract,
         uint64 expiry
-    ) external returns (bytes32 childNode) {
-        if (bytes(label).length == 0) revert EmptyLabel();
+    ) external whenNotPaused returns (bytes32 childNode) {
+        _validateLabel(bytes(label)); // AN-1-ONCHAIN: canonical charset on chain
         if (newOwner == address(0)) revert ZeroOwner();
         _requireParentAuth(parentNode);
         _requireNotExpired(parentNode);
@@ -252,7 +286,7 @@ contract AgentNameRegistry {
      *         Authorized to the node's owner ONLY — labels can't be
      *         changed once set, preventing display spoofing.
      */
-    function backfillLabel(bytes32 node, string calldata label_) external {
+    function backfillLabel(bytes32 node, string calldata label_) external whenNotPaused {
         _requireNodeAuth(node);
         if (bytes(label_).length == 0) revert EmptyLabel();
         if (keccak256(bytes(label_)) != _records[node].labelhash) revert NotAuthorized();
@@ -262,26 +296,26 @@ contract AgentNameRegistry {
 
     // ─── Setters ────────────────────────────────────────────────────
 
-    function setOwner(bytes32 node, address newOwner) external {
+    function setOwner(bytes32 node, address newOwner) external whenNotPaused {
         _requireNodeAuth(node);
         if (newOwner == address(0)) revert ZeroOwner();
         _records[node].owner = newOwner;
         emit OwnerChanged(node, newOwner);
     }
 
-    function setResolver(bytes32 node, address resolverContract) external {
+    function setResolver(bytes32 node, address resolverContract) external whenNotPaused {
         _requireNodeAuth(node);
         _records[node].resolver = resolverContract;
         emit ResolverChanged(node, resolverContract);
     }
 
-    function setSubregistry(bytes32 node, address subregistryContract) external {
+    function setSubregistry(bytes32 node, address subregistryContract) external whenNotPaused {
         _requireNodeAuth(node);
         _records[node].subregistry = subregistryContract;
         emit SubregistryChanged(node, subregistryContract);
     }
 
-    function renew(bytes32 node, uint64 newExpiry) external {
+    function renew(bytes32 node, uint64 newExpiry) external whenNotPaused {
         _requireNodeAuth(node);
         _records[node].expiry = newExpiry;
         emit NameRenewed(node, newExpiry);
@@ -293,7 +327,10 @@ contract AgentNameRegistry {
      *         NOT verify the forward record points back here. The
      *         universal resolver enforces the round-trip on reads.
      */
-    function setPrimaryName(bytes32 node) external {
+    function setPrimaryName(bytes32 node) external whenNotPaused {
+        // R6.3: `registeredAt == 0` is a sentinel "record-never-created" check.
+        // Storage default IS exactly 0; not a numeric precision concern.
+        // slither-disable-next-line incorrect-equality
         if (node != bytes32(0) && _records[node].registeredAt == 0) revert NodeNotFound();
         _primaryName[msg.sender] = node;
         if (node == bytes32(0)) emit PrimaryNameCleared(msg.sender);

package/src/naming/AgentNameUniversalResolver.sol

@@ -122,7 +122,7 @@ contract AgentNameUniversalResolver {
     /**
      * @notice Reverse-resolve a Smart Agent address to its primary name
      *         STRING in a single external call. Per spec/222 this is
-     *         the ENS-aligned reverse path — no log walks, no name
+     *         the on-chain reverse path — no log walks, no name
      *         reconstruction in the SDK, no event indexer required.
      *
      *         Walks `parent(node)` up the registry, reading `label(node)`

package/src/naming/PermissionlessSubregistry.sol

@@ -2,6 +2,7 @@
 pragma solidity ^0.8.28;
 
 import "./AgentNameRegistry.sol";
+import {ReentrancyGuard} from "@openzeppelin/contracts/utils/ReentrancyGuard.sol";
 
 /**
  * @title PermissionlessSubregistry
@@ -36,7 +37,15 @@ import "./AgentNameRegistry.sol";
  *     through whatever authority `newOwner` represents (EOA wallet,
  *     PSA CustodyPolicy quorum, etc.).
  */
-contract PermissionlessSubregistry {
+/// @dev R6.2 — `ReentrancyGuard` closes the Slither finding
+///      `reentrancy-no-eth` on `register()`: the prior-claim check
+///      (`claimedBy[msg.sender] != 0`) was followed by an external
+///      call to `REGISTRY.register(...)` BEFORE the corresponding
+///      state write. A malicious resolver invoked by the registry
+///      could re-enter `register()` and pass the check a second time.
+///      The guard prevents any nested call into `register()`, closing
+///      the window. Recon doc § 4.1 / `docs/audits/r6-contracts-recon-2026-05-31.md`.
+contract PermissionlessSubregistry is ReentrancyGuard {
     AgentNameRegistry public immutable REGISTRY;
     bytes32 public immutable PARENT_NODE;
     address public immutable DEFAULT_RESOLVER;
@@ -77,12 +86,20 @@ contract PermissionlessSubregistry {
      *         fee — fee gating belongs in a different subregistry
      *         shape if needed.
      */
-    function register(string calldata label, address newOwner) external returns (bytes32 childNode) {
+    function register(string calldata label, address newOwner) external nonReentrant returns (bytes32 childNode) {
         if (bytes(label).length == 0) revert EmptyLabel();
         if (bytes(label).length < MIN_LABEL_LENGTH) revert LabelTooShort();
         if (newOwner == address(0)) revert ZeroNewOwner();
         bytes32 prior = claimedBy[msg.sender];
         if (prior != bytes32(0)) revert AlreadyClaimed(prior);
+        // R9 / docs/audits/r9-static-analysis-triage.md § Slither M-1:
+        // Slither flags this as cross-function reentrancy because state is
+        // written AFTER the external call. The function is `nonReentrant`
+        // (line 89) + REGISTRY is an immutable contract we control
+        // (`AgentNameRegistry`) that does not call back into this contract.
+        // The cross-function reader (`hasClaimed`) is view-only. No invariant
+        // is violated by the pre-write-window. Triaged false positive.
+        // slither-disable-next-line reentrancy-no-eth
         childNode = REGISTRY.register(PARENT_NODE, label, newOwner, DEFAULT_RESOLVER, 0);
         claimedBy[msg.sender] = childNode;
         unchecked {

package/src/payments/PaymentEscrow.sol

@@ -0,0 +1,137 @@
+// SPDX-License-Identifier: MIT
+pragma solidity ^0.8.28;
+
+import {IERC20} from "@openzeppelin/contracts/token/ERC20/IERC20.sol";
+import {SafeERC20} from "@openzeppelin/contracts/token/ERC20/utils/SafeERC20.sol";
+import {ReentrancyGuard} from "@openzeppelin/contracts/utils/ReentrancyGuard.sol";
+
+/**
+ * @title PaymentEscrow
+ * @notice Hold-and-capture for an exchange order (spec 243 §5.5 escrow rail, FG-PAY-7).
+ *         A payer funds a hold keyed by `orderHash`; funds then move on exactly ONE terminal path:
+ *           - release  → captured to the payee (on fulfillment evidence)
+ *           - refund   → returned to the payer (payee-consented, before capture)
+ *           - reclaim  → returned to the payer (payer-initiated, after expiry)
+ *         Symmetric-escrow doctrine (273 EXC-D4): any escrowable leg can be held. Ports the
+ *         smart-agent `CommitmentRegistry` status-machine pattern; no third-party escrow dependency.
+ *
+ * @dev    HASH-ONLY events (orderHash only — no amounts/addresses leak; privacy posture §6). Apps read
+ *         hold state via the `getHold` view (`readContract`), never inline `eth_getLogs` (ADR-0012).
+ *         Fail-closed: a hold moves Held → {Captured|Refunded|Reclaimed} once and never again
+ *         (checks-effects-interactions + ReentrancyGuard). Uses OZ SafeERC20 for fee/no-return tokens.
+ */
+contract PaymentEscrow is ReentrancyGuard {
+    using SafeERC20 for IERC20;
+
+    enum Status {
+        None,
+        Held,
+        Captured,
+        Refunded,
+        Reclaimed
+    }
+
+    struct Hold {
+        address payer; // funded the hold
+        address asset; // ERC-20
+        uint256 amount;
+        address payee; // captures on release
+        address refundTo; // receives refund / reclaim
+        address releaser; // OPTIONAL extra party authorized to release (0 = payee-only)
+        uint64 expiry; // payer may reclaim at/after this time
+        Status status;
+    }
+
+    mapping(bytes32 orderHash => Hold) private _holds;
+
+    event EscrowDeposited(bytes32 indexed orderHash);
+    event EscrowReleased(bytes32 indexed orderHash);
+    event EscrowRefunded(bytes32 indexed orderHash);
+    event EscrowReclaimed(bytes32 indexed orderHash);
+
+    error HoldExists();
+    error NoHold();
+    error NotHeld();
+    error ZeroAmount();
+    error ZeroAddress();
+    error BadExpiry();
+    error NotAuthorized();
+    error NotYetExpired();
+
+    /**
+     * @notice Fund a hold for `orderHash`. Pulls `amount` of `asset` from the caller (the payer).
+     * @param refundTo Where refund/reclaim returns funds; 0 defaults to the payer.
+     * @param releaser Extra address allowed to `release` besides `payee`; 0 = payee-only.
+     */
+    function deposit(
+        bytes32 orderHash,
+        address asset,
+        uint256 amount,
+        address payee,
+        address refundTo,
+        address releaser,
+        uint64 expiry
+    ) external nonReentrant {
+        if (_holds[orderHash].status != Status.None) revert HoldExists();
+        if (amount == 0) revert ZeroAmount();
+        if (asset == address(0) || payee == address(0)) revert ZeroAddress();
+        if (expiry <= block.timestamp) revert BadExpiry();
+
+        _holds[orderHash] = Hold({
+            payer: msg.sender,
+            asset: asset,
+            amount: amount,
+            payee: payee,
+            refundTo: refundTo == address(0) ? msg.sender : refundTo,
+            releaser: releaser,
+            expiry: expiry,
+            status: Status.Held
+        });
+        emit EscrowDeposited(orderHash);
+        IERC20(asset).safeTransferFrom(msg.sender, address(this), amount);
+    }
+
+    /// @notice Capture a held order to the payee. Authorized: the payee, or the configured releaser.
+    function release(bytes32 orderHash) external nonReentrant {
+        Hold storage h = _held(orderHash);
+        if (msg.sender != h.payee && (h.releaser == address(0) || msg.sender != h.releaser)) revert NotAuthorized();
+        h.status = Status.Captured;
+        emit EscrowReleased(orderHash);
+        IERC20(h.asset).safeTransfer(h.payee, h.amount);
+    }
+
+    /// @notice Payee-consented refund of a held order to the payer (before capture).
+    function refund(bytes32 orderHash) external nonReentrant {
+        Hold storage h = _held(orderHash);
+        if (msg.sender != h.payee) revert NotAuthorized();
+        h.status = Status.Refunded;
+        emit EscrowRefunded(orderHash);
+        IERC20(h.asset).safeTransfer(h.refundTo, h.amount);
+    }
+
+    /// @notice Payer reclaims a held order after expiry (never released).
+    function reclaim(bytes32 orderHash) external nonReentrant {
+        Hold storage h = _held(orderHash);
+        if (msg.sender != h.payer) revert NotAuthorized();
+        if (block.timestamp < h.expiry) revert NotYetExpired();
+        h.status = Status.Reclaimed;
+        emit EscrowReclaimed(orderHash);
+        IERC20(h.asset).safeTransfer(h.refundTo, h.amount);
+    }
+
+    /// @notice Full hold record (app reads via this view, not log scans — ADR-0012).
+    function getHold(bytes32 orderHash) external view returns (Hold memory) {
+        return _holds[orderHash];
+    }
+
+    function statusOf(bytes32 orderHash) external view returns (Status) {
+        return _holds[orderHash].status;
+    }
+
+    /// @dev Load a hold that MUST be in `Held` (fail-closed): missing → NoHold; terminal → NotHeld.
+    function _held(bytes32 orderHash) private view returns (Hold storage h) {
+        h = _holds[orderHash];
+        if (h.status == Status.None) revert NoHold();
+        if (h.status != Status.Held) revert NotHeld();
+    }
+}

package/src/payments/PaymentReceiptRegistry.sol

@@ -0,0 +1,67 @@
+// SPDX-License-Identifier: MIT
+pragma solidity ^0.8.28;
+
+/**
+ * @title PaymentReceiptRegistry
+ * @notice Trustless, queryable settlement log for x402 pay-per-use (spec 272, PAY-CON-4 / X402-D9.3).
+ *         Only the authorized {PaymentEnforcer} may `record` — a receipt is a byproduct of a gated
+ *         `DelegationManager.redeemDelegation`, so a service cannot fabricate one and the reader's
+ *         charge history needs no trust in service logs.
+ *
+ * @dev    HASHES + ADDRESSES ONLY — no URLs, queries, licensed text, or passage refs ever reach the
+ *         chain (PAY-WIRE-6). Event-only (no per-row storage): apps read settlements via an indexer /
+ *         app cache, never inline `eth_getLogs` in product hot paths (ADR-0012). The
+ *         `PaymentEnforcer.PaymentCharged` event is the primary on-chain receipt; `PaymentSettled`
+ *         here adds payer/payee/mandateId-indexed querying for treasury views.
+ */
+contract PaymentReceiptRegistry {
+    /// @notice The deployer who wires the sole authorized recorder once.
+    address public immutable owner;
+    /// @notice The single PaymentEnforcer permitted to `record` (set once via {setEnforcer}).
+    address public enforcer;
+
+    event PaymentSettled(
+        bytes32 indexed mandateId,
+        address indexed payer,
+        address indexed payee,
+        address asset,
+        uint256 amount,
+        bytes32 resourceHash,
+        bytes32 delegationHash,
+        bytes32 nonce
+    );
+    event EnforcerSet(address indexed enforcer);
+
+    error NotOwner();
+    error NotEnforcer();
+    error EnforcerAlreadySet();
+    error ZeroAddress();
+
+    constructor() {
+        owner = msg.sender;
+    }
+
+    /// @notice One-time wiring: authorize the deployed {PaymentEnforcer} as the sole recorder.
+    function setEnforcer(address enforcer_) external {
+        if (msg.sender != owner) revert NotOwner();
+        if (enforcer != address(0)) revert EnforcerAlreadySet();
+        if (enforcer_ == address(0)) revert ZeroAddress();
+        enforcer = enforcer_;
+        emit EnforcerSet(enforcer_);
+    }
+
+    /// @notice Record a settled payment. Reverts unless called by the authorized enforcer.
+    function record(
+        bytes32 mandateId,
+        address payer,
+        address payee,
+        address asset,
+        uint256 amount,
+        bytes32 resourceHash,
+        bytes32 delegationHash,
+        bytes32 nonce
+    ) external {
+        if (msg.sender != enforcer) revert NotEnforcer();
+        emit PaymentSettled(mandateId, payer, payee, asset, amount, resourceHash, delegationHash, nonce);
+    }
+}

package/src/relationships/AgentRelationship.sol

@@ -34,6 +34,13 @@ pragma solidity ^0.8.28;
  *     Off-chain JSON published at `metadataURI` MUST hash to
  *     `metadataHash`; consumers reject mismatched fetches.
  */
+// R6.3 — Every `e.createdAt == 0` comparison in this contract is a
+//        sentinel "edge-never-created" check. Storage default IS exactly
+//        0 for unset records, so the equality is semantically a
+//        "does-not-exist" probe — not a numeric-precision concern.
+//        Disabling Slither's `incorrect-equality` at the contract scope
+//        keeps these inline reads idiomatic.
+// slither-disable-start incorrect-equality
 contract AgentRelationship {
     enum EdgeStatus {
         NONE,        // 0 — never set (sentinel)
@@ -287,3 +294,4 @@ contract AgentRelationship {
         }
     }
 }
+// slither-disable-end incorrect-equality