@agenticprimitives/contracts 1.0.0-alpha.11 → 1.0.0-alpha.13

package/dist/abi/PaymentEnforcer.json

@@ -2,6 +2,11 @@
   {
     "type": "constructor",
     "inputs": [
+      {
+        "name": "delegationManager_",
+        "type": "address",
+        "internalType": "address"
+      },
       {
         "name": "receiptRegistry_",
         "type": "address",
@@ -56,7 +61,7 @@
       }
     ],
     "outputs": [],
-    "stateMutability": "pure"
+    "stateMutability": "view"
   },
   {
     "type": "function",
@@ -106,6 +111,19 @@
     "outputs": [],
     "stateMutability": "nonpayable"
   },
+  {
+    "type": "function",
+    "name": "delegationManager",
+    "inputs": [],
+    "outputs": [
+      {
+        "name": "",
+        "type": "address",
+        "internalType": "address"
+      }
+    ],
+    "stateMutability": "view"
+  },
   {
     "type": "function",
     "name": "encodeTerms",
@@ -378,6 +396,17 @@
       }
     ]
   },
+  {
+    "type": "error",
+    "name": "NotDelegationManager",
+    "inputs": [
+      {
+        "name": "caller",
+        "type": "address",
+        "internalType": "address"
+      }
+    ]
+  },
   {
     "type": "error",
     "name": "NotTransferCall",

package/dist/abi/PaymentEscrow.json

@@ -46,6 +46,11 @@
     "type": "function",
     "name": "getHold",
     "inputs": [
+      {
+        "name": "payer",
+        "type": "address",
+        "internalType": "address"
+      },
       {
         "name": "orderHash",
         "type": "bytes32",
@@ -120,6 +125,11 @@
     "type": "function",
     "name": "refund",
     "inputs": [
+      {
+        "name": "payer",
+        "type": "address",
+        "internalType": "address"
+      },
       {
         "name": "orderHash",
         "type": "bytes32",
@@ -133,6 +143,11 @@
     "type": "function",
     "name": "release",
     "inputs": [
+      {
+        "name": "payer",
+        "type": "address",
+        "internalType": "address"
+      },
       {
         "name": "orderHash",
         "type": "bytes32",
@@ -146,6 +161,11 @@
     "type": "function",
     "name": "statusOf",
     "inputs": [
+      {
+        "name": "payer",
+        "type": "address",
+        "internalType": "address"
+      },
       {
         "name": "orderHash",
         "type": "bytes32",
@@ -240,6 +260,11 @@
     "name": "BadExpiry",
     "inputs": []
   },
+  {
+    "type": "error",
+    "name": "Expired",
+    "inputs": []
+  },
   {
     "type": "error",
     "name": "FailedInnerCall",

package/dist/abi/index.d.ts

@@ -10,6 +10,7 @@ export declare const AgentNameRegistry: Abi;
 export declare const AgentNameUniversalResolver: Abi;
 export declare const AgentProfilePredicates: Abi;
 export declare const AgentProfileResolver: Abi;
+export declare const AgentRegistryBase: Abi;
 export declare const AgentRelationship: Abi;
 export declare const AgentRelationshipPredicates: Abi;
 export declare const AgreementRegistry: Abi;
@@ -41,6 +42,7 @@ export declare const IERC7579ModuleLifecycle: Abi;
 export declare const IERC7579ModuleLike: Abi;
 export declare const IGovernanceView: Abi;
 export declare const IPaymentReceiptRegistry: Abi;
+export declare const IRegistryMembershipPolicy: Abi;
 export declare const MockUSDC: Abi;
 export declare const MultiSendCallOnly: Abi;
 export declare const MultiSendCallOnlyHarness: Abi;

package/dist/abi/index.js

@@ -10,6 +10,7 @@ export { default as AgentNameRegistry } from './AgentNameRegistry.json' with { t
 export { default as AgentNameUniversalResolver } from './AgentNameUniversalResolver.json' with { type: 'json' };
 export { default as AgentProfilePredicates } from './AgentProfilePredicates.json' with { type: 'json' };
 export { default as AgentProfileResolver } from './AgentProfileResolver.json' with { type: 'json' };
+export { default as AgentRegistryBase } from './AgentRegistryBase.json' with { type: 'json' };
 export { default as AgentRelationship } from './AgentRelationship.json' with { type: 'json' };
 export { default as AgentRelationshipPredicates } from './AgentRelationshipPredicates.json' with { type: 'json' };
 export { default as AgreementRegistry } from './AgreementRegistry.json' with { type: 'json' };
@@ -41,6 +42,7 @@ export { default as IERC7579ModuleLifecycle } from './IERC7579ModuleLifecycle.js
 export { default as IERC7579ModuleLike } from './IERC7579ModuleLike.json' with { type: 'json' };
 export { default as IGovernanceView } from './IGovernanceView.json' with { type: 'json' };
 export { default as IPaymentReceiptRegistry } from './IPaymentReceiptRegistry.json' with { type: 'json' };
+export { default as IRegistryMembershipPolicy } from './IRegistryMembershipPolicy.json' with { type: 'json' };
 export { default as MockUSDC } from './MockUSDC.json' with { type: 'json' };
 export { default as MultiSendCallOnly } from './MultiSendCallOnly.json' with { type: 'json' };
 export { default as MultiSendCallOnlyHarness } from './MultiSendCallOnlyHarness.json' with { type: 'json' };

package/dist/deployments/base-sepolia.d.ts

@@ -8,6 +8,7 @@ export interface Deployments {
   readonly "agentNameResolver": Address;
   readonly "agentNameUniversalResolver": Address;
   readonly "agentProfileResolver": Address;
+  readonly "agentRegistryBase": Address;
   readonly "agentRelationship": Address;
   readonly "agreementRegistry": Address;
   readonly "allowedMethodsEnforcer": Address;

package/dist/deployments/base-sepolia.js

@@ -7,6 +7,7 @@ export const CONTRACTS = {
   "agentNameResolver": "0xcC9855A23C7a4D4592E68Fe47E195C2f9D832473",
   "agentNameUniversalResolver": "0x7d777d2d0bbc1806B9Cc779121C27fbaAaFDb60b",
   "agentProfileResolver": "0xc448EB159B2a35F07f6E1814CC8d125244d7384B",
+  "agentRegistryBase": "0xe320947b18D3C71710DCB75D4bf200147ded18Df",
   "agentRelationship": "0xE6B8F6C7F1c9857013dA356DF08D0384334A9607",
   "agreementRegistry": "0x7f4d6A74eda1D6ce251D371566f1c6639F9B0DDa",
   "allowedMethodsEnforcer": "0xf77cf06aCd8b9e2f3204fe4bE16449B3594c9633",
@@ -31,9 +32,9 @@ export const CONTRACTS = {
   "timestampEnforcer": "0x7c452434314A5bf2048f9263aeCd0cC20Fa07965",
   "universalSignatureValidator": "0xe8F3e531429F44D77dC3A331C18032bfa1550D84",
   "valueEnforcer": "0x7c4533e0A9fB0B1cb5aa70327b222a80d72d52db",
-  "paymentEnforcer": "0xAF48273e11435cC2D56f4AFBfD091Abb162458E9",
-  "paymentReceiptRegistry": "0x366616E265cd3cDE0F042A592C17838fe210D1d4",
+  "paymentEnforcer": "0xCB5D2dbfc11e146d568764471516C9DB734D2c60",
+  "paymentReceiptRegistry": "0x391Ed4D7538f80a221F910539005bB00b996Ff9F",
   "mockUsdc": "0x8fb56ff3C13347DFC4E1287aE83E88deE5a7211C",
-  "paymentEscrow": "0x954Ba6B3A02E02c5a3Fcd570943126633071cbdD"
+  "paymentEscrow": "0xC85EB1831e9180F5e2cA7854f362f6C9a6D727EA"
 };
 export default CONTRACTS;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agenticprimitives/contracts",
-  "version": "1.0.0-alpha.11",
+  "version": "1.0.0-alpha.13",
   "description": "Solidity contracts + ABIs + flattened sources + per-network deployment addresses for the agenticprimitives stack.",
   "license": "MIT",
   "repository": {

package/src/enforcers/PaymentEnforcer.sol

@@ -58,6 +58,14 @@ contract PaymentEnforcer is ICaveatEnforcer {
     /// delegator => delegationHash => nonce => consumed (on-chain replay guard)
     mapping(address => mapping(bytes32 => mapping(bytes32 => bool))) private _nonceUsed;
 
+    /// @notice The ONLY authorized caller of the hooks (EXT-PMT-1 / C-NEW-1). Unlike the stateless
+    ///         enforcers (timestamp/value/targets/methods), this enforcer MUTATES state (budget, nonce)
+    ///         and writes a settlement receipt — so it is NOT safe to call externally. A direct caller
+    ///         that is not the DelegationManager could otherwise forge a `PaymentSettled` receipt and
+    ///         grief the victim's budget/nonce with no actual transfer. Bound immutably at deploy; the
+    ///         hooks revert `NotDelegationManager` for any other `msg.sender`.
+    address public immutable delegationManager;
+
     /// @notice Trustless receipt sink (PAY-CON-4). Immutable; `address(0)` disables registry receipts
     ///         (the `PaymentCharged` event below is always the primary on-chain receipt).
     IPaymentReceiptRegistry public immutable receiptRegistry;
@@ -84,8 +92,21 @@ contract PaymentEnforcer is ICaveatEnforcer {
     error AggregateExceeded(uint256 spent, uint256 maxAggregate, uint256 amount);
     error FrequencyExceeded(uint32 callsInWindow, uint32 maxRedemptionsPerWindow);
     error NonceReused(bytes32 nonce);
+    error NotDelegationManager(address caller);
+
+    /// @dev The hooks are state-mutating + receipt-emitting, so ONLY the DelegationManager may invoke
+    ///      them (EXT-PMT-1). `_runBeforeHooks`/`_runAfterHooks` call the enforcer directly, so during a
+    ///      real `redeemDelegation` msg.sender IS the DelegationManager. The `verifyAuthorization` view
+    ///      path staticcalls the hook from the same DelegationManager and still reverts on the SSTORE
+    ///      under staticcall (yields `false`), exactly as before — the modifier does not change that.
+    modifier onlyDelegationManager() {
+        if (msg.sender != delegationManager) revert NotDelegationManager(msg.sender);
+        _;
+    }
 
-    constructor(address receiptRegistry_) {
+    constructor(address delegationManager_, address receiptRegistry_) {
+        require(delegationManager_ != address(0), "PaymentEnforcer: zero DelegationManager");
+        delegationManager = delegationManager_;
         receiptRegistry = IPaymentReceiptRegistry(receiptRegistry_);
     }
 
@@ -98,7 +119,7 @@ contract PaymentEnforcer is ICaveatEnforcer {
         address target,
         uint256 value,
         bytes calldata callData
-    ) external override {
+    ) external override onlyDelegationManager {
         // ── terms (immutable, set at delegation creation) ──
         if (terms.length != 192) revert InvalidTerms();
         (
@@ -161,8 +182,9 @@ contract PaymentEnforcer is ICaveatEnforcer {
 
     function afterHook(bytes calldata, bytes calldata, bytes32, address, address, address, uint256, bytes calldata)
         external
-        pure
+        view
         override
+        onlyDelegationManager
     {}
 
     // ── views (off-chain budget display + idempotency checks) ──

package/src/payments/PaymentEscrow.sol

@@ -42,7 +42,10 @@ contract PaymentEscrow is ReentrancyGuard {
         Status status;
     }
 
-    mapping(bytes32 orderHash => Hold) private _holds;
+    // EXT-PMT-3: holds are keyed by (payer, orderHash), NOT orderHash alone — so a stranger cannot
+    // squat a predictable orderHash to block the real payer's deposit (HoldExists griefing). Each payer
+    // has an independent namespace for any given orderHash.
+    mapping(bytes32 holdKey => Hold) private _holds;
 
     event EscrowDeposited(bytes32 indexed orderHash);
     event EscrowReleased(bytes32 indexed orderHash);
@@ -57,6 +60,13 @@ contract PaymentEscrow is ReentrancyGuard {
     error BadExpiry();
     error NotAuthorized();
     error NotYetExpired();
+    error Expired();
+
+    /// @dev The (payer, orderHash) namespace key. Terminal calls by the payee/releaser pass `payer`;
+    ///      the payer's own `reclaim`/`deposit` derive it from `msg.sender`.
+    function _key(address payer, bytes32 orderHash) private pure returns (bytes32) {
+        return keccak256(abi.encode(payer, orderHash));
+    }
 
     /**
      * @notice Fund a hold for `orderHash`. Pulls `amount` of `asset` from the caller (the payer).
@@ -72,15 +82,30 @@ contract PaymentEscrow is ReentrancyGuard {
         address releaser,
         uint64 expiry
     ) external nonReentrant {
-        if (_holds[orderHash].status != Status.None) revert HoldExists();
+        bytes32 key = _key(msg.sender, orderHash);
+        if (_holds[key].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({
+        // EXT-PMT-3: credit the REALIZED amount received (balance delta), not the requested `amount`. A
+        // fee-on-transfer / rebasing asset delivers less than `amount`, which would otherwise over-credit
+        // the hold and let it draw from other holds' funds in the shared pool (cross-hold drain). The
+        // external transfer happens before the storage write, but nonReentrant + the status check above
+        // keep it safe (a reentrant deposit is blocked; a duplicate (payer,orderHash) reverts HoldExists).
+        uint256 beforeBal = IERC20(asset).balanceOf(address(this));
+        // Triaged false positive: `deposit` is `nonReentrant`, so the balanceOf delta cannot be
+        // manipulated by re-entering between the two reads — the guard blocks any callback. The
+        // before/after balance read is the EXT-PMT-3 realized-amount fix for fee-on-transfer assets.
+        // slither-disable-next-line reentrancy-balance
+        IERC20(asset).safeTransferFrom(msg.sender, address(this), amount);
+        uint256 received = IERC20(asset).balanceOf(address(this)) - beforeBal;
+        if (received == 0) revert ZeroAmount();
+
+        _holds[key] = Hold({
             payer: msg.sender,
             asset: asset,
-            amount: amount,
+            amount: received,
             payee: payee,
             refundTo: refundTo == address(0) ? msg.sender : refundTo,
             releaser: releaser,
@@ -88,49 +113,51 @@ contract PaymentEscrow is ReentrancyGuard {
             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);
+    ///         `payer` namespaces the hold (EXT-PMT-3). Cannot release at/after expiry — that window is
+    ///         the payer's `reclaim` (removes the prior release/reclaim race; spec 243 §reclaim intent).
+    function release(address payer, bytes32 orderHash) external nonReentrant {
+        Hold storage h = _held(_key(payer, orderHash));
         if (msg.sender != h.payee && (h.releaser == address(0) || msg.sender != h.releaser)) revert NotAuthorized();
+        if (block.timestamp >= h.expiry) revert Expired();
         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);
+    /// @notice Payee-consented refund of a held order to the payer (before capture). `payer` namespaces.
+    function refund(address payer, bytes32 orderHash) external nonReentrant {
+        Hold storage h = _held(_key(payer, 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).
+    /// @notice Payer reclaims a held order after expiry (never released). Payer-initiated → the hold is
+    ///         derived from `msg.sender`, so only the payer can reach their own hold.
     function reclaim(bytes32 orderHash) external nonReentrant {
-        Hold storage h = _held(orderHash);
-        if (msg.sender != h.payer) revert NotAuthorized();
+        Hold storage h = _held(_key(msg.sender, orderHash));
         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];
+    /// @notice Full hold record for (payer, orderHash) — app reads via this view, not log scans (ADR-0012).
+    function getHold(address payer, bytes32 orderHash) external view returns (Hold memory) {
+        return _holds[_key(payer, orderHash)];
     }
 
-    function statusOf(bytes32 orderHash) external view returns (Status) {
-        return _holds[orderHash].status;
+    function statusOf(address payer, bytes32 orderHash) external view returns (Status) {
+        return _holds[_key(payer, 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];
+    function _held(bytes32 key) private view returns (Hold storage h) {
+        h = _holds[key];
         if (h.status == Status.None) revert NoHold();
         if (h.status != Status.Held) revert NotHeld();
     }

package/src/registry/AgentRegistryBase.sol

@@ -0,0 +1,281 @@
+// SPDX-License-Identifier: MIT
+pragma solidity ^0.8.28;
+
+import {IRegistryMembershipPolicy} from "./IRegistryMembershipPolicy.sol";
+
+/**
+ * @title AgentRegistryBase
+ * @notice The generic, SA-anchored registry base that vertical registries are built FROM (spec 279 §4,
+ *         ADR-0038 "many-registries"). It is a MEMBERSHIP LEDGER of facets — entries that point AT a
+ *         Smart Agent address — not an account. It holds no funds, signs nothing, executes nothing, and
+ *         grants NO authority to act: an entry is evidence ("this SA is a member of registry R, here is
+ *         its card hash + binding-proof hash + claims"), never a delegation. Authority lives in the
+ *         AgentAccount + DelegationManager; this contract only records and gates membership.
+ *
+ *         ─── How it differs from AgentAccount ───
+ *         AgentAccount IS the agent (ERC-4337/7579 custody + execution + ERC-1271). AgentRegistryBase is
+ *         a directory of MANY entries pointing at MANY agents, one instance per registry. The subject SA
+ *         controls its own entry because it must be the caller (RB-01); the registry's controller / policy
+ *         hook gates admission + ejection (RB-02/03). The binding proof referenced by `bindingProofHash`
+ *         is verified OFF-CHAIN by a verifier (registry-kit `verifyEntryBindingProof`) against the
+ *         subject SA's ERC-1271 — this contract stores the hash as a pointer, it does not re-verify it.
+ *
+ *         ─── Key invariants (RB-*) ───
+ *         RB-01 entry control follows the subject SA custody policy — register / renew / self-revoke /
+ *               self-update require `msg.sender == subjectAgent` (so the SA's own custody produced the
+ *               call); the contract never re-implements custody.
+ *         RB-02 admission is gated by the registry's pluggable membership hook (or open if unset); a
+ *               policy returning false OR reverting fails closed (ADR-0013) — no second path.
+ *         RB-03 suspension / revocation / claim-update by a non-subject require the registry controller
+ *               OR a policy-authorized actor (`canAdminister`); never an arbitrary caller.
+ *         RB-04 revocation is terminal; a revoked entry cannot be renewed, re-registered, suspended, or
+ *               claim-updated.
+ *         RB-05 NO external-registry-protocol fields in storage (no ENS/8004/HCS/OASF) — those are
+ *               external projections (ADR-0037), not AP state.
+ *         RB-06 reads are storage views only — discovery never scans chain logs (ADR-0012); the indexer
+ *               consumes the events below.
+ *         RB-07 epoch-bucket registration timestamps (raw block.timestamp never stored); `expiresAt` is a
+ *               caller-supplied absolute unix-seconds bound compared against block.timestamp for liveness.
+ *
+ *         Spec 279 §4 + ADR-0010 / 0012 / 0013 / 0037 / 0038.
+ */
+contract AgentRegistryBase {
+    // ─── Constants ──────────────────────────────────────────────────────
+
+    /// @dev RB-07 — registration time is bucketed (provenance, not a precise clock). Mirrors AttestationRegistry.
+    uint64 public constant EPOCH_SECONDS = 3600;
+
+    // ─── Types ──────────────────────────────────────────────────────────
+
+    /// @dev Stored status. `Expired` is NOT stored (no keeper to flip it) — it is DERIVED from `expiresAt`
+    ///      by {isActive}; storage only tracks the explicit lifecycle transitions.
+    enum EntryStatus {
+        None,
+        Active,
+        Suspended,
+        Revoked
+    }
+
+    struct Registry {
+        address controller; // the governing SA (set on create); address(0) iff !exists
+        address policy; // pluggable membership hook; address(0) = open registry (subject self-service only)
+        bool exists;
+    }
+
+    struct Entry {
+        address subjectAgent; // the canonical SA this entry is a facet of
+        bytes32 cardHash; // sha256 of the agent-profile signed card bundle
+        bytes32 bindingProofHash; // sha256 of the off-chain binding proof (verified off-chain, not here)
+        bytes32 claimsRoot; // keccak of the registration-time claimHashes[] (the set the binding proof signed)
+        EntryStatus status;
+        uint64 registeredAtBucket; // block.timestamp / EPOCH_SECONDS at registration
+        uint64 expiresAt; // absolute unix seconds; 0 = non-expiring
+    }
+
+    // ─── Storage ────────────────────────────────────────────────────────
+
+    mapping(bytes32 => Registry) private _registries; // registryId => Registry
+    mapping(bytes32 => Entry) private _entries; // entryKey => Entry
+    mapping(bytes32 => mapping(bytes32 => bytes32)) private _claims; // entryKey => claimSlotId => claimHash
+
+    // ─── Errors ─────────────────────────────────────────────────────────
+
+    error RegistryExists();
+    error RegistryNotFound();
+    error NotController();
+    error EntryExists();
+    error EntryNotFound();
+    error ZeroSubject();
+    error SubjectMismatch(); // msg.sender is not the entry's subject SA (RB-01)
+    error NotAuthorized(); // msg.sender is neither controller nor a policy-authorized admin (RB-03)
+    error NotActive();
+    error AlreadyRevoked();
+    error InvalidExpiry();
+    error MembershipDenied(); // RB-02 fail-closed admission denial
+
+    // ─── Events ─────────────────────────────────────────────────────────
+
+    // Registry provisioning (not part of the registry-kit lifecycle ABI).
+    event RegistryCreated(bytes32 indexed registryId, address indexed controller, address policy);
+    event RegistryPolicyUpdated(bytes32 indexed registryId, address policy);
+
+    // Entry lifecycle — MUST match registry-kit `AGENT_REGISTRY_BASE_ABI` + spec 279 §4.1 EXACTLY
+    // (the SDK encodes calls against / decodes logs from these signatures).
+    event RegistryEntryRegistered(
+        bytes32 indexed registryId,
+        bytes32 indexed entryId,
+        address indexed subjectAgent,
+        bytes32 cardHash,
+        bytes32 bindingProofHash
+    );
+    event RegistryEntryRenewed(bytes32 indexed registryId, bytes32 indexed entryId, uint64 expiresAt);
+    event RegistryEntrySuspended(bytes32 indexed registryId, bytes32 indexed entryId, bytes32 reasonHash);
+    event RegistryEntryRevoked(bytes32 indexed registryId, bytes32 indexed entryId, bytes32 reasonHash);
+    event RegistryClaimUpdated(
+        bytes32 indexed registryId, bytes32 indexed entryId, bytes32 indexed claimSlotId, bytes32 claimHash
+    );
+
+    // ─── Registry provisioning ──────────────────────────────────────────
+
+    /// @notice Create a registry. Permissionless + first-create-wins: `msg.sender` becomes the controller.
+    /// @dev `registryId` is `keccak256(urn:ap:registry:…)` off-chain; squatting on an id is a PROVISIONING
+    ///      concern (create the registry in the same flow that mints its urn), out of scope for this base.
+    ///      `policy == address(0)` ⇒ open registry: any SA may self-register, no admission gate.
+    function createRegistry(bytes32 registryId, address policy) external {
+        if (_registries[registryId].exists) revert RegistryExists();
+        _registries[registryId] = Registry({controller: msg.sender, policy: policy, exists: true});
+        emit RegistryCreated(registryId, msg.sender, policy);
+    }
+
+    /// @notice Swap the pluggable membership hook. Controller only.
+    function setRegistryPolicy(bytes32 registryId, address policy) external {
+        Registry storage r = _registries[registryId];
+        if (!r.exists) revert RegistryNotFound();
+        if (msg.sender != r.controller) revert NotController();
+        r.policy = policy;
+        emit RegistryPolicyUpdated(registryId, policy);
+    }
+
+    // ─── Entry lifecycle ────────────────────────────────────────────────
+
+    /// @notice Register a facet of `subjectAgent`. RB-01: the subject SA must be the caller. RB-02: the
+    ///         registry's membership hook (if any) must admit. Signature ABI matches registry-kit.
+    function registerEntry(
+        bytes32 registryId,
+        bytes32 entryId,
+        address subjectAgent,
+        bytes32 cardHash,
+        bytes32 bindingProofHash,
+        bytes32[] calldata claimHashes,
+        uint64 expiresAt
+    ) external {
+        Registry storage r = _registries[registryId];
+        if (!r.exists) revert RegistryNotFound();
+        if (subjectAgent == address(0)) revert ZeroSubject();
+        if (msg.sender != subjectAgent) revert SubjectMismatch(); // RB-01
+        if (expiresAt != 0 && expiresAt <= block.timestamp) revert InvalidExpiry();
+
+        bytes32 key = _entryKey(registryId, entryId);
+        if (_entries[key].status != EntryStatus.None) revert EntryExists();
+
+        // RB-02 — admission gate, fail-closed: a false return OR a revert blocks registration.
+        address policy = r.policy;
+        if (policy != address(0)) {
+            try IRegistryMembershipPolicy(policy)
+                .canRegister(registryId, entryId, subjectAgent, cardHash, claimHashes) returns (
+                bool ok
+            ) {
+                if (!ok) revert MembershipDenied();
+            } catch {
+                revert MembershipDenied();
+            }
+        }
+
+        _entries[key] = Entry({
+            subjectAgent: subjectAgent,
+            cardHash: cardHash,
+            bindingProofHash: bindingProofHash,
+            claimsRoot: keccak256(abi.encode(claimHashes)),
+            status: EntryStatus.Active,
+            registeredAtBucket: uint64(block.timestamp) / EPOCH_SECONDS,
+            expiresAt: expiresAt
+        });
+
+        emit RegistryEntryRegistered(registryId, entryId, subjectAgent, cardHash, bindingProofHash);
+    }
+
+    /// @notice Extend an active entry's expiry. RB-01: subject SA only. RB-04: a revoked/suspended entry
+    ///         cannot be renewed.
+    function renewEntry(bytes32 registryId, bytes32 entryId, uint64 expiresAt) external {
+        Entry storage e = _entries[_entryKey(registryId, entryId)];
+        if (e.status == EntryStatus.None) revert EntryNotFound();
+        if (msg.sender != e.subjectAgent) revert SubjectMismatch(); // RB-01
+        if (e.status != EntryStatus.Active) revert NotActive(); // RB-04 (Suspended/Revoked)
+        if (expiresAt != 0 && expiresAt <= block.timestamp) revert InvalidExpiry();
+        e.expiresAt = expiresAt;
+        emit RegistryEntryRenewed(registryId, entryId, expiresAt);
+    }
+
+    /// @notice Suspend an active entry. RB-03: admin action (controller or policy-authorized) — NOT subject.
+    function suspendEntry(bytes32 registryId, bytes32 entryId, bytes32 reasonHash) external {
+        Entry storage e = _entries[_entryKey(registryId, entryId)];
+        if (e.status == EntryStatus.None) revert EntryNotFound();
+        _requireAdmin(registryId, entryId); // RB-03
+        if (e.status != EntryStatus.Active) revert NotActive();
+        e.status = EntryStatus.Suspended;
+        emit RegistryEntrySuspended(registryId, entryId, reasonHash);
+    }
+
+    /// @notice Revoke an entry (terminal). The subject SA may leave; the controller / policy-admin may eject.
+    function revokeEntry(bytes32 registryId, bytes32 entryId, bytes32 reasonHash) external {
+        Entry storage e = _entries[_entryKey(registryId, entryId)];
+        if (e.status == EntryStatus.None) revert EntryNotFound();
+        if (msg.sender != e.subjectAgent) _requireAdmin(registryId, entryId); // subject (leave) or admin (eject)
+        if (e.status == EntryStatus.Revoked) revert AlreadyRevoked(); // RB-04
+        e.status = EntryStatus.Revoked;
+        emit RegistryEntryRevoked(registryId, entryId, reasonHash);
+    }
+
+    /// @notice Set a per-slot claim hash. Subject self-service OR admin (issuer/registry-managed claims).
+    /// @dev Distinct from `claimsRoot` (the immutable snapshot the binding proof signed at registration):
+    ///      this is the mutable, slot-keyed projection the indexer reads for discovery.
+    function updateClaim(bytes32 registryId, bytes32 entryId, bytes32 claimSlotId, bytes32 claimHash) external {
+        bytes32 key = _entryKey(registryId, entryId);
+        Entry storage e = _entries[key];
+        if (e.status == EntryStatus.None) revert EntryNotFound();
+        if (e.status == EntryStatus.Revoked) revert AlreadyRevoked(); // RB-04
+        if (msg.sender != e.subjectAgent) _requireAdmin(registryId, entryId);
+        _claims[key][claimSlotId] = claimHash;
+        emit RegistryClaimUpdated(registryId, entryId, claimSlotId, claimHash);
+    }
+
+    // ─── Views (RB-06: discovery reads use these, never log scans) ──────
+
+    function getRegistry(bytes32 registryId) external view returns (Registry memory) {
+        Registry memory r = _registries[registryId];
+        if (!r.exists) revert RegistryNotFound();
+        return r;
+    }
+
+    function getEntry(bytes32 registryId, bytes32 entryId) external view returns (Entry memory) {
+        Entry memory e = _entries[_entryKey(registryId, entryId)];
+        if (e.status == EntryStatus.None) revert EntryNotFound();
+        return e;
+    }
+
+    /// @notice Effective liveness: stored-Active AND not past `expiresAt`. A missing entry returns false
+    ///         (empty is an answer, ADR-0013 — not a trigger for a fallback lookup).
+    function isActive(bytes32 registryId, bytes32 entryId) external view returns (bool) {
+        Entry memory e = _entries[_entryKey(registryId, entryId)];
+        if (e.status != EntryStatus.Active) return false;
+        if (e.expiresAt != 0 && block.timestamp > e.expiresAt) return false;
+        return true;
+    }
+
+    /// @notice The current hash for a claim slot (0 if unset). Slot semantics are defined by the registry.
+    function getClaim(bytes32 registryId, bytes32 entryId, bytes32 claimSlotId) external view returns (bytes32) {
+        return _claims[_entryKey(registryId, entryId)][claimSlotId];
+    }
+
+    // ─── Internal ───────────────────────────────────────────────────────
+
+    function _entryKey(bytes32 registryId, bytes32 entryId) internal pure returns (bytes32) {
+        return keccak256(abi.encodePacked(registryId, entryId));
+    }
+
+    /// @dev RB-03 — controller passes; otherwise the pluggable policy may authorize the actor. Fail-closed:
+    ///      no policy, a false return, or a revert all deny.
+    function _requireAdmin(bytes32 registryId, bytes32 entryId) internal view {
+        Registry storage r = _registries[registryId];
+        if (msg.sender == r.controller) return;
+        address policy = r.policy;
+        if (policy != address(0)) {
+            try IRegistryMembershipPolicy(policy).canAdminister(registryId, entryId, msg.sender) returns (bool ok) {
+                if (ok) return;
+            } catch {
+                // fail-closed: treat a reverting policy as denial
+            }
+        }
+        revert NotAuthorized();
+    }
+}