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

package/src/SmartAgentPaymaster.sol

@@ -260,16 +260,21 @@ contract SmartAgentPaymaster is BasePaymaster {
         return _pausedMirror;
     }
 
-    /// @dev Read the canonical governance pause flag. Used ONLY by the
-    ///      out-of-band sync path, never during validation. Mirrors the prior
-    ///      defensive decode: a non-conforming governance (EOA / missing fn)
-    ///      reads as "not paused" so legacy / test deploys keep working.
+    /// @dev Read the canonical governance pause flag. Used ONLY by the out-of-band sync path, never
+    ///      during validation (ERC-7562 scope). L1 (seam audit): distinguish "no governance configured"
+    ///      (legacy / test deploy — not paused, by design) from "governance IS configured but the read
+    ///      faulted / returned malformed data" (a governance outage or non-conforming contract), which now
+    ///      FAILS CLOSED — treat as paused so a sync during a governance fault halts sponsorship rather
+    ///      than fail-open sponsoring. Only a clean, decodable `false` permits sponsorship.
     function _governanceIsPaused() internal view returns (bool) {
-        if (governance.code.length == 0) return false;
+        // Unconfigured governance (unset, or an EOA with no code) → not paused (legacy/test path).
+        if (governance == address(0) || governance.code.length == 0) return false;
         (bool ok, bytes memory data) = governance.staticcall(
             abi.encodeWithSelector(IGovernanceView.isPaused.selector)
         );
-        return ok && data.length >= 32 && abi.decode(data, (bool));
+        // Configured but faulted (call failed or undecodable) → fail closed (paused).
+        if (!ok || data.length < 32) return true;
+        return abi.decode(data, (bool));
     }
 
     // ─── PM-2: governance-timelocked deposit withdrawal ────────────────

package/src/custody/CustodyPolicy.sol

@@ -309,6 +309,11 @@ contract CustodyPolicy {
     error AdminInsufficientQuorum(uint256 supplied, uint8 required);
     error AdminDuplicateOrUnsortedSigner(address signer);
     error AdminUnauthorizedSigner(address signer);
+    /// @notice ACCT-C2 (spec 300) — the account itself was presented as a quorum
+    ///         signer (via `isCustodian(address(this))==true` or the `v=0`
+    ///         self-referential ERC-1271 slot). A self-signature must never count
+    ///         toward the quorum, else one custodian forges an extra member.
+    error AdminSelfSignerNotAllowed(address account);
     error TrusteeAlreadyExists(address guardian);
     error TrusteeDoesNotExist(address guardian);
     error InvalidMode(uint8 mode_);
@@ -748,6 +753,11 @@ contract CustodyPolicy {
             );
             if (signer <= prev) revert AdminDuplicateOrUnsortedSigner(signer);
             prev = signer;
+            // ACCT-C2 (spec 300): the account is never its own quorum signer. Both
+            // exploit shapes — `isCustodian(address(this))==true` and the `v=0`
+            // self-referential ERC-1271 slot that recovers `signer==account` — land
+            // here as `signer == account`, so one guard closes both.
+            if (signer == account) revert AdminSelfSignerNotAllowed(account);
             if (vargs.guardianMode) {
                 if (!c.trustees[signer]) revert UnauthorizedTrustee(signer);
             } else {

package/src/enforcers/PaymentEnforcer.sol

@@ -58,6 +58,13 @@ contract PaymentEnforcer is ICaveatEnforcer {
     /// delegator => delegationHash => nonce => consumed (on-chain replay guard)
     mapping(address => mapping(bytes32 => mapping(bytes32 => bool))) private _nonceUsed;
 
+    /// @notice M1 (seam audit): keccak256(delegator, delegationHash, nonce) => (treasury balanceBefore + 1).
+    ///         Snapshotted in `beforeHook`; consumed in `afterHook` to verify the transfer ACTUALLY moved
+    ///         `amount` to the treasury before the settlement receipt is written. `+1` sentinel so a set
+    ///         entry is distinguishable from an unset slot even when the treasury balance is 0. Set and
+    ///         deleted within a single non-reentrant `redeemDelegation`, so it never persists across txs.
+    mapping(bytes32 => uint256) private _settleSnap;
+
     /// @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
@@ -93,6 +100,10 @@ contract PaymentEnforcer is ICaveatEnforcer {
     error FrequencyExceeded(uint32 callsInWindow, uint32 maxRedemptionsPerWindow);
     error NonceReused(bytes32 nonce);
     error NotDelegationManager(address caller);
+    /// @notice M1 (seam audit): the transfer did not move `amount` to the treasury (a token that returns
+    ///         false without reverting, a fee-on-transfer skim, or a missing beforeHook snapshot) — so no
+    ///         settlement receipt is written and the whole redemption reverts.
+    error SettlementNotObserved();
 
     /// @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
@@ -173,19 +184,49 @@ contract PaymentEnforcer is ICaveatEnforcer {
             delegator, delegationHash, mandateId, treasury, asset, amount, nonce, resourceHash, nextSpent, nextCalls
         );
 
-        // Trustless settlement receipt (PAY-CON-4). Reverting here reverts the whole redemption, so a
-        // settled charge always has a receipt and an unsettled one never does (atomic).
+        // M1 (seam audit): snapshot the treasury balance BEFORE the transfer. The trustless settlement
+        // receipt (PAY-CON-4) is written in `afterHook` ONLY once the transfer is observed to have moved
+        // `amount` to the treasury — a token that returns false without reverting (or a fee-on-transfer
+        // skim) then records NO receipt and reverts the whole redemption, so "a settled charge always has
+        // a receipt and an unsettled one never does" holds against the value that ACTUALLY moved.
+        _settleSnap[_settleKey(delegator, delegationHash, nonce)] = IERC20(asset).balanceOf(treasury) + 1;
+    }
+
+    function afterHook(
+        bytes calldata terms,
+        bytes calldata args,
+        bytes32 delegationHash,
+        address delegator,
+        address, /*redeemer*/
+        address, /*target*/
+        uint256, /*value*/
+        bytes calldata callData
+    ) external override onlyDelegationManager {
+        // Only this enforcer's own 192-byte-terms caveat carries a snapshot (beforeHook validated the
+        // shape); ignore anything else defensively so a malformed sibling caveat can't revert settlement.
+        if (terms.length != 192) return;
+        (address treasury, address asset,,,,) = abi.decode(terms, (address, address, uint256, uint256, uint32, uint32));
+        (bytes32 mandateId, bytes32 nonce, bytes32 resourceHash) = abi.decode(args, (bytes32, bytes32, bytes32));
+        (, uint256 amount) = abi.decode(callData[4:], (address, uint256));
+
+        bytes32 key = _settleKey(delegator, delegationHash, nonce);
+        uint256 snap = _settleSnap[key];
+        if (snap == 0) revert SettlementNotObserved(); // no beforeHook snapshot (defensive)
+        delete _settleSnap[key];
+
+        // The treasury must have received AT LEAST `amount` since the snapshot. A silent transfer failure
+        // (balance unchanged) or a fee-on-transfer short-delivery fails this and reverts the redemption.
+        if (IERC20(asset).balanceOf(treasury) < (snap - 1) + amount) revert SettlementNotObserved();
+
         if (address(receiptRegistry) != address(0)) {
             receiptRegistry.record(mandateId, delegator, treasury, asset, amount, resourceHash, delegationHash, nonce);
         }
     }
 
-    function afterHook(bytes calldata, bytes calldata, bytes32, address, address, address, uint256, bytes calldata)
-        external
-        view
-        override
-        onlyDelegationManager
-    {}
+    /// @dev Unique per redemption — the nonce is single-use per [delegator][delegationHash].
+    function _settleKey(address delegator, bytes32 delegationHash, bytes32 nonce) private pure returns (bytes32) {
+        return keccak256(abi.encode(delegator, delegationHash, nonce));
+    }
 
     // ── views (off-chain budget display + idempotency checks) ──
 

package/src/identity/AgentProfilePredicates.sol

@@ -28,6 +28,9 @@ library AgentProfilePredicates {
     // ─── Identity-only ──────────────────────────────────────────────
 
     bytes32 internal constant ATL_DESCRIPTION       = keccak256("atl:description");
+    /// spec 282 — publicly-asserted skill labels (string; the indexer projects to approf:skills, the
+    /// discovery matcher ranks on it). The agent's full private skill claims live in agent-skills VCs.
+    bytes32 internal constant ATL_SKILLS            = keccak256("atl:skills");
     bytes32 internal constant ATL_HOMEPAGE          = keccak256("atl:homepage");
     bytes32 internal constant ATL_AVATAR            = keccak256("atl:avatar");
     bytes32 internal constant ATL_PROFILE_SCHEMA_URI = keccak256("atl:profileSchemaURI");

package/src/naming/AgentNamePredicates.sol

@@ -55,6 +55,17 @@ library AgentNamePredicates {
     /// (per ADR-0008). `string`.
     bytes32 internal constant ATL_NATIVE_ID                  = keccak256("atl:nativeId");
 
+    /// `atl:connectionKind` — connection-bootstrap credential KIND (spec 280).
+    /// Stored as `bytes32` (hashed enum). Bound to CONNECTION_KIND_ENUM. OPT-IN,
+    /// owner-set, PUBLIC. Advertises how a returning person connects by name.
+    bytes32 internal constant ATL_CONNECTION_KIND            = keccak256("atl:connectionKind");
+
+    /// `atl:connectionAddress` — connection-bootstrap credential ADDRESS (spec 280).
+    /// The custodian EOA (wallet) or social KMS C_sub. `address`. OPT-IN, owner-set,
+    /// PUBLIC pre-select hint only (NOT required to connect). Deliberate, documented
+    /// name→credential index (ADR-0040 amendment). Never set automatically.
+    bytes32 internal constant ATL_CONNECTION_ADDRESS         = keccak256("atl:connectionAddress");
+
     // ─── Shape + enum-set ids ───────────────────────────────────────
 
     /// `atl:AgentName` — the class id for ShapeRegistry validation.
@@ -71,4 +82,14 @@ library AgentNamePredicates {
     bytes32 internal constant AGENT_KIND_PERSON              = keccak256("person");
     bytes32 internal constant AGENT_KIND_ORG                 = keccak256("org");
     bytes32 internal constant AGENT_KIND_SERVICE             = keccak256("service");
+
+    /// Enum set bound to `atl:connectionKind` (spec 280). Contains the
+    /// five hashed member ids below.
+    bytes32 internal constant CONNECTION_KIND_ENUM           = keccak256("atl:ConnectionKindEnum");
+
+    bytes32 internal constant CONNECTION_KIND_WALLET         = keccak256("wallet");
+    bytes32 internal constant CONNECTION_KIND_GOOGLE         = keccak256("google");
+    bytes32 internal constant CONNECTION_KIND_YOUVERSION     = keccak256("youversion");
+    bytes32 internal constant CONNECTION_KIND_PASSKEY        = keccak256("passkey");
+    bytes32 internal constant CONNECTION_KIND_MULTI          = keccak256("multi");
 }

package/src/naming/AgentNameRegistry.sol

@@ -261,7 +261,10 @@ contract AgentNameRegistry is GovernanceManaged {
 
         bytes32 lh = keccak256(bytes(label));
         childNode = keccak256(abi.encodePacked(parentNode, lh));
-        if (_records[childNode].registeredAt != 0) revert NodeAlreadyExists();
+        // M2 (seam audit): an EXPIRED name is reclaimable (parent-authorized re-register). Only a LIVE
+        // record blocks re-registration — previously expiry was inert and a name could never be reclaimed.
+        bool reclaiming = _records[childNode].registeredAt != 0;
+        if (reclaiming && !isExpired(childNode)) revert NodeAlreadyExists();
 
         _records[childNode] = NameRecord({
             owner: newOwner,
@@ -274,7 +277,8 @@ contract AgentNameRegistry is GovernanceManaged {
         });
 
         _children[parentNode][lh] = childNode;
-        _childLabels[parentNode].push(lh);
+        // Only index a brand-new child; a reclaim reuses the existing _childLabels entry (no duplicate).
+        if (!reclaiming) _childLabels[parentNode].push(lh);
         _label[childNode] = label;
 
         emit NameRegistered(childNode, parentNode, label, newOwner, resolverContract, expiry);
@@ -352,7 +356,13 @@ contract AgentNameRegistry is GovernanceManaged {
     function parent(bytes32 node) external view returns (bytes32) { return _records[node].parent; }
     function labelhash(bytes32 node) external view returns (bytes32) { return _records[node].labelhash; }
     function expiry(bytes32 node) external view returns (uint64) { return _records[node].expiry; }
-    function recordExists(bytes32 node) external view returns (bool) { return _records[node].registeredAt != 0; }
+    /// @dev M2 (seam audit): an EXPIRED record does NOT exist for read purposes — so the resolver
+    ///      (resolveName/resolveString, which gate on recordExists) and any other reader stop resolving
+    ///      an expired name. Expiry now provides real revocation, not a decorative field. Registry
+    ///      mutators gate on the raw `registeredAt`/`isExpired`, not this, so re-registration is unaffected.
+    function recordExists(bytes32 node) external view returns (bool) {
+        return _records[node].registeredAt != 0 && !isExpired(node);
+    }
     function registeredAt(bytes32 node) external view returns (uint64) { return _records[node].registeredAt; }
 
     function childNode(bytes32 parentNode, bytes32 lh) external view returns (bytes32) {

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);
+}