@agenticprimitives/contracts 0.1.0-alpha.2

package/src/ontology/AttributeStorage.sol

@@ -0,0 +1,289 @@
+// SPDX-License-Identifier: MIT
+pragma solidity ^0.8.28;
+
+import "./OntologyTermRegistry.sol";
+
+/**
+ * @title AttributeStorage
+ * @notice Abstract base for typed, ontology-governed attribute storage.
+ *         Each contract that inherits gets its OWN copy of the mappings
+ *         (no shared backend). Subclasses choose their auth model; the
+ *         setters are `internal` so the subclass enforces preconditions.
+ *
+ * Eight typed value families, identified by `uint8` datatype
+ * discriminators:
+ *   1 string, 2 address, 3 bool, 4 uint256,
+ *   5 bytes32, 6 string[], 7 address[], 8 bytes32[]
+ *
+ * Predicate enumeration: `predicatesOf(subject)` returns the list of
+ * predicates ever set on a subject (insertion order, no duplicates).
+ * `subjectVersion(subject)` is bumped on every write — off-chain syncs
+ * (RDF mirrors, indexers) use it as a watermark for diff-aware emission.
+ *
+ * Predicate governance: every internal setter checks the predicate is
+ * ACTIVE in the bound `ONTOLOGY` (an OntologyTermRegistry instance
+ * passed at construction). Bypass-the-SDK writes with unknown
+ * predicates revert at the chain edge.
+ *
+ * Adapted from smart-agent
+ * (`packages/contracts/src/AttributeStorage.sol`, 283 LOC) —
+ * structurally identical.
+ */
+abstract contract AttributeStorage {
+    OntologyTermRegistry public immutable ONTOLOGY;
+
+    // ─── Datatype discriminators ────────────────────────────────────
+    uint8 internal constant DT_STRING       = 1;
+    uint8 internal constant DT_ADDRESS      = 2;
+    uint8 internal constant DT_BOOL         = 3;
+    uint8 internal constant DT_UINT256      = 4;
+    uint8 internal constant DT_BYTES32      = 5;
+    uint8 internal constant DT_STRING_ARR   = 6;
+    uint8 internal constant DT_ADDRESS_ARR  = 7;
+    uint8 internal constant DT_BYTES32_ARR  = 8;
+
+    // ─── Typed value families ───────────────────────────────────────
+    mapping(bytes32 => mapping(bytes32 => string))    private _string;
+    mapping(bytes32 => mapping(bytes32 => address))   private _address;
+    mapping(bytes32 => mapping(bytes32 => bool))      private _bool;
+    mapping(bytes32 => mapping(bytes32 => uint256))   private _uint;
+    mapping(bytes32 => mapping(bytes32 => bytes32))   private _bytes32;
+    mapping(bytes32 => mapping(bytes32 => string[]))  private _stringArr;
+    mapping(bytes32 => mapping(bytes32 => address[])) private _addressArr;
+    mapping(bytes32 => mapping(bytes32 => bytes32[])) private _bytes32Arr;
+
+    // ─── Indexing / metadata ────────────────────────────────────────
+    mapping(bytes32 => bytes32[])                      private _predicates;
+    mapping(bytes32 => mapping(bytes32 => bool))       private _isSet;
+    mapping(bytes32 => mapping(bytes32 => uint8))      private _datatype;
+    mapping(bytes32 => mapping(bytes32 => uint64))     private _updatedAt;
+    mapping(bytes32 => uint64)                         private _subjectVersion;
+    bytes32[]                                          private _allSubjects;
+    mapping(bytes32 => bool)                           private _subjectKnown;
+
+    // ─── Events ─────────────────────────────────────────────────────
+    event AttributeSet(bytes32 indexed subject, bytes32 indexed predicate, uint8 datatype, uint64 version);
+    event AttributeUnset(bytes32 indexed subject, bytes32 indexed predicate, uint64 version);
+    event AttributeAppended(bytes32 indexed subject, bytes32 indexed predicate, uint8 datatype, uint64 version);
+    event SubjectFirstSeen(bytes32 indexed subject);
+
+    // ─── Errors ─────────────────────────────────────────────────────
+    error PredicateNotActive();
+    error AttributeNotSet();
+
+    constructor(address ontologyRegistry) {
+        ONTOLOGY = OntologyTermRegistry(ontologyRegistry);
+    }
+
+    // ─── Public datatype discriminator readers (for ShapeRegistry) ──
+
+    function DT_STRING_PUB() external pure returns (uint8) { return DT_STRING; }
+    function DT_ADDRESS_PUB() external pure returns (uint8) { return DT_ADDRESS; }
+    function DT_BOOL_PUB() external pure returns (uint8) { return DT_BOOL; }
+    function DT_UINT256_PUB() external pure returns (uint8) { return DT_UINT256; }
+    function DT_BYTES32_PUB() external pure returns (uint8) { return DT_BYTES32; }
+    function DT_STRING_ARR_PUB() external pure returns (uint8) { return DT_STRING_ARR; }
+    function DT_ADDRESS_ARR_PUB() external pure returns (uint8) { return DT_ADDRESS_ARR; }
+    function DT_BYTES32_ARR_PUB() external pure returns (uint8) { return DT_BYTES32_ARR; }
+
+    // ─── Internal setters (subclass-only) ───────────────────────────
+
+    function _setString(bytes32 subject, bytes32 predicate, string memory value) internal {
+        _requirePredicate(predicate);
+        _string[subject][predicate] = value;
+        _record(subject, predicate, DT_STRING);
+    }
+
+    function _setAddress(bytes32 subject, bytes32 predicate, address value) internal {
+        _requirePredicate(predicate);
+        _address[subject][predicate] = value;
+        _record(subject, predicate, DT_ADDRESS);
+    }
+
+    function _setBool(bytes32 subject, bytes32 predicate, bool value) internal {
+        _requirePredicate(predicate);
+        _bool[subject][predicate] = value;
+        _record(subject, predicate, DT_BOOL);
+    }
+
+    function _setUint(bytes32 subject, bytes32 predicate, uint256 value) internal {
+        _requirePredicate(predicate);
+        _uint[subject][predicate] = value;
+        _record(subject, predicate, DT_UINT256);
+    }
+
+    function _setBytes32(bytes32 subject, bytes32 predicate, bytes32 value) internal {
+        _requirePredicate(predicate);
+        _bytes32[subject][predicate] = value;
+        _record(subject, predicate, DT_BYTES32);
+    }
+
+    function _setStringArr(bytes32 subject, bytes32 predicate, string[] memory values) internal {
+        _requirePredicate(predicate);
+        delete _stringArr[subject][predicate];
+        for (uint256 i = 0; i < values.length; i++) {
+            _stringArr[subject][predicate].push(values[i]);
+        }
+        _record(subject, predicate, DT_STRING_ARR);
+    }
+
+    function _setAddressArr(bytes32 subject, bytes32 predicate, address[] memory values) internal {
+        _requirePredicate(predicate);
+        delete _addressArr[subject][predicate];
+        for (uint256 i = 0; i < values.length; i++) {
+            _addressArr[subject][predicate].push(values[i]);
+        }
+        _record(subject, predicate, DT_ADDRESS_ARR);
+    }
+
+    function _setBytes32Arr(bytes32 subject, bytes32 predicate, bytes32[] memory values) internal {
+        _requirePredicate(predicate);
+        delete _bytes32Arr[subject][predicate];
+        for (uint256 i = 0; i < values.length; i++) {
+            _bytes32Arr[subject][predicate].push(values[i]);
+        }
+        _record(subject, predicate, DT_BYTES32_ARR);
+    }
+
+    function _appendString(bytes32 subject, bytes32 predicate, string memory value) internal {
+        _requirePredicate(predicate);
+        _stringArr[subject][predicate].push(value);
+        _recordAppend(subject, predicate, DT_STRING_ARR);
+    }
+
+    function _appendAddress(bytes32 subject, bytes32 predicate, address value) internal {
+        _requirePredicate(predicate);
+        _addressArr[subject][predicate].push(value);
+        _recordAppend(subject, predicate, DT_ADDRESS_ARR);
+    }
+
+    function _appendBytes32(bytes32 subject, bytes32 predicate, bytes32 value) internal {
+        _requirePredicate(predicate);
+        _bytes32Arr[subject][predicate].push(value);
+        _recordAppend(subject, predicate, DT_BYTES32_ARR);
+    }
+
+    function _unset(bytes32 subject, bytes32 predicate) internal {
+        if (!_isSet[subject][predicate]) revert AttributeNotSet();
+        uint8 dt = _datatype[subject][predicate];
+        if (dt == DT_STRING)            delete _string[subject][predicate];
+        else if (dt == DT_ADDRESS)      delete _address[subject][predicate];
+        else if (dt == DT_BOOL)         delete _bool[subject][predicate];
+        else if (dt == DT_UINT256)      delete _uint[subject][predicate];
+        else if (dt == DT_BYTES32)      delete _bytes32[subject][predicate];
+        else if (dt == DT_STRING_ARR)   delete _stringArr[subject][predicate];
+        else if (dt == DT_ADDRESS_ARR)  delete _addressArr[subject][predicate];
+        else if (dt == DT_BYTES32_ARR)  delete _bytes32Arr[subject][predicate];
+        _isSet[subject][predicate] = false;
+        delete _datatype[subject][predicate];
+        delete _updatedAt[subject][predicate];
+        uint64 v = _bumpVersion(subject);
+        emit AttributeUnset(subject, predicate, v);
+    }
+
+    // ─── Public getters ─────────────────────────────────────────────
+
+    function getString(bytes32 subject, bytes32 predicate) external view returns (string memory) {
+        return _string[subject][predicate];
+    }
+    function getAddress(bytes32 subject, bytes32 predicate) external view returns (address) {
+        return _address[subject][predicate];
+    }
+    function getBool(bytes32 subject, bytes32 predicate) external view returns (bool) {
+        return _bool[subject][predicate];
+    }
+    function getUint(bytes32 subject, bytes32 predicate) external view returns (uint256) {
+        return _uint[subject][predicate];
+    }
+    function getBytes32(bytes32 subject, bytes32 predicate) external view returns (bytes32) {
+        return _bytes32[subject][predicate];
+    }
+    function getStringArr(bytes32 subject, bytes32 predicate) external view returns (string[] memory) {
+        return _stringArr[subject][predicate];
+    }
+    function getAddressArr(bytes32 subject, bytes32 predicate) external view returns (address[] memory) {
+        return _addressArr[subject][predicate];
+    }
+    function getBytes32Arr(bytes32 subject, bytes32 predicate) external view returns (bytes32[] memory) {
+        return _bytes32Arr[subject][predicate];
+    }
+
+    function predicatesOf(bytes32 subject) external view returns (bytes32[] memory) {
+        return _predicates[subject];
+    }
+    function datatypeOf(bytes32 subject, bytes32 predicate) external view returns (uint8) {
+        return _datatype[subject][predicate];
+    }
+    function updatedAt(bytes32 subject, bytes32 predicate) external view returns (uint64) {
+        return _updatedAt[subject][predicate];
+    }
+    function isSet(bytes32 subject, bytes32 predicate) external view returns (bool) {
+        return _isSet[subject][predicate];
+    }
+    function subjectVersion(bytes32 subject) external view returns (uint64) {
+        return _subjectVersion[subject];
+    }
+    function allSubjects() external view returns (bytes32[] memory) {
+        return _allSubjects;
+    }
+    function subjectCount() external view returns (uint256) {
+        return _allSubjects.length;
+    }
+
+    // ─── Internal helpers ───────────────────────────────────────────
+
+    function _requirePredicate(bytes32 predicate) internal view {
+        if (!ONTOLOGY.isActive(predicate)) revert PredicateNotActive();
+    }
+
+    function _record(bytes32 subject, bytes32 predicate, uint8 dt) internal {
+        _trackSubject(subject);
+        if (!_isSet[subject][predicate]) {
+            _predicates[subject].push(predicate);
+            _isSet[subject][predicate] = true;
+        }
+        _datatype[subject][predicate] = dt;
+        uint64 v = _bumpVersion(subject);
+        _updatedAt[subject][predicate] = v;
+        emit AttributeSet(subject, predicate, dt, v);
+    }
+
+    function _recordAppend(bytes32 subject, bytes32 predicate, uint8 dt) internal {
+        _trackSubject(subject);
+        if (!_isSet[subject][predicate]) {
+            _predicates[subject].push(predicate);
+            _isSet[subject][predicate] = true;
+        }
+        _datatype[subject][predicate] = dt;
+        uint64 v = _bumpVersion(subject);
+        _updatedAt[subject][predicate] = v;
+        emit AttributeAppended(subject, predicate, dt, v);
+    }
+
+    function _trackSubject(bytes32 subject) internal {
+        if (!_subjectKnown[subject]) {
+            _subjectKnown[subject] = true;
+            _allSubjects.push(subject);
+            emit SubjectFirstSeen(subject);
+        }
+    }
+
+    function _bumpVersion(bytes32 subject) internal returns (uint64) {
+        uint64 next = _subjectVersion[subject] + 1;
+        _subjectVersion[subject] = next;
+        return next;
+    }
+}
+
+/**
+ * @title IAttributeReader
+ * @notice Read-only interface every AttributeStorage subclass exposes.
+ *         ShapeRegistry takes this so a single shape definition can
+ *         validate any registry's subject.
+ */
+interface IAttributeReader {
+    function isSet(bytes32 subject, bytes32 predicate) external view returns (bool);
+    function datatypeOf(bytes32 subject, bytes32 predicate) external view returns (uint8);
+    function getBytes32(bytes32 subject, bytes32 predicate) external view returns (bytes32);
+    function getBytes32Arr(bytes32 subject, bytes32 predicate) external view returns (bytes32[] memory);
+}

package/src/ontology/OntologyTermRegistry.sol

@@ -0,0 +1,146 @@
+// SPDX-License-Identifier: MIT
+pragma solidity ^0.8.28;
+
+/**
+ * @title OntologyTermRegistry
+ * @notice Governed registry of valid ontology predicates for the
+ *         agenticprimitives trust fabric.
+ *
+ * Controls which predicate bytes32 ids may appear on any
+ * `AttributeStorage` subclass (naming records, future relationships /
+ * identity records). Each term maps a `bytes32` id (keccak256 of a
+ * CURIE like `"atl:displayName"`) to its full URI, human label, and
+ * expected datatype family.
+ *
+ * Governance: only `governor` may register or deactivate terms.
+ * Deployer is the bootstrap governor; rotation to a multi-sig /
+ * Smart Agent CustodyPolicy is a single `transferGovernor` call.
+ *
+ * Adapted from smart-agent
+ * (`packages/contracts/src/OntologyTermRegistry.sol`, 136 LOC) —
+ * structurally identical; copied here to keep the agenticprimitives
+ * trust fabric self-contained.
+ */
+contract OntologyTermRegistry {
+    struct Term {
+        bytes32 id;          // keccak256("atl:displayName")
+        string curie;        // "atl:displayName"
+        string uri;          // "https://agentictrust.io/ontology/core#displayName"
+        string label;        // "Display Name"
+        string datatype;     // "string" | "address" | "bool" | "uint256" | "bytes32" | "string[]" | "address[]" | "bytes32[]"
+        bool active;
+        uint256 registeredAt;
+    }
+
+    address public governor;
+    mapping(bytes32 => Term) private _terms;
+    bytes32[] private _termIds;
+
+    event TermRegistered(bytes32 indexed id, string curie, string uri);
+    event TermDeactivated(bytes32 indexed id);
+    event TermActivated(bytes32 indexed id);
+    event GovernorTransferred(address indexed oldGovernor, address indexed newGovernor);
+
+    error NotGovernor();
+    error TermExists();
+    error TermNotFound();
+    error ZeroGovernor();
+
+    modifier onlyGovernor() {
+        if (msg.sender != governor) revert NotGovernor();
+        _;
+    }
+
+    constructor(address governor_) {
+        if (governor_ == address(0)) revert ZeroGovernor();
+        governor = governor_;
+    }
+
+    function transferGovernor(address newGovernor) external onlyGovernor {
+        if (newGovernor == address(0)) revert ZeroGovernor();
+        emit GovernorTransferred(governor, newGovernor);
+        governor = newGovernor;
+    }
+
+    function registerTerm(
+        bytes32 id,
+        string calldata curie,
+        string calldata uri,
+        string calldata label,
+        string calldata datatype
+    ) external onlyGovernor {
+        if (_terms[id].registeredAt != 0) revert TermExists();
+        _terms[id] = Term({
+            id: id,
+            curie: curie,
+            uri: uri,
+            label: label,
+            datatype: datatype,
+            active: true,
+            registeredAt: block.timestamp
+        });
+        _termIds.push(id);
+        emit TermRegistered(id, curie, uri);
+    }
+
+    function registerTermBatch(
+        bytes32[] calldata ids,
+        string[] calldata curies,
+        string[] calldata uris,
+        string[] calldata labels,
+        string[] calldata datatypes
+    ) external onlyGovernor {
+        for (uint256 i = 0; i < ids.length; i++) {
+            if (_terms[ids[i]].registeredAt != 0) continue; // skip existing
+            _terms[ids[i]] = Term({
+                id: ids[i],
+                curie: curies[i],
+                uri: uris[i],
+                label: labels[i],
+                datatype: datatypes[i],
+                active: true,
+                registeredAt: block.timestamp
+            });
+            _termIds.push(ids[i]);
+            emit TermRegistered(ids[i], curies[i], uris[i]);
+        }
+    }
+
+    function deactivateTerm(bytes32 id) external onlyGovernor {
+        if (_terms[id].registeredAt == 0) revert TermNotFound();
+        _terms[id].active = false;
+        emit TermDeactivated(id);
+    }
+
+    function activateTerm(bytes32 id) external onlyGovernor {
+        if (_terms[id].registeredAt == 0) revert TermNotFound();
+        _terms[id].active = true;
+        emit TermActivated(id);
+    }
+
+    // ─── Queries ────────────────────────────────────────────────────
+
+    function getTerm(bytes32 id) external view returns (Term memory) {
+        return _terms[id];
+    }
+
+    function isRegistered(bytes32 id) external view returns (bool) {
+        return _terms[id].registeredAt != 0;
+    }
+
+    function isActive(bytes32 id) external view returns (bool) {
+        return _terms[id].active;
+    }
+
+    function termCount() external view returns (uint256) {
+        return _termIds.length;
+    }
+
+    function getTermAt(uint256 index) external view returns (Term memory) {
+        return _terms[_termIds[index]];
+    }
+
+    function getAllTermIds() external view returns (bytes32[] memory) {
+        return _termIds;
+    }
+}

package/src/ontology/ShapeRegistry.sol

@@ -0,0 +1,240 @@
+// SPDX-License-Identifier: MIT
+pragma solidity ^0.8.28;
+
+import "./AttributeStorage.sol";
+
+/**
+ * @title ShapeRegistry
+ * @notice SHACL-inspired class shape constraints. Decoupled from any
+ *         specific store: every validation call takes the reader's
+ *         address, so a single registry can hold shapes that validate
+ *         against any AttributeStorage subclass (naming records today,
+ *         relationship + identity records in Phase 3+).
+ *
+ * Supported SHACL subset:
+ *   `sh:path`       → predicate id
+ *   `sh:datatype`   → AttributeStorage datatype family discriminator (`DT_*`)
+ *   `sh:minCount` / `sh:maxCount` → cardinality enum
+ *   `sh:in`         → enumSetId referencing the contract's stored allowed values
+ *   `sh:class`      → expectedClass id (informational; off-chain class IRI hash)
+ *
+ * Adapted from smart-agent
+ * (`packages/contracts/src/ShapeRegistry.sol`, 231 LOC) —
+ * structurally identical.
+ */
+contract ShapeRegistry {
+    address public governor;
+
+    enum Cardinality {
+        OPTIONAL,        // 0..1
+        REQUIRED_ONE,    // 1..1
+        REQUIRED_MANY,   // 1..*
+        OPTIONAL_MANY    // 0..*
+    }
+
+    struct PropertyConstraint {
+        bytes32 predicate;
+        uint8 expectedDatatype;
+        Cardinality cardinality;
+        bytes32 enumSetId;
+        bytes32 expectedClass;
+    }
+
+    struct Shape {
+        bytes32 classId;
+        string shapeURI;
+        bytes32 shapeHash;
+        uint16 version;
+        bool active;
+        bool exists;
+    }
+
+    mapping(bytes32 => Shape)                    private _shapes;
+    mapping(bytes32 => PropertyConstraint[])     private _props;
+    mapping(bytes32 => bytes32[])                private _enumValues;
+    mapping(bytes32 => mapping(bytes32 => bool)) private _enumContains;
+    bytes32[] private _classIds;
+
+    event ShapeDefined(bytes32 indexed classId, uint16 version, string shapeURI, bytes32 shapeHash);
+    event ShapeUpdated(bytes32 indexed classId, uint16 version, bytes32 shapeHash);
+    event ShapeDeactivated(bytes32 indexed classId);
+    event ShapeActivated(bytes32 indexed classId);
+    event EnumSetDefined(bytes32 indexed enumSetId, uint256 valueCount);
+    event GovernorTransferred(address indexed previousGovernor, address indexed newGovernor);
+
+    error NotGovernor();
+    error ShapeAlreadyDefined();
+    error ShapeNotDefined();
+    error ShapeNotActive();
+    error MissingRequiredProperty(bytes32 predicate);
+    error WrongDatatype(bytes32 predicate, uint8 actual, uint8 expected);
+    error EnumValueNotAllowed(bytes32 predicate, bytes32 actualValue);
+    error EnumSetEmpty();
+    error ZeroGovernor();
+
+    modifier onlyGovernor() {
+        if (msg.sender != governor) revert NotGovernor();
+        _;
+    }
+
+    constructor(address governor_) {
+        if (governor_ == address(0)) revert ZeroGovernor();
+        governor = governor_;
+    }
+
+    function transferGovernor(address newGovernor) external onlyGovernor {
+        if (newGovernor == address(0)) revert ZeroGovernor();
+        emit GovernorTransferred(governor, newGovernor);
+        governor = newGovernor;
+    }
+
+    // ─── Shape definition ───────────────────────────────────────────
+
+    function defineShape(
+        bytes32 classId,
+        PropertyConstraint[] calldata props,
+        string calldata shapeURI,
+        bytes32 shapeHash
+    ) external onlyGovernor returns (uint16) {
+        if (_shapes[classId].exists) revert ShapeAlreadyDefined();
+        _shapes[classId] = Shape({
+            classId: classId,
+            shapeURI: shapeURI,
+            shapeHash: shapeHash,
+            version: 1,
+            active: true,
+            exists: true
+        });
+        _classIds.push(classId);
+        for (uint256 i = 0; i < props.length; i++) {
+            _props[classId].push(props[i]);
+        }
+        emit ShapeDefined(classId, 1, shapeURI, shapeHash);
+        return 1;
+    }
+
+    function updateShape(
+        bytes32 classId,
+        PropertyConstraint[] calldata props,
+        string calldata shapeURI,
+        bytes32 shapeHash
+    ) external onlyGovernor returns (uint16) {
+        Shape storage s = _shapes[classId];
+        if (!s.exists) revert ShapeNotDefined();
+        s.version += 1;
+        s.shapeURI = shapeURI;
+        s.shapeHash = shapeHash;
+        delete _props[classId];
+        for (uint256 i = 0; i < props.length; i++) {
+            _props[classId].push(props[i]);
+        }
+        emit ShapeUpdated(classId, s.version, shapeHash);
+        return s.version;
+    }
+
+    function deactivateShape(bytes32 classId) external onlyGovernor {
+        Shape storage s = _shapes[classId];
+        if (!s.exists) revert ShapeNotDefined();
+        s.active = false;
+        emit ShapeDeactivated(classId);
+    }
+
+    function activateShape(bytes32 classId) external onlyGovernor {
+        Shape storage s = _shapes[classId];
+        if (!s.exists) revert ShapeNotDefined();
+        s.active = true;
+        emit ShapeActivated(classId);
+    }
+
+    function defineEnumSet(bytes32 enumSetId, bytes32[] calldata allowedValues) external onlyGovernor {
+        if (allowedValues.length == 0) revert EnumSetEmpty();
+        bytes32[] storage existing = _enumValues[enumSetId];
+        for (uint256 i = 0; i < existing.length; i++) {
+            _enumContains[enumSetId][existing[i]] = false;
+        }
+        delete _enumValues[enumSetId];
+        for (uint256 i = 0; i < allowedValues.length; i++) {
+            _enumValues[enumSetId].push(allowedValues[i]);
+            _enumContains[enumSetId][allowedValues[i]] = true;
+        }
+        emit EnumSetDefined(enumSetId, allowedValues.length);
+    }
+
+    // ─── Validation ─────────────────────────────────────────────────
+
+    /// @notice Validate `subject` in `store` against the shape `classId`.
+    ///         Reverts with a specific error if any constraint fails.
+    function validateSubject(bytes32 classId, bytes32 subject, address store) external view {
+        _validate(classId, subject, IAttributeReader(store));
+    }
+
+    /// @notice Try-validate variant: returns false instead of reverting.
+    function isValid(bytes32 classId, bytes32 subject, address store) external view returns (bool) {
+        try this.validateSubject(classId, subject, store) {
+            return true;
+        } catch {
+            return false;
+        }
+    }
+
+    function _validate(bytes32 classId, bytes32 subject, IAttributeReader store) internal view {
+        Shape storage s = _shapes[classId];
+        if (!s.exists) revert ShapeNotDefined();
+        if (!s.active) revert ShapeNotActive();
+
+        PropertyConstraint[] storage props = _props[classId];
+        for (uint256 i = 0; i < props.length; i++) {
+            PropertyConstraint storage p = props[i];
+            bool present = store.isSet(subject, p.predicate);
+            bool required = p.cardinality == Cardinality.REQUIRED_ONE
+                || p.cardinality == Cardinality.REQUIRED_MANY;
+
+            if (!present) {
+                if (required) revert MissingRequiredProperty(p.predicate);
+                continue;
+            }
+
+            uint8 actualDt = store.datatypeOf(subject, p.predicate);
+            if (actualDt != p.expectedDatatype) {
+                revert WrongDatatype(p.predicate, actualDt, p.expectedDatatype);
+            }
+
+            if (p.enumSetId != bytes32(0)) {
+                if (p.expectedDatatype == 5) { // DT_BYTES32
+                    bytes32 v = store.getBytes32(subject, p.predicate);
+                    if (!_enumContains[p.enumSetId][v]) {
+                        revert EnumValueNotAllowed(p.predicate, v);
+                    }
+                } else if (p.expectedDatatype == 8) { // DT_BYTES32_ARR
+                    bytes32[] memory arr = store.getBytes32Arr(subject, p.predicate);
+                    for (uint256 j = 0; j < arr.length; j++) {
+                        if (!_enumContains[p.enumSetId][arr[j]]) {
+                            revert EnumValueNotAllowed(p.predicate, arr[j]);
+                        }
+                    }
+                }
+            }
+        }
+    }
+
+    // ─── Queries ────────────────────────────────────────────────────
+
+    function getShape(bytes32 classId) external view returns (Shape memory) {
+        return _shapes[classId];
+    }
+    function getProperties(bytes32 classId) external view returns (PropertyConstraint[] memory) {
+        return _props[classId];
+    }
+    function getEnumValues(bytes32 enumSetId) external view returns (bytes32[] memory) {
+        return _enumValues[enumSetId];
+    }
+    function isInEnumSet(bytes32 enumSetId, bytes32 value) external view returns (bool) {
+        return _enumContains[enumSetId][value];
+    }
+    function shapeCount() external view returns (uint256) {
+        return _classIds.length;
+    }
+    function getClassIdAt(uint256 index) external view returns (bytes32) {
+        return _classIds[index];
+    }
+}