@agenticprimitives/contracts 1.0.0-alpha.4 → 1.0.0-alpha.5

package/src/AgentAccountFactory.sol

@@ -10,7 +10,7 @@ import "./governance/GovernanceManaged.sol";
 /**
  * @title AgentAccountFactory
  * @notice Single-entry factory for AgentAccount proxies with
- *         deterministic CREATE2 addresses. Phase 6f.5 — collapsed
+ *         deterministic CREATE2 addresses. Phase 6f.5 -- collapsed
  *         createPersonAgent + createMultiSigSmartAgent into one
  *         entry point so every account on chain has the same shape;
  *         the only axis is `mode` on the init params.
@@ -32,7 +32,7 @@ import "./governance/GovernanceManaged.sol";
  *         marker check).
  *
  *         The canonical CustodyPolicy address is wired at construction
- *         (factory-immutable) — there is no per-call validator
+ *         (factory-immutable) -- there is no per-call validator
  *         override. Swapping CustodyPolicy versions means redeploying
  *         the factory, which is the same blast radius as a CREATE2
  *         salt bump.
@@ -41,7 +41,7 @@ import "./governance/GovernanceManaged.sol";
  *   `bundlerSigner` and `sessionIssuer` are factory-level capability
  *   addresses. They are NEVER custodians of any deployed account; each
  *   account reads them off this factory on demand. Phase A.5 made both
- *   mutable under governance — rotation flows through a governance
+ *   mutable under governance -- rotation flows through a governance
  *   proposal + 48h timelock and propagates automatically to every
  *   existing AgentAccount.
  */
@@ -49,6 +49,11 @@ contract AgentAccountFactory is GovernanceManaged {
     AgentAccount public immutable accountImplementation;
     address public immutable delegationManager;
     address public immutable custodyPolicy;
+    /// @dev Spec 253 — the ApprovedHashRegistry baked (immutable) into the
+    ///      AgentAccount impl this factory deploys; surfaced here for
+    ///      deploy-time auditing. The account's `isValidSignature` 0x03
+    ///      sentinel consults it; it is NOT a mutable factory-view.
+    address public immutable approvedHashRegistry;
 
     address public bundlerSigner;
     address public sessionIssuer;
@@ -73,6 +78,21 @@ contract AgentAccountFactory is GovernanceManaged {
     error InsufficientTrusteesForMode(uint8 mode, uint256 actual, uint256 required);
     error TrusteesRequiredForRecoverableMode(uint8 mode);
     error ZeroAddress();
+    /// @notice R9.6 / ATL-SEC-05 -- thrown when `params.custodians.length`
+    ///         exceeds `MAX_INITIAL_CUSTODIANS`. Without this cap,
+    ///         `_buildValidatorInitData` casts `nSigners` to `uint8`
+    ///         and silently truncates at 256, computing a wrong default
+    ///         threshold for a misconfigured account. A self-hurt
+    ///         footgun, not a cross-account vulnerability -- capped so
+    ///         the misconfiguration fails closed at construction.
+    error TooManyInitialCustodians(uint256 actual, uint256 max);
+
+    /// @notice R9.6 / ATL-SEC-05 -- upper bound on initial custodians
+    ///         passed via `AgentAccountInitParams`. 32 is deliberately
+    ///         generous (every smart-account substrate we surveyed
+    ///         caps well below 16) but well under the `uint8` truncation
+    ///         threshold at `_buildValidatorInitData:252`.
+    uint256 public constant MAX_INITIAL_CUSTODIANS = 32;
 
     constructor(
         IEntryPoint entryPoint_,
@@ -80,10 +100,12 @@ contract AgentAccountFactory is GovernanceManaged {
         address custodyPolicy_,
         address bundlerSigner_,
         address sessionIssuer_,
-        address governance_
+        address governance_,
+        address approvedHashRegistry_
     ) GovernanceManaged(governance_) {
         if (custodyPolicy_ == address(0)) revert ZeroAddress();
-        accountImplementation = new AgentAccount(entryPoint_);
+        accountImplementation = new AgentAccount(entryPoint_, approvedHashRegistry_);
+        approvedHashRegistry = approvedHashRegistry_;
         delegationManager = delegationManager_;
         custodyPolicy = custodyPolicy_;
         bundlerSigner = bundlerSigner_;
@@ -219,6 +241,13 @@ contract AgentAccountFactory is GovernanceManaged {
 
         bool hasPasskey = params.initialPasskeyX != 0 && params.initialPasskeyY != 0;
         if (params.custodians.length == 0 && !hasPasskey) revert NoInitialSigner();
+        // R9.6 / ATL-SEC-05: cap the initial custodian set so
+        // `_buildValidatorInitData`'s `uint8(nSigners)` cast can't
+        // silently truncate. 32 is well above any rational config and
+        // well below the uint8 boundary.
+        if (params.custodians.length > MAX_INITIAL_CUSTODIANS) {
+            revert TooManyInitialCustodians(params.custodians.length, MAX_INITIAL_CUSTODIANS);
+        }
 
         if (params.mode == 0) return;
 

package/src/SmartAgentPaymaster.sol

@@ -263,6 +263,8 @@ contract SmartAgentPaymaster is BasePaymaster {
             // EIP-191 wrap matches what KMS-backed `signMessage({raw})`
             // produces via the v0.7 reference paymaster convention.
             bytes32 ethHash = hash.toEthSignedMessageHash();
+            // R6.3: third return (sigVersion) intentionally discarded; the explicit `err` + `recovered != verifyingSigner` revert IS the auth.
+            // slither-disable-next-line unused-return
             (address recovered, ECDSA.RecoverError err, ) = ECDSA.tryRecover(ethHash, signature);
             if (err != ECDSA.RecoverError.NoError || recovered != verifyingSigner) {
                 // Returning sigFailed=true (per EntryPoint convention)

package/src/UniversalSignatureValidator.sol

@@ -125,11 +125,14 @@ contract UniversalSignatureValidator {
     ) private pure returns (bool) {
         if (sig.length != 65) return false;
         // Try raw hash first.
+        // R6.3: third return (sigVersion) intentionally discarded; the `err` + `recovered == signer` is the auth.
+        // slither-disable-next-line unused-return
         (address recovered, ECDSA.RecoverError err, ) = ECDSA.tryRecover(hash, sig);
         if (err == ECDSA.RecoverError.NoError && recovered == signer) return true;
         // Then try the eth-signed prefix variant — many wallets sign this
         // form even when the caller passes a raw digest.
         bytes32 prefixed = hash.toEthSignedMessageHash();
+        // slither-disable-next-line unused-return
         (recovered, err, ) = ECDSA.tryRecover(prefixed, sig);
         return err == ECDSA.RecoverError.NoError && recovered == signer;
     }

package/src/agency/DelegationManager.sol

@@ -86,6 +86,11 @@ contract DelegationManager is IDelegationManager, ReentrancyGuard {
         "Caveat(address enforcer,bytes terms)"
     );
 
+    /// @dev Gas cap for the read-only caveat evaluation in `verifyAuthorizationForCall`.
+    ///      Generous for any pure/view enforcer; bounds the gas a stateful enforcer would
+    ///      burn before reverting under staticcall, so on-chain callers get a cheap `false`.
+    uint256 private constant CAVEAT_VIEW_GAS = 1_000_000;
+
     /// @dev Revoked delegation hashes
     mapping(bytes32 => bool) private _revoked;
 
@@ -242,6 +247,156 @@ contract DelegationManager is IDelegationManager, ReentrancyGuard {
         return keccak256(abi.encodePacked("\x19\x01", DOMAIN_SEPARATOR, structHash));
     }
 
+    /// @notice View-only verification of a delegation chain. Returns whether
+    ///         the chain is well-formed (signatures, authority chain, not
+    ///         revoked) WITHOUT executing it.
+    ///
+    /// Spec 242 §6 (PD-9): the `attestations` package uses this to verify
+    /// bilateral-consent delegations as signed authorization predicates,
+    /// rather than redeeming them as cross-account execution. Returning
+    /// `(true, "")` means the delegation chain authorizes the named call from
+    /// `sender`. Caveat predicates (CalldataHashEnforcer, AllowedTargets,
+    /// AllowedMethods, Timestamp) are NOT executed here — callers are expected
+    /// to pin those into the delegation's caveats at issuance time, where
+    /// they're hash-bound to the delegation signature.
+    ///
+    /// @param delegations Chain (leaf first; root authority last)
+    /// @param sender The address that would be the redeemer
+    /// @return ok True if every link verifies
+    /// @return reason Empty if ok; otherwise a short rejection reason
+    function verifyAuthorization(
+        Delegation[] calldata delegations,
+        address sender
+    ) external view returns (bool ok, string memory reason) {
+        if (delegations.length == 0) return (false, "empty-chain");
+
+        for (uint256 i = 0; i < delegations.length; i++) {
+            (bool valid, string memory r) = _validateDelegationView(delegations, i, sender);
+            if (!valid) return (false, r);
+        }
+        return (true, "");
+    }
+
+    /// @notice View verifier for a SPECIFIC call (ADR-0027 / spec 249, RW1-4). Validates the
+    ///         delegation chain AND evaluates every caveat's `beforeHook` against the exact
+    ///         `(target, value, data)` — read-only, FAIL-CLOSED.
+    /// @dev    `verifyAuthorization` checks chain/signature/authority/revocation but NOT the
+    ///         caveats — too weak to authorize a specific call. This evaluates each caveat via
+    ///         `staticcall` (the hook is `external`/non-view because stateful enforcers like
+    ///         Quorum exist). Returns `true` ONLY if the chain validates and EVERY caveat passes
+    ///         read-only. A caveat that reverts (denied) OR cannot be evaluated read-only (a
+    ///         stateful enforcer attempting a write under staticcall) yields `false` — so `true`
+    ///         is a genuine authorization guarantee for this exact call, and `false` means "use
+    ///         live redemption" (which evaluates stateful caveats properly). The caveat
+    ///         evaluation mirrors `_runBeforeHooks` exactly (same args, same `sender`-as-redeemer),
+    ///         so an unknown/no-code enforcer is a no-op here just as it is in redemption. Pure
+    ///         addition — `redeemDelegation` is untouched.
+    /// @param delegations Chain (leaf first; root authority last)
+    /// @param sender The address that would be the redeemer
+    /// @param target The exact target the delegated call would hit
+    /// @param value The exact ETH value
+    /// @param data The exact calldata
+    function verifyAuthorizationForCall(
+        Delegation[] calldata delegations,
+        address sender,
+        address target,
+        uint256 value,
+        bytes calldata data
+    ) external view returns (bool ok, string memory reason) {
+        if (delegations.length == 0) return (false, "empty-chain");
+
+        for (uint256 i = 0; i < delegations.length; i++) {
+            (bool valid, string memory r) = _validateDelegationView(delegations, i, sender);
+            if (!valid) return (false, r);
+
+            Delegation calldata d = delegations[i];
+            bytes32 dHash = hashDelegation(d);
+            for (uint256 j = 0; j < d.caveats.length; j++) {
+                // staticcall the same hook redemption would call; success == satisfied read-only.
+                // Gas-bounded: a stateful enforcer (which would revert on its SSTORE under
+                // staticcall) is capped so an on-chain caller (e.g. RW1-1) sees a cheap, predictable
+                // `false`, not an out-of-gas of the whole call. CAVEAT_VIEW_GAS is generous for any
+                // pure/view enforcer (timestamp/value/targets/methods are all far below it).
+                (bool passed, ) = d.caveats[j].enforcer.staticcall{gas: CAVEAT_VIEW_GAS}(
+                    abi.encodeWithSelector(
+                        ICaveatEnforcer.beforeHook.selector,
+                        d.caveats[j].terms,
+                        d.caveats[j].args,
+                        dHash,
+                        d.delegator,
+                        sender,
+                        target,
+                        value,
+                        data
+                    )
+                );
+                if (!passed) return (false, "caveat-failed");
+            }
+        }
+        return (true, "");
+    }
+
+    /// @dev View-only sibling of `_validateDelegation`. Same checks, no state
+    ///      writes, no events. Used by `verifyAuthorization`.
+    function _validateDelegationView(
+        Delegation[] calldata delegations,
+        uint256 i,
+        address sender
+    ) internal view returns (bool ok, string memory reason) {
+        Delegation calldata d = delegations[i];
+        bytes32 dHash = hashDelegation(d);
+
+        if (_revoked[dHash]) return (false, "revoked");
+
+        // Delegate chain
+        if (i == 0) {
+            if (d.delegate != OPEN_DELEGATION && d.delegate != sender) {
+                return (false, "invalid-delegate");
+            }
+        } else {
+            if (d.delegate != OPEN_DELEGATION && d.delegate != delegations[i - 1].delegator) {
+                return (false, "invalid-delegate-chain");
+            }
+        }
+
+        // Authority chain
+        if (d.authority != ROOT_AUTHORITY) {
+            if (i + 1 >= delegations.length) return (false, "invalid-authority");
+            bytes32 parentHash = hashDelegation(delegations[i + 1]);
+            if (d.authority != parentHash) return (false, "invalid-authority-chain");
+        }
+
+        // Signature
+        if (!_isValidSignatureBool(d.delegator, dHash, d.signature)) {
+            return (false, "invalid-signature");
+        }
+
+        return (true, "");
+    }
+
+    /// @dev Bool-returning sibling of `_validateSignature`. Returns false
+    ///      instead of reverting, so view-only callers can produce a typed
+    ///      `(ok, reason)` instead of bubbling a revert.
+    function _isValidSignatureBool(
+        address signer,
+        bytes32 digest,
+        bytes calldata signature
+    ) internal view returns (bool) {
+        // ERC-1271 path for smart accounts
+        if (signer.code.length > 0) {
+            try IERC1271(signer).isValidSignature(digest, signature) returns (bytes4 result) {
+                return result == IERC1271.isValidSignature.selector;
+            } catch {
+                return false;
+            }
+        }
+        // EOA — tryRecover the eth-signed message hash
+        bytes32 ethHash = digest.toEthSignedMessageHash();
+        (address recovered, ECDSA.RecoverError err, ) = ECDSA.tryRecover(ethHash, signature);
+        if (err != ECDSA.RecoverError.NoError) return false;
+        return recovered == signer;
+    }
+
     // ─── Internal: Validation ──────────────────────────────────────────
 
     function _validateDelegation(

package/src/agency/IDelegationManager.sol

@@ -66,4 +66,39 @@ interface IDelegationManager {
 
     /// @notice Check if a delegation has been revoked.
     function isRevoked(bytes32 delegationHash) external view returns (bool);
+
+    /// @notice View-only verification of a delegation chain. Returns whether
+    ///         the chain authorizes `sender` to redeem WITHOUT executing it.
+    ///         Used by trust-substrate contracts (e.g. AttestationRegistry's
+    ///         bilateral-consent path per spec 242 PD-9) to validate a packed
+    ///         delegation as a signed authorization predicate.
+    /// @param delegations Delegation chain, leaf first
+    /// @param sender The address that would be the redeemer
+    /// @return ok True if the chain verifies
+    /// @return reason Empty if ok; otherwise short rejection reason
+    function verifyAuthorization(
+        Delegation[] calldata delegations,
+        address sender
+    ) external view returns (bool ok, string memory reason);
+
+    /// @notice View-only authorization of a SPECIFIC call (ADR-0027 / spec 249 RW1-4):
+    ///         validates the chain AND evaluates every caveat's `beforeHook` against the exact
+    ///         `(target, value, data)` read-only, fail-closed. `true` ONLY if the chain validates
+    ///         and every caveat passes under `staticcall`; a denied OR non-view-evaluable caveat
+    ///         yields `false` ("use live redemption"). Lets a registry bind consent to the exact
+    ///         call inside its own transaction. Caveat evaluation mirrors `redeemDelegation`.
+    /// @param delegations Delegation chain, leaf first
+    /// @param sender The address that would be the redeemer
+    /// @param target The exact target of the delegated call
+    /// @param value The exact ETH value
+    /// @param data The exact calldata
+    /// @return ok True if the chain + every caveat authorize this exact call
+    /// @return reason Empty if ok; otherwise short rejection reason
+    function verifyAuthorizationForCall(
+        Delegation[] calldata delegations,
+        address sender,
+        address target,
+        uint256 value,
+        bytes calldata data
+    ) external view returns (bool ok, string memory reason);
 }

package/src/agreement/AgreementRegistry.sol

@@ -0,0 +1,306 @@
+// SPDX-License-Identifier: MIT
+pragma solidity ^0.8.28;
+
+import "@openzeppelin/contracts/interfaces/IERC1271.sol";
+
+/**
+ * @title AgreementRegistry
+ * @notice Commitment-only registry per spec 241 + ADR-0024 Decision 2.
+ *
+ *   ─── Substrate role ───
+ *
+ * Layer 8 of the coordination spine — Agreement / Commitment. Stores the
+ * commitment HASH only (no agreement bodies, no party SAs). Bodies live in
+ * party Joint Vaults; party SAs surface only through joint assertions
+ * registered in the AttestationRegistry (which references our `commitmentHash`).
+ *
+ *   ─── Key invariants (AR-*) ───
+ *
+ * AR-01 register() recomputes the commitment from supplied components
+ * AR-02 issuer EIP-712 attestation verified via ERC-1271
+ * AR-03 schema validated against (off-chain) ShapeRegistry
+ * AR-04 status state-machine: ACTIVE → COMPLETED | DISPUTED | REVOKED
+ * AR-05 bilateral signing required for ACTIVE→COMPLETED, ACTIVE→REVOKED
+ * AR-06 either-party for ACTIVE→DISPUTED
+ * AR-07 NO issuerRevoke / issuerStatusUpdate entrypoint — by static analysis
+ * AR-08 nullifier set prevents replay on status transitions
+ * AR-09 epoch-bucket timestamps; raw block.timestamp never stored
+ * AR-10 isAssertableCommitment view gateway for AttestationRegistry
+ * AR-11 party SA addresses NEVER appear in register() calldata
+ * AR-12 single on-chain row per agreement (D-37)
+ */
+contract AgreementRegistry {
+    // ─── Constants ──────────────────────────────────────────────────────
+
+    uint64 public constant EPOCH_SECONDS = 3600;
+
+    uint8 public constant STATUS_NONE = 0;
+    uint8 public constant STATUS_ACTIVE = 1;
+    uint8 public constant STATUS_COMPLETED = 2;
+    uint8 public constant STATUS_DISPUTED = 3;
+    uint8 public constant STATUS_REVOKED = 4;
+
+    /// @dev RW1-3 (ADR-0027): the contract RECOMPUTES the transition digest the
+    ///      parties sign from (agreementCommitment, toStatus, nullifier) — it no
+    ///      longer trusts a caller-supplied `transitionStructHash`. One canonical
+    ///      digest model; the TS side derives the same constant (cross-stack
+    ///      typehash-equality gate). Plain struct hash (no domain separator),
+    ///      matching the attestation registry's JOINT_CONSENT_TYPEHASH.
+    bytes32 internal constant TRANSITION_TYPEHASH =
+        keccak256("AgreementTransition(bytes32 agreementCommitment,uint8 toStatus,bytes32 nullifier)");
+
+    // ─── Errors ─────────────────────────────────────────────────────────
+
+    error AlreadyRegistered();
+    error NotRegistered();
+    error InvalidStatus();
+    error InvalidIssuerSignature();
+    error InvalidTransitionSignature();
+    error NullifierUsed();
+    error CommitmentMismatch();
+    error SignerNotParty();
+
+    // ─── Storage ────────────────────────────────────────────────────────
+
+    struct AgreementRow {
+        bytes32 agreementCommitment; // canonical commitment hash
+        bytes32 schemaHash; // SHACL shape hash from ShapeRegistry
+        address issuer; // SA whose EIP-712 attestation backs the commitment
+        uint8 status;
+        uint64 createdEpochBucket;
+        uint64 lastTransitionEpochBucket;
+    }
+
+    /// @dev key = agreementCommitment hash
+    mapping(bytes32 => AgreementRow) private _rows;
+
+    /// @dev AR-08: nullifier set for replay protection on status transitions.
+    mapping(bytes32 => bool) private _nullifiers;
+
+    // ─── Requests ───────────────────────────────────────────────────────
+
+    /// @notice The components the contract recomputes the commitment from
+    ///         (per spec 241 §3). Party SAs are intentionally NOT in this
+    ///         payload — AR-11.
+    struct AgreementIssuancePayload {
+        bytes32 schemaHash;
+        address issuer;
+        /// @dev EIP-712 attestation hash by the issuer (over agreementCommitment + schemaHash).
+        bytes32 attestationStructHash;
+        /// @dev issuer's signature over `attestationStructHash`.
+        bytes issuerSignature;
+        /// @dev The asserted canonical commitment hash; we verify recomputation.
+        bytes32 agreementCommitment;
+        /// @dev Component commitments for AR-01 recomputation:
+        ///      keccak256(partySet, issuerCommitment, termsCommitment, scheduleCommitment, salt) == agreementCommitment
+        bytes32 partySetCommitment;
+        bytes32 issuerCommitment;
+        bytes32 termsCommitment;
+        bytes32 scheduleCommitment;
+        uint256 salt;
+    }
+
+    struct StatusUpdatePayload {
+        bytes32 agreementCommitment;
+        uint8 toStatus;
+        bytes32 nullifier;
+        /// @dev Signatures over the RECOMPUTED transition digest (RW1-3): 1 for
+        ///      either-party (DISPUTED), 2 for bilateral (COMPLETED/REVOKED).
+        bytes signature1;
+        bytes signature2;
+        /// @dev Party SAs that signed. For DISPUTED: signer1 only. For COMPLETED/REVOKED: both.
+        address signer1;
+        address signer2;
+        /// @dev RW1-2 (ADR-0027): the agreement's parties + commitment components, REVEALED at
+        ///      transition time so the contract can recompute the commitment and PROVE the signers
+        ///      are the parties. (Registration stays commitment-only — AR-12; the transition is
+        ///      already a public state change that names its signers.)
+        address party1;
+        address party2;
+        bytes32 issuerCommitment;
+        bytes32 termsCommitment;
+        bytes32 scheduleCommitment;
+        uint256 commitmentSalt;
+    }
+
+    // ─── Events ─────────────────────────────────────────────────────────
+
+    event AgreementRegistered(
+        bytes32 indexed agreementCommitment,
+        address indexed issuer,
+        bytes32 indexed schemaHash,
+        uint64 epochBucket
+    );
+
+    event StatusUpdated(
+        bytes32 indexed agreementCommitment,
+        uint8 indexed fromStatus,
+        uint8 indexed toStatus,
+        uint64 epochBucket
+    );
+
+    // ─── Public surface ─────────────────────────────────────────────────
+
+    /// @notice Register an agreement by its commitment hash.
+    function register(AgreementIssuancePayload calldata p) external returns (bytes32) {
+        // AR-01 — recompute commitment from components
+        bytes32 recomputed = keccak256(
+            abi.encode(p.partySetCommitment, p.issuerCommitment, p.termsCommitment, p.scheduleCommitment, p.salt)
+        );
+        if (recomputed != p.agreementCommitment) revert CommitmentMismatch();
+
+        if (_rows[p.agreementCommitment].agreementCommitment != bytes32(0)) {
+            revert AlreadyRegistered();
+        }
+
+        // AR-02 — verify issuer signature over the attestation hash
+        if (!_isValidSignatureBool(p.issuer, p.attestationStructHash, p.issuerSignature)) {
+            revert InvalidIssuerSignature();
+        }
+
+        uint64 bucket = uint64(block.timestamp) / EPOCH_SECONDS;
+
+        _rows[p.agreementCommitment] = AgreementRow({
+            agreementCommitment: p.agreementCommitment,
+            schemaHash: p.schemaHash,
+            issuer: p.issuer,
+            status: STATUS_ACTIVE,
+            createdEpochBucket: bucket,
+            lastTransitionEpochBucket: bucket
+        });
+
+        emit AgreementRegistered(p.agreementCommitment, p.issuer, p.schemaHash, bucket);
+        return p.agreementCommitment;
+    }
+
+    /// @notice Update the agreement status. Signing requirements (AR-04..AR-06):
+    ///         - DISPUTED: signer1 (either party) only
+    ///         - COMPLETED / REVOKED: both signer1 + signer2 (bilateral)
+    ///         RW1-2 (ADR-0027): the caller REVEALS the parties + commitment
+    ///         components; the contract recomputes the commitment (register's
+    ///         exact formula) and requires each signer to BE one of the two
+    ///         parties. The on-chain row still stores NO party SAs (AR-11 covers
+    ///         register() calldata only); the parties surface here because a
+    ///         status transition is already a public state change that names its
+    ///         signers. Replay protection comes from the nullifier. RW1-3: the
+    ///         transition digest the parties sign is RECOMPUTED here from
+    ///         (agreementCommitment, toStatus, nullifier) — not caller-supplied.
+    function updateStatus(StatusUpdatePayload calldata p) external {
+        AgreementRow storage row = _rows[p.agreementCommitment];
+        if (row.agreementCommitment == bytes32(0)) revert NotRegistered();
+
+        // Status transition validity (AR-04)
+        if (row.status != STATUS_ACTIVE && row.status != STATUS_DISPUTED) revert InvalidStatus();
+        if (
+            p.toStatus != STATUS_COMPLETED &&
+            p.toStatus != STATUS_DISPUTED &&
+            p.toStatus != STATUS_REVOKED
+        ) {
+            revert InvalidStatus();
+        }
+        // DISPUTED → COMPLETED / REVOKED needs bilateral.
+        // ACTIVE → DISPUTED: either-party allowed.
+        // ACTIVE → COMPLETED / REVOKED: bilateral.
+
+        // AR-08 — replay protection
+        if (_nullifiers[p.nullifier]) revert NullifierUsed();
+        _nullifiers[p.nullifier] = true;
+
+        // RW1-2 (ADR-0027): PROVE the signers are the agreement's parties. Recompute the agreement
+        // commitment from the REVEALED parties + components (register's exact formula) and require it
+        // to equal the row's commitment; then require each signer to BE a party. The caller-supplied
+        // signer set is no longer trusted (a nonzero commitment ref / arbitrary signer is not authority).
+        {
+            bytes32 partySet = keccak256(abi.encodePacked(p.party1, p.party2));
+            bytes32 recomputed = keccak256(
+                abi.encode(partySet, p.issuerCommitment, p.termsCommitment, p.scheduleCommitment, p.commitmentSalt)
+            );
+            if (recomputed != p.agreementCommitment) revert CommitmentMismatch();
+        }
+
+        // RW1-3 (ADR-0027): RECOMPUTE the transition digest the parties sign — do not trust a
+        // caller-supplied hash. The signed payload is canonically bound to (commitment, toStatus,
+        // nullifier) here, on chain.
+        bytes32 transitionDigest = keccak256(
+            abi.encode(TRANSITION_TYPEHASH, p.agreementCommitment, p.toStatus, p.nullifier)
+        );
+
+        bool bilateralRequired = (p.toStatus != STATUS_DISPUTED);
+
+        // signer1 must BE a party, and must have signed.
+        if (p.signer1 != p.party1 && p.signer1 != p.party2) revert SignerNotParty();
+        if (!_isValidSignatureBool(p.signer1, transitionDigest, p.signature1)) {
+            revert InvalidTransitionSignature();
+        }
+        if (bilateralRequired) {
+            // both DISTINCT parties must sign.
+            if (p.signer2 == address(0) || p.signer2 == p.signer1) revert InvalidTransitionSignature();
+            if (p.signer2 != p.party1 && p.signer2 != p.party2) revert SignerNotParty();
+            if (!_isValidSignatureBool(p.signer2, transitionDigest, p.signature2)) {
+                revert InvalidTransitionSignature();
+            }
+        }
+
+        uint8 fromStatus = row.status;
+        row.status = p.toStatus;
+        row.lastTransitionEpochBucket = uint64(block.timestamp) / EPOCH_SECONDS;
+
+        emit StatusUpdated(p.agreementCommitment, fromStatus, p.toStatus, row.lastTransitionEpochBucket);
+    }
+
+    /// @notice Gateway for spec 242 AttestationRegistry.assertJointAgreement.
+    ///         Returns (true, "") if the commitment exists and is in a state
+    ///         that permits public joint assertion (currently any non-NONE
+    ///         status; revoked agreements can still be jointly disclosed as
+    ///         historical record).
+    function isAssertableCommitment(
+        bytes32 agreementCommitment,
+        address /* actor */
+    ) external view returns (bool ok, string memory reason) {
+        AgreementRow memory row = _rows[agreementCommitment];
+        if (row.agreementCommitment == bytes32(0)) return (false, "not-registered");
+        return (true, "");
+    }
+
+    /// @notice Get the on-chain row.
+    function getRecord(bytes32 agreementCommitment) external view returns (AgreementRow memory) {
+        AgreementRow memory row = _rows[agreementCommitment];
+        if (row.agreementCommitment == bytes32(0)) revert NotRegistered();
+        return row;
+    }
+
+    /// @notice Has a nullifier been consumed?
+    function isNullifierUsed(bytes32 n) external view returns (bool) {
+        return _nullifiers[n];
+    }
+
+    // ─── Internal ───────────────────────────────────────────────────────
+
+    function _isValidSignatureBool(
+        address signer,
+        bytes32 digest,
+        bytes memory signature
+    ) internal view returns (bool) {
+        if (signer.code.length > 0) {
+            try IERC1271(signer).isValidSignature(digest, signature) returns (bytes4 result) {
+                return result == IERC1271.isValidSignature.selector;
+            } catch {
+                return false;
+            }
+        }
+        bytes32 ethHash = keccak256(abi.encodePacked("\x19Ethereum Signed Message:\n32", digest));
+        if (signature.length != 65) return false;
+        bytes32 r;
+        bytes32 s;
+        uint8 v;
+        // solhint-disable-next-line no-inline-assembly
+        assembly {
+            r := mload(add(signature, 0x20))
+            s := mload(add(signature, 0x40))
+            v := byte(0, mload(add(signature, 0x60)))
+        }
+        if (v < 27) v += 27;
+        address recovered = ecrecover(ethHash, v, r, s);
+        return recovered != address(0) && recovered == signer;
+    }
+}