@agenticprimitives/contracts 0.1.0-alpha.3 → 1.0.0-alpha.5

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

package/src/attestation/AttestationRegistry.sol

@@ -0,0 +1,320 @@
+// SPDX-License-Identifier: MIT
+pragma solidity ^0.8.28;
+
+import "@openzeppelin/contracts/interfaces/IERC1271.sol";
+
+/**
+ * @title AttestationRegistry
+ * @notice EAS-aligned, bilateral-consent attestation registry per ADR-0023.
+ *
+ *   ─── Substrate role ───
+ *
+ * Layers 12-15 of the coordination spine (Evidence / Outcome / Validation /
+ * TrustUpdate) plus the substrate's Association + JointAgreement attestations
+ * all share THIS one contract. Per ADR-0024 Decision 2 — the architectural
+ * inverse of the smart-contract-per-credential anti-pattern.
+ *
+ *   ─── Key invariants (AR-*) ───
+ *
+ * AR-01 deterministic UID = keccak256(subject, issuer, credentialType, credentialHash, refUID, salt)
+ * AR-02 issuer signature verified via ERC-1271 against the named issuer SA
+ * AR-03 schemaId MUST point to a registered ShapeRegistry shape (governance-gated)
+ * AR-04 bilateral-consent verified via DelegationManager.verifyAuthorization
+ * AR-05 holder-only revocation for unilateral; either-party for joint
+ * AR-06 NO issuerRevoke(...) entrypoint — by static analysis
+ * AR-07 epoch-bucket timestamps; raw block.timestamp never stored
+ * AR-08 four indexed event topics (EAS-like)
+ * AR-09 immutable + non-upgradeable; no admin
+ *
+ * Spec 242 §9 + ADR-0023.
+ */
+contract AttestationRegistry {
+    // ─── Constants ──────────────────────────────────────────────────────
+
+    uint64 public constant EPOCH_SECONDS = 3600;
+
+    // ─── Errors ─────────────────────────────────────────────────────────
+
+    error InvalidIssuerSignature();
+    error AttestationAlreadyExists();
+    error AttestationNotFound();
+    error NotSubject();
+    error NotParty();
+    error AlreadyRevoked();
+    error InvalidParties();
+    error InvalidPartyConsent();
+    error EmptyCredentialHash();
+
+    /// @dev RW1-1 (ADR-0027) — the canonical consent payload each party signs to consent to a
+    ///      joint agreement. The contract RECOMPUTES this digest from calldata; a stored/supplied
+    ///      reference is not consent. Binds the consent to the exact parties + agreement + credential.
+    bytes32 internal constant JOINT_CONSENT_TYPEHASH = keccak256(
+        "JointAgreementConsent(address party1,address party2,bytes32 agreementCommitment,bytes32 credentialHash)"
+    );
+
+    // ─── Storage ────────────────────────────────────────────────────────
+
+    /// @notice The canonical attestation row. EAS-aligned shape.
+    struct Attestation {
+        bytes32 uid;
+        bytes32 schemaId; // → ShapeRegistry row
+        bytes32 credentialType; // VC type class
+        bytes32 credentialHash; // RFC 8785 JCS hash of off-chain VC body
+        bytes32 refUID; // EAS-style back-pointer (e.g. AgreementCommitment for JointAgreement)
+        bytes32 bilateralConsentRef; // 0 for unilateral; hash for joint
+        bytes32 offchainCredentialStatusList; // W3C VC StatusList2021 pointer
+        uint64 epochBucket; // attest time / EPOCH_SECONDS
+        uint64 revocationEpochBucket; // 0 if not revoked
+        address subject; // holder (unilateral) or party[0] (joint)
+        address party2; // address(0) for unilateral; party[1] for joint
+        address issuer; // off-chain VC signer SA
+    }
+
+    mapping(bytes32 => Attestation) private _attestations;
+
+    // ─── Requests ───────────────────────────────────────────────────────
+
+    struct AssociationAttestationRequest {
+        bytes32 schemaId;
+        bytes32 credentialType;
+        bytes32 credentialHash;
+        bytes32 offchainCredentialStatusList;
+        address subject;
+        address issuer;
+        /// @dev EIP-712 signature by `issuer` SA over the credentialHash;
+        ///      verified via ERC-1271.
+        bytes issuerSignature;
+        uint256 salt;
+    }
+
+    struct JointAgreementAttestationRequest {
+        bytes32 schemaId;
+        bytes32 credentialType;
+        bytes32 credentialHash;
+        bytes32 refUID; // AgreementCommitment hash (spec 241)
+        bytes32 bilateralConsentRef; // DEPRECATED / IGNORED (RW1-1, ADR-0027): consent is now
+            // VERIFIED on-chain from party1Signature + party2Signature over the RECOMPUTED
+            // consent digest; the stored `bilateralConsentRef` is that recomputed digest, not this.
+        bytes32 offchainCredentialStatusList;
+        address party1;
+        address party2;
+        address issuer;
+        bytes issuerSignature;
+        bytes party1Signature; // RW1-1: party1's consent over JOINT_CONSENT_TYPEHASH digest
+        bytes party2Signature; // RW1-1: party2's consent over JOINT_CONSENT_TYPEHASH digest
+        uint256 salt;
+    }
+
+    // ─── Events (EAS-like; 4 indexed topics each) ───────────────────────
+
+    /// @dev Solidity caps indexed-args at 3 per non-anonymous event (EVM
+    ///      topic0 = event signature). Matches EAS event shape:
+    ///      `uid` is non-indexed payload; subject + issuer + credentialType
+    ///      are indexed for filtering.
+    event Attested(
+        address indexed subject,
+        address indexed issuer,
+        bytes32 indexed credentialType,
+        bytes32 uid
+    );
+
+    event JointAttested(
+        address indexed party1,
+        address indexed party2,
+        bytes32 indexed credentialType,
+        bytes32 uid
+    );
+
+    event Revoked(
+        address indexed subjectOrParty,
+        bytes32 indexed credentialType,
+        bytes32 uid,
+        bytes32 reasonHash
+    );
+
+    // ─── Public surface ─────────────────────────────────────────────────
+
+    /// @notice Unilateral attestation by a holder against an issued credential.
+    function assertAssociation(AssociationAttestationRequest calldata req) external returns (bytes32) {
+        if (req.credentialHash == bytes32(0)) revert EmptyCredentialHash();
+
+        // AR-02: verify issuer signature over credentialHash
+        if (!_isValidSignatureBool(req.issuer, req.credentialHash, req.issuerSignature)) {
+            revert InvalidIssuerSignature();
+        }
+
+        bytes32 uid = _computeUid(
+            req.subject,
+            address(0),
+            req.issuer,
+            req.credentialType,
+            req.credentialHash,
+            bytes32(0),
+            req.salt
+        );
+
+        if (_attestations[uid].uid != bytes32(0)) revert AttestationAlreadyExists();
+
+        uint64 bucket = uint64(block.timestamp) / EPOCH_SECONDS;
+
+        _attestations[uid] = Attestation({
+            uid: uid,
+            schemaId: req.schemaId,
+            credentialType: req.credentialType,
+            credentialHash: req.credentialHash,
+            refUID: bytes32(0),
+            bilateralConsentRef: bytes32(0),
+            offchainCredentialStatusList: req.offchainCredentialStatusList,
+            epochBucket: bucket,
+            revocationEpochBucket: 0,
+            subject: req.subject,
+            party2: address(0),
+            issuer: req.issuer
+        });
+
+        emit Attested(req.subject, req.issuer, req.credentialType, uid);
+        return uid;
+    }
+
+    /// @notice Joint attestation by two parties against an agreement.
+    /// @dev RW1-1 (ADR-0027) — bilateral consent is VERIFIED on-chain, not trusted. The contract
+    ///      recomputes the canonical consent digest (`JOINT_CONSENT_TYPEHASH` over party1, party2,
+    ///      the agreement commitment, and the credential hash) and requires BOTH parties' signatures
+    ///      over it (ERC-1271 for smart accounts, ECDSA for EOAs). A nonzero `bilateralConsentRef` is
+    ///      NOT consent (the prior "caller's responsibility" model, AR-04). The recomputed digest is
+    ///      what gets stored. Alternative consent proof via `DelegationManager.verifyAuthorizationForCall`
+    ///      (an exact-call sub-delegation per party) is spec 249's option (b); this entrypoint takes
+    ///      the direct two-party-signature form.
+    function assertJointAgreement(
+        JointAgreementAttestationRequest calldata req
+    ) external returns (bytes32) {
+        if (req.credentialHash == bytes32(0)) revert EmptyCredentialHash();
+        if (req.party1 == address(0) || req.party2 == address(0)) revert InvalidParties();
+        if (req.party1 == req.party2) revert InvalidParties();
+
+        if (!_isValidSignatureBool(req.issuer, req.credentialHash, req.issuerSignature)) {
+            revert InvalidIssuerSignature();
+        }
+
+        // VERIFY bilateral consent: recompute the digest, require both parties' signatures over it.
+        bytes32 consentDigest = keccak256(
+            abi.encode(JOINT_CONSENT_TYPEHASH, req.party1, req.party2, req.refUID, req.credentialHash)
+        );
+        if (!_isValidSignatureBool(req.party1, consentDigest, req.party1Signature)) revert InvalidPartyConsent();
+        if (!_isValidSignatureBool(req.party2, consentDigest, req.party2Signature)) revert InvalidPartyConsent();
+
+        bytes32 uid = _computeUid(
+            req.party1,
+            req.party2,
+            req.issuer,
+            req.credentialType,
+            req.credentialHash,
+            req.refUID,
+            req.salt
+        );
+        if (_attestations[uid].uid != bytes32(0)) revert AttestationAlreadyExists();
+
+        uint64 bucket = uint64(block.timestamp) / EPOCH_SECONDS;
+
+        _attestations[uid] = Attestation({
+            uid: uid,
+            schemaId: req.schemaId,
+            credentialType: req.credentialType,
+            credentialHash: req.credentialHash,
+            refUID: req.refUID,
+            bilateralConsentRef: consentDigest, // the VERIFIED, recomputed consent digest (RW1-1)
+            offchainCredentialStatusList: req.offchainCredentialStatusList,
+            epochBucket: bucket,
+            revocationEpochBucket: 0,
+            subject: req.party1,
+            party2: req.party2,
+            issuer: req.issuer
+        });
+
+        emit JointAttested(req.party1, req.party2, req.credentialType, uid);
+        return uid;
+    }
+
+    /// @notice Holder-only revocation for unilateral attestations (AR-05).
+    function revokeOwnAssociation(bytes32 uid, bytes32 reasonHash) external {
+        Attestation storage a = _attestations[uid];
+        if (a.uid == bytes32(0)) revert AttestationNotFound();
+        if (a.party2 != address(0)) revert NotSubject(); // joint — wrong entrypoint
+        if (msg.sender != a.subject) revert NotSubject();
+        if (a.revocationEpochBucket != 0) revert AlreadyRevoked();
+
+        a.revocationEpochBucket = uint64(block.timestamp) / EPOCH_SECONDS;
+        emit Revoked(msg.sender, a.credentialType, uid, reasonHash);
+    }
+
+    /// @notice Either-party revocation for joint attestations (D-26 + AR-05).
+    function revokeOwnJointAgreement(bytes32 uid, bytes32 reasonHash) external {
+        Attestation storage a = _attestations[uid];
+        if (a.uid == bytes32(0)) revert AttestationNotFound();
+        if (a.party2 == address(0)) revert NotParty(); // unilateral — wrong entrypoint
+        if (msg.sender != a.subject && msg.sender != a.party2) revert NotParty();
+        if (a.revocationEpochBucket != 0) revert AlreadyRevoked();
+
+        a.revocationEpochBucket = uint64(block.timestamp) / EPOCH_SECONDS;
+        emit Revoked(msg.sender, a.credentialType, uid, reasonHash);
+    }
+
+    /// @notice Get the full attestation row.
+    function getAttestation(bytes32 uid) external view returns (Attestation memory) {
+        Attestation memory a = _attestations[uid];
+        if (a.uid == bytes32(0)) revert AttestationNotFound();
+        return a;
+    }
+
+    /// @notice Convenience — `!revoked` view.
+    function isValid(bytes32 uid) external view returns (bool) {
+        return _attestations[uid].uid != bytes32(0) && _attestations[uid].revocationEpochBucket == 0;
+    }
+
+    // ─── Internal ───────────────────────────────────────────────────────
+
+    function _computeUid(
+        address subject,
+        address party2,
+        address issuer,
+        bytes32 credentialType,
+        bytes32 credentialHash,
+        bytes32 refUID,
+        uint256 salt
+    ) internal pure returns (bytes32) {
+        return
+            keccak256(
+                abi.encode(subject, party2, issuer, credentialType, credentialHash, refUID, salt)
+            );
+    }
+
+    /// @dev ERC-1271-first signature verification (smart accounts), with EOA fallback.
+    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;
+            }
+        }
+        // EOA fallback via eth-signed message hash + ecrecover
+        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;
+    }
+}