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

package/deployments-base-sepolia.json

@@ -5,6 +5,7 @@
   "agentNameResolver": "0xcC9855A23C7a4D4592E68Fe47E195C2f9D832473",
   "agentNameUniversalResolver": "0x7d777d2d0bbc1806B9Cc779121C27fbaAaFDb60b",
   "agentProfileResolver": "0xc448EB159B2a35F07f6E1814CC8d125244d7384B",
+  "agentRegistryBase": "0xe320947b18D3C71710DCB75D4bf200147ded18Df",
   "agentRelationship": "0xE6B8F6C7F1c9857013dA356DF08D0384334A9607",
   "agreementRegistry": "0x7f4d6A74eda1D6ce251D371566f1c6639F9B0DDa",
   "allowedMethodsEnforcer": "0xf77cf06aCd8b9e2f3204fe4bE16449B3594c9633",

package/dist/abi/AgentRegistryBase.json

@@ -0,0 +1,588 @@
+[
+  {
+    "type": "function",
+    "name": "EPOCH_SECONDS",
+    "inputs": [],
+    "outputs": [
+      {
+        "name": "",
+        "type": "uint64",
+        "internalType": "uint64"
+      }
+    ],
+    "stateMutability": "view"
+  },
+  {
+    "type": "function",
+    "name": "createRegistry",
+    "inputs": [
+      {
+        "name": "registryId",
+        "type": "bytes32",
+        "internalType": "bytes32"
+      },
+      {
+        "name": "policy",
+        "type": "address",
+        "internalType": "address"
+      }
+    ],
+    "outputs": [],
+    "stateMutability": "nonpayable"
+  },
+  {
+    "type": "function",
+    "name": "getClaim",
+    "inputs": [
+      {
+        "name": "registryId",
+        "type": "bytes32",
+        "internalType": "bytes32"
+      },
+      {
+        "name": "entryId",
+        "type": "bytes32",
+        "internalType": "bytes32"
+      },
+      {
+        "name": "claimSlotId",
+        "type": "bytes32",
+        "internalType": "bytes32"
+      }
+    ],
+    "outputs": [
+      {
+        "name": "",
+        "type": "bytes32",
+        "internalType": "bytes32"
+      }
+    ],
+    "stateMutability": "view"
+  },
+  {
+    "type": "function",
+    "name": "getEntry",
+    "inputs": [
+      {
+        "name": "registryId",
+        "type": "bytes32",
+        "internalType": "bytes32"
+      },
+      {
+        "name": "entryId",
+        "type": "bytes32",
+        "internalType": "bytes32"
+      }
+    ],
+    "outputs": [
+      {
+        "name": "",
+        "type": "tuple",
+        "internalType": "struct AgentRegistryBase.Entry",
+        "components": [
+          {
+            "name": "subjectAgent",
+            "type": "address",
+            "internalType": "address"
+          },
+          {
+            "name": "cardHash",
+            "type": "bytes32",
+            "internalType": "bytes32"
+          },
+          {
+            "name": "bindingProofHash",
+            "type": "bytes32",
+            "internalType": "bytes32"
+          },
+          {
+            "name": "claimsRoot",
+            "type": "bytes32",
+            "internalType": "bytes32"
+          },
+          {
+            "name": "status",
+            "type": "uint8",
+            "internalType": "enum AgentRegistryBase.EntryStatus"
+          },
+          {
+            "name": "registeredAtBucket",
+            "type": "uint64",
+            "internalType": "uint64"
+          },
+          {
+            "name": "expiresAt",
+            "type": "uint64",
+            "internalType": "uint64"
+          }
+        ]
+      }
+    ],
+    "stateMutability": "view"
+  },
+  {
+    "type": "function",
+    "name": "getRegistry",
+    "inputs": [
+      {
+        "name": "registryId",
+        "type": "bytes32",
+        "internalType": "bytes32"
+      }
+    ],
+    "outputs": [
+      {
+        "name": "",
+        "type": "tuple",
+        "internalType": "struct AgentRegistryBase.Registry",
+        "components": [
+          {
+            "name": "controller",
+            "type": "address",
+            "internalType": "address"
+          },
+          {
+            "name": "policy",
+            "type": "address",
+            "internalType": "address"
+          },
+          {
+            "name": "exists",
+            "type": "bool",
+            "internalType": "bool"
+          }
+        ]
+      }
+    ],
+    "stateMutability": "view"
+  },
+  {
+    "type": "function",
+    "name": "isActive",
+    "inputs": [
+      {
+        "name": "registryId",
+        "type": "bytes32",
+        "internalType": "bytes32"
+      },
+      {
+        "name": "entryId",
+        "type": "bytes32",
+        "internalType": "bytes32"
+      }
+    ],
+    "outputs": [
+      {
+        "name": "",
+        "type": "bool",
+        "internalType": "bool"
+      }
+    ],
+    "stateMutability": "view"
+  },
+  {
+    "type": "function",
+    "name": "registerEntry",
+    "inputs": [
+      {
+        "name": "registryId",
+        "type": "bytes32",
+        "internalType": "bytes32"
+      },
+      {
+        "name": "entryId",
+        "type": "bytes32",
+        "internalType": "bytes32"
+      },
+      {
+        "name": "subjectAgent",
+        "type": "address",
+        "internalType": "address"
+      },
+      {
+        "name": "cardHash",
+        "type": "bytes32",
+        "internalType": "bytes32"
+      },
+      {
+        "name": "bindingProofHash",
+        "type": "bytes32",
+        "internalType": "bytes32"
+      },
+      {
+        "name": "claimHashes",
+        "type": "bytes32[]",
+        "internalType": "bytes32[]"
+      },
+      {
+        "name": "expiresAt",
+        "type": "uint64",
+        "internalType": "uint64"
+      }
+    ],
+    "outputs": [],
+    "stateMutability": "nonpayable"
+  },
+  {
+    "type": "function",
+    "name": "renewEntry",
+    "inputs": [
+      {
+        "name": "registryId",
+        "type": "bytes32",
+        "internalType": "bytes32"
+      },
+      {
+        "name": "entryId",
+        "type": "bytes32",
+        "internalType": "bytes32"
+      },
+      {
+        "name": "expiresAt",
+        "type": "uint64",
+        "internalType": "uint64"
+      }
+    ],
+    "outputs": [],
+    "stateMutability": "nonpayable"
+  },
+  {
+    "type": "function",
+    "name": "revokeEntry",
+    "inputs": [
+      {
+        "name": "registryId",
+        "type": "bytes32",
+        "internalType": "bytes32"
+      },
+      {
+        "name": "entryId",
+        "type": "bytes32",
+        "internalType": "bytes32"
+      },
+      {
+        "name": "reasonHash",
+        "type": "bytes32",
+        "internalType": "bytes32"
+      }
+    ],
+    "outputs": [],
+    "stateMutability": "nonpayable"
+  },
+  {
+    "type": "function",
+    "name": "setRegistryPolicy",
+    "inputs": [
+      {
+        "name": "registryId",
+        "type": "bytes32",
+        "internalType": "bytes32"
+      },
+      {
+        "name": "policy",
+        "type": "address",
+        "internalType": "address"
+      }
+    ],
+    "outputs": [],
+    "stateMutability": "nonpayable"
+  },
+  {
+    "type": "function",
+    "name": "suspendEntry",
+    "inputs": [
+      {
+        "name": "registryId",
+        "type": "bytes32",
+        "internalType": "bytes32"
+      },
+      {
+        "name": "entryId",
+        "type": "bytes32",
+        "internalType": "bytes32"
+      },
+      {
+        "name": "reasonHash",
+        "type": "bytes32",
+        "internalType": "bytes32"
+      }
+    ],
+    "outputs": [],
+    "stateMutability": "nonpayable"
+  },
+  {
+    "type": "function",
+    "name": "updateClaim",
+    "inputs": [
+      {
+        "name": "registryId",
+        "type": "bytes32",
+        "internalType": "bytes32"
+      },
+      {
+        "name": "entryId",
+        "type": "bytes32",
+        "internalType": "bytes32"
+      },
+      {
+        "name": "claimSlotId",
+        "type": "bytes32",
+        "internalType": "bytes32"
+      },
+      {
+        "name": "claimHash",
+        "type": "bytes32",
+        "internalType": "bytes32"
+      }
+    ],
+    "outputs": [],
+    "stateMutability": "nonpayable"
+  },
+  {
+    "type": "event",
+    "name": "RegistryClaimUpdated",
+    "inputs": [
+      {
+        "name": "registryId",
+        "type": "bytes32",
+        "indexed": true,
+        "internalType": "bytes32"
+      },
+      {
+        "name": "entryId",
+        "type": "bytes32",
+        "indexed": true,
+        "internalType": "bytes32"
+      },
+      {
+        "name": "claimSlotId",
+        "type": "bytes32",
+        "indexed": true,
+        "internalType": "bytes32"
+      },
+      {
+        "name": "claimHash",
+        "type": "bytes32",
+        "indexed": false,
+        "internalType": "bytes32"
+      }
+    ],
+    "anonymous": false
+  },
+  {
+    "type": "event",
+    "name": "RegistryCreated",
+    "inputs": [
+      {
+        "name": "registryId",
+        "type": "bytes32",
+        "indexed": true,
+        "internalType": "bytes32"
+      },
+      {
+        "name": "controller",
+        "type": "address",
+        "indexed": true,
+        "internalType": "address"
+      },
+      {
+        "name": "policy",
+        "type": "address",
+        "indexed": false,
+        "internalType": "address"
+      }
+    ],
+    "anonymous": false
+  },
+  {
+    "type": "event",
+    "name": "RegistryEntryRegistered",
+    "inputs": [
+      {
+        "name": "registryId",
+        "type": "bytes32",
+        "indexed": true,
+        "internalType": "bytes32"
+      },
+      {
+        "name": "entryId",
+        "type": "bytes32",
+        "indexed": true,
+        "internalType": "bytes32"
+      },
+      {
+        "name": "subjectAgent",
+        "type": "address",
+        "indexed": true,
+        "internalType": "address"
+      },
+      {
+        "name": "cardHash",
+        "type": "bytes32",
+        "indexed": false,
+        "internalType": "bytes32"
+      },
+      {
+        "name": "bindingProofHash",
+        "type": "bytes32",
+        "indexed": false,
+        "internalType": "bytes32"
+      }
+    ],
+    "anonymous": false
+  },
+  {
+    "type": "event",
+    "name": "RegistryEntryRenewed",
+    "inputs": [
+      {
+        "name": "registryId",
+        "type": "bytes32",
+        "indexed": true,
+        "internalType": "bytes32"
+      },
+      {
+        "name": "entryId",
+        "type": "bytes32",
+        "indexed": true,
+        "internalType": "bytes32"
+      },
+      {
+        "name": "expiresAt",
+        "type": "uint64",
+        "indexed": false,
+        "internalType": "uint64"
+      }
+    ],
+    "anonymous": false
+  },
+  {
+    "type": "event",
+    "name": "RegistryEntryRevoked",
+    "inputs": [
+      {
+        "name": "registryId",
+        "type": "bytes32",
+        "indexed": true,
+        "internalType": "bytes32"
+      },
+      {
+        "name": "entryId",
+        "type": "bytes32",
+        "indexed": true,
+        "internalType": "bytes32"
+      },
+      {
+        "name": "reasonHash",
+        "type": "bytes32",
+        "indexed": false,
+        "internalType": "bytes32"
+      }
+    ],
+    "anonymous": false
+  },
+  {
+    "type": "event",
+    "name": "RegistryEntrySuspended",
+    "inputs": [
+      {
+        "name": "registryId",
+        "type": "bytes32",
+        "indexed": true,
+        "internalType": "bytes32"
+      },
+      {
+        "name": "entryId",
+        "type": "bytes32",
+        "indexed": true,
+        "internalType": "bytes32"
+      },
+      {
+        "name": "reasonHash",
+        "type": "bytes32",
+        "indexed": false,
+        "internalType": "bytes32"
+      }
+    ],
+    "anonymous": false
+  },
+  {
+    "type": "event",
+    "name": "RegistryPolicyUpdated",
+    "inputs": [
+      {
+        "name": "registryId",
+        "type": "bytes32",
+        "indexed": true,
+        "internalType": "bytes32"
+      },
+      {
+        "name": "policy",
+        "type": "address",
+        "indexed": false,
+        "internalType": "address"
+      }
+    ],
+    "anonymous": false
+  },
+  {
+    "type": "error",
+    "name": "AlreadyRevoked",
+    "inputs": []
+  },
+  {
+    "type": "error",
+    "name": "EntryExists",
+    "inputs": []
+  },
+  {
+    "type": "error",
+    "name": "EntryNotFound",
+    "inputs": []
+  },
+  {
+    "type": "error",
+    "name": "InvalidExpiry",
+    "inputs": []
+  },
+  {
+    "type": "error",
+    "name": "MembershipDenied",
+    "inputs": []
+  },
+  {
+    "type": "error",
+    "name": "NotActive",
+    "inputs": []
+  },
+  {
+    "type": "error",
+    "name": "NotAuthorized",
+    "inputs": []
+  },
+  {
+    "type": "error",
+    "name": "NotController",
+    "inputs": []
+  },
+  {
+    "type": "error",
+    "name": "RegistryExists",
+    "inputs": []
+  },
+  {
+    "type": "error",
+    "name": "RegistryNotFound",
+    "inputs": []
+  },
+  {
+    "type": "error",
+    "name": "SubjectMismatch",
+    "inputs": []
+  },
+  {
+    "type": "error",
+    "name": "ZeroSubject",
+    "inputs": []
+  }
+]

package/dist/abi/IRegistryMembershipPolicy.json

@@ -0,0 +1,70 @@
+[
+  {
+    "type": "function",
+    "name": "canAdminister",
+    "inputs": [
+      {
+        "name": "registryId",
+        "type": "bytes32",
+        "internalType": "bytes32"
+      },
+      {
+        "name": "entryId",
+        "type": "bytes32",
+        "internalType": "bytes32"
+      },
+      {
+        "name": "actor",
+        "type": "address",
+        "internalType": "address"
+      }
+    ],
+    "outputs": [
+      {
+        "name": "ok",
+        "type": "bool",
+        "internalType": "bool"
+      }
+    ],
+    "stateMutability": "view"
+  },
+  {
+    "type": "function",
+    "name": "canRegister",
+    "inputs": [
+      {
+        "name": "registryId",
+        "type": "bytes32",
+        "internalType": "bytes32"
+      },
+      {
+        "name": "entryId",
+        "type": "bytes32",
+        "internalType": "bytes32"
+      },
+      {
+        "name": "subjectAgent",
+        "type": "address",
+        "internalType": "address"
+      },
+      {
+        "name": "cardHash",
+        "type": "bytes32",
+        "internalType": "bytes32"
+      },
+      {
+        "name": "claimHashes",
+        "type": "bytes32[]",
+        "internalType": "bytes32[]"
+      }
+    ],
+    "outputs": [
+      {
+        "name": "ok",
+        "type": "bool",
+        "internalType": "bool"
+      }
+    ],
+    "stateMutability": "view"
+  }
+]

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",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agenticprimitives/contracts",
-  "version": "1.0.0-alpha.12",
+  "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/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();
+    }
+}

package/src/registry/IRegistryMembershipPolicy.sol

@@ -0,0 +1,30 @@
+// SPDX-License-Identifier: MIT
+pragma solidity ^0.8.28;
+
+/**
+ * @title IRegistryMembershipPolicy
+ * @notice Pluggable membership/validation hook for {AgentRegistryBase} (spec 279 §4.2). It answers two
+ *         yes/no questions and NOTHING else:
+ *
+ *           - `canRegister`     — may `subjectAgent` create `entryId` in `registryId` with these claims?
+ *           - `canAdminister`   — may a NON-subject `actor` suspend / revoke / update `entryId`?
+ *
+ *         Implementations live OUTSIDE Ring 0 (issuer-attested, stake/bond, quorum-approved,
+ *         domain-control-proof, skill-claim-proof, …) — they MUST NOT push vertical business logic into
+ *         the registry base. Both methods are `view`, so {AgentRegistryBase} reaches them via STATICCALL
+ *         (no state mutation, no reentrancy). A policy that returns `false` OR reverts is treated as a
+ *         denial: the base fails closed (ADR-0013) — there is no second, weaker authorization path.
+ */
+interface IRegistryMembershipPolicy {
+    /// @return ok whether `subjectAgent` may register `entryId` in `registryId` with `cardHash`/`claimHashes`.
+    function canRegister(
+        bytes32 registryId,
+        bytes32 entryId,
+        address subjectAgent,
+        bytes32 cardHash,
+        bytes32[] calldata claimHashes
+    ) external view returns (bool ok);
+
+    /// @return ok whether `actor` (not the entry's subject) may administer (suspend / revoke / update) the entry.
+    function canAdminister(bytes32 registryId, bytes32 entryId, address actor) external view returns (bool ok);
+}