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

package/src/geo/GeoFeatureRegistry.sol

@@ -0,0 +1,190 @@
+// SPDX-License-Identifier: MIT
+pragma solidity ^0.8.28;
+
+/**
+ * @title GeoFeatureRegistry
+ * @notice Versioned PUBLIC geo features — the definition layer of the
+ *         definition-vs-claim model (spec 251). Exact geometry stays OFF chain
+ *         behind `metadataURI`; on chain we anchor a `geometryHash`, coverage +
+ *         source merkle roots, and a COARSE centroid/bbox (UI only).
+ *
+ *   ─── Doctrine ───
+ *
+ * GFR-01 Keyed by Smart Agent ADDRESS (the `stewardAccount`); names are never
+ *        authority (ADR-0010).
+ * GFR-02 Authorization is `msg.sender == stewardAccount` — the steward SA
+ *        publishes through its own `execute()` path. NO `isOwner` staticcall.
+ * GFR-03 Monotonic per-`featureId` versioning; a boundary refresh is a new
+ *        version (claims pin a version, so they don't retroactively re-target).
+ * GFR-04 `featureKind` is a C-box-anchored codelist value (ADR-0009 lockstep).
+ * GFR-05 Geo CLAIMS are NOT on chain — they are verifiable credentials that
+ *        point to a `(featureId, version)` here (spec 251). No GeoClaimRegistry.
+ * GFR-06 NO domain/faith vocabulary (reusable substrate).
+ * GFR-07 NEUTRAL public geography ONLY. A feature is a generic public place
+ *        (planet/region/country/admin area). It is NEVER tagged with — and its
+ *        `metadataURI` NEVER carries — domain or operational data that could
+ *        imply a private presence (e.g. "where a worker operates", access
+ *        sensitivity, ministry context). Sensitivity classification is an
+ *        OFF-chain app/domain policy applied OVER neutral features, never an
+ *        on-chain feature attribute. All metadata MUST be sanitized.
+ * GFR-08 NO on-chain skill↔geo mapping. This registry holds geo features only
+ *        and has ZERO reference to SkillDefinitionRegistry (or any skill id).
+ *        Any "serves skill X in region Y" fact is an off-chain claim/credential.
+ *
+ * Ported from smart-agent `GeoFeatureRegistry`; diverges per spec 251 (AP auth,
+ * C-box-anchored kinds, no name binding in v1).
+ */
+contract GeoFeatureRegistry {
+    // ─── C-box feature-kind codelist (keccak of the cbox URIs) ──────────
+    //   Concept URIs are declared in packages/ontology cbox/geo-vocabulary.ttl
+    //   (scheme apg:geoKind); lockstep-gated against the ontology (ADR-0009).
+    bytes32 public constant KIND_PLANET = keccak256(bytes("https://agenticprimitives.dev/ns/geo#Planet"));
+    bytes32 public constant KIND_REGION = keccak256(bytes("https://agenticprimitives.dev/ns/geo#Region"));
+    bytes32 public constant KIND_COUNTRY = keccak256(bytes("https://agenticprimitives.dev/ns/geo#Country"));
+    bytes32 public constant KIND_ADMIN = keccak256(bytes("https://agenticprimitives.dev/ns/geo#AdminArea"));
+    bytes32 public constant KIND_CUSTOM = keccak256(bytes("https://agenticprimitives.dev/ns/geo#Custom"));
+    int256 public constant COORD_SCALE = 1e7;
+
+    // ─── Errors ─────────────────────────────────────────────────────────
+    error NotSteward();
+    error FeatureNotFound();
+    error EmptyMetadata();
+    error EmptyId();
+
+    // ─── Storage ────────────────────────────────────────────────────────
+    struct FeatureRecord {
+        bytes32 featureId;
+        uint64 version;
+        address stewardAccount;
+        bytes32 featureKind;
+        bytes32 geometryHash; // keccak of canonical GeoJSON (off chain)
+        bytes32 coverageRoot; // merkle root over covering cells (e.g. H3)
+        bytes32 sourceSetRoot; // merkle root over the source dataset
+        string metadataURI;
+        int256 centroidLat; // degrees × 1e7, coarse — UI only
+        int256 centroidLon;
+        int256 bboxMinLat;
+        int256 bboxMinLon;
+        int256 bboxMaxLat;
+        int256 bboxMaxLon;
+        uint64 validAfter;
+        uint64 validUntil;
+        bool active;
+        uint64 registeredAt;
+    }
+
+    mapping(bytes32 => mapping(uint64 => FeatureRecord)) private _records;
+    mapping(bytes32 => uint64) public latestVersion;
+    bytes32[] private _allFeatures;
+
+    // ─── Events ─────────────────────────────────────────────────────────
+    event FeaturePublished(
+        bytes32 indexed featureId,
+        uint64 indexed version,
+        address indexed steward,
+        bytes32 featureKind,
+        bytes32 geometryHash,
+        bytes32 coverageRoot,
+        bytes32 sourceSetRoot,
+        string metadataURI
+    );
+    event FeatureDeactivated(bytes32 indexed featureId, uint64 version);
+    event FeatureValidityChanged(bytes32 indexed featureId, uint64 version, uint64 validAfter, uint64 validUntil);
+
+    // ─── Publish ────────────────────────────────────────────────────────
+    struct PublishInput {
+        bytes32 featureId;
+        bytes32 featureKind;
+        address stewardAccount;
+        bytes32 geometryHash;
+        bytes32 coverageRoot;
+        bytes32 sourceSetRoot;
+        string metadataURI;
+        int256 centroidLat;
+        int256 centroidLon;
+        int256 bboxMinLat;
+        int256 bboxMinLon;
+        int256 bboxMaxLat;
+        int256 bboxMaxLon;
+        uint64 validAfter;
+        uint64 validUntil;
+    }
+
+    function publish(PublishInput calldata p) external returns (uint64 version) {
+        if (p.featureId == bytes32(0)) revert EmptyId();
+        if (bytes(p.metadataURI).length == 0) revert EmptyMetadata();
+        if (msg.sender != p.stewardAccount) revert NotSteward();
+
+        uint64 prevVer = latestVersion[p.featureId];
+        if (prevVer != 0 && _records[p.featureId][prevVer].stewardAccount != p.stewardAccount) {
+            revert NotSteward();
+        }
+
+        version = prevVer + 1;
+        _records[p.featureId][version] = FeatureRecord({
+            featureId: p.featureId,
+            version: version,
+            stewardAccount: p.stewardAccount,
+            featureKind: p.featureKind,
+            geometryHash: p.geometryHash,
+            coverageRoot: p.coverageRoot,
+            sourceSetRoot: p.sourceSetRoot,
+            metadataURI: p.metadataURI,
+            centroidLat: p.centroidLat,
+            centroidLon: p.centroidLon,
+            bboxMinLat: p.bboxMinLat,
+            bboxMinLon: p.bboxMinLon,
+            bboxMaxLat: p.bboxMaxLat,
+            bboxMaxLon: p.bboxMaxLon,
+            validAfter: p.validAfter,
+            validUntil: p.validUntil,
+            active: true,
+            registeredAt: uint64(block.timestamp)
+        });
+        latestVersion[p.featureId] = version;
+        if (prevVer == 0) _allFeatures.push(p.featureId);
+
+        emit FeaturePublished(p.featureId, version, p.stewardAccount, p.featureKind, p.geometryHash, p.coverageRoot, p.sourceSetRoot, p.metadataURI);
+    }
+
+    function deactivate(bytes32 featureId) external {
+        uint64 v = latestVersion[featureId];
+        if (v == 0) revert FeatureNotFound();
+        FeatureRecord storage r = _records[featureId][v];
+        if (msg.sender != r.stewardAccount) revert NotSteward();
+        r.active = false;
+        emit FeatureDeactivated(featureId, v);
+    }
+
+    function setValidity(bytes32 featureId, uint64 version, uint64 validAfter, uint64 validUntil) external {
+        FeatureRecord storage r = _records[featureId][version];
+        if (r.version == 0) revert FeatureNotFound();
+        if (msg.sender != r.stewardAccount) revert NotSteward();
+        r.validAfter = validAfter;
+        r.validUntil = validUntil;
+        emit FeatureValidityChanged(featureId, version, validAfter, validUntil);
+    }
+
+    // ─── Views ──────────────────────────────────────────────────────────
+    function getFeature(bytes32 featureId, uint64 version) external view returns (FeatureRecord memory) {
+        FeatureRecord memory r = _records[featureId][version];
+        if (r.version == 0) revert FeatureNotFound();
+        return r;
+    }
+
+    function getLatest(bytes32 featureId) external view returns (FeatureRecord memory) {
+        uint64 v = latestVersion[featureId];
+        if (v == 0) revert FeatureNotFound();
+        return _records[featureId][v];
+    }
+
+    /// @notice True if `version` of `featureId` exists (used by off-chain geo claim credentials to
+    ///         confirm the pinned definition version they reference).
+    function exists(bytes32 featureId, uint64 version) external view returns (bool) {
+        return _records[featureId][version].version != 0;
+    }
+
+    function allFeatures() external view returns (bytes32[] memory) {
+        return _allFeatures;
+    }
+}

package/src/naming/AgentNameRegistry.sol

@@ -1,11 +1,13 @@
 // SPDX-License-Identifier: MIT
 pragma solidity ^0.8.28;
 
+import "../governance/GovernanceManaged.sol";
+
 /**
  * @title AgentNameRegistry
  * @notice Hierarchical multi-root name registry for Smart Agents.
  *
- * Names are keyed by `node` (the ENS-style namehash:
+ * Names are keyed by `node` (the recursive namehash:
  * `keccak256(parentNode || labelhash)`). Each node has an owner (a Smart
  * Agent address), a resolver, an optional subregistry delegate that may
  * issue children, a parent pointer, the labelhash, and an optional
@@ -36,7 +38,11 @@ pragma solidity ^0.8.28;
  * discipline (a primary name only counts when the forward record
  * agrees).
  */
-contract AgentNameRegistry {
+/// @dev R6.8 — inherits `GovernanceManaged` to gain the
+///      `whenNotPaused` modifier on its mutating surface. The registry
+///      still owns its own per-node auth (`_requireParentAuth` /
+///      `msg.sender == owner`); governance only owns the pause flag.
+contract AgentNameRegistry is GovernanceManaged {
     // ─── H7-C.4 / CON-NAMING-001 — root-initializer gate ───────────────
     //
     // `initializeRoot` was permissionless: any mempool observer could
@@ -129,10 +135,13 @@ contract AgentNameRegistry {
 
     // ─── Constructor (H7-C.4) ───────────────────────────────────────
 
-    /// @notice Set the immutable root-initializer. The deploy script
-    ///         deploys the registry + calls `initializeRoot` in the same
-    ///         transaction so the TLD can't be frontrun.
-    constructor(address initializer_) {
+    /// @notice Set the immutable root-initializer + governance pointer.
+    ///         The deploy script deploys the registry + calls
+    ///         `initializeRoot` in the same transaction so the TLD
+    ///         can't be frontrun. R6.8 added `governance_` so the
+    ///         registry can read the system pause flag through
+    ///         `GovernanceManaged._pausedSafe()`.
+    constructor(address initializer_, address governance_) GovernanceManaged(governance_) {
         if (initializer_ == address(0)) revert ZeroOwner();
         initializer = initializer_;
     }
@@ -219,7 +228,7 @@ contract AgentNameRegistry {
         address newOwner,
         address resolverContract,
         uint64 expiry
-    ) external returns (bytes32 childNode) {
+    ) external whenNotPaused returns (bytes32 childNode) {
         if (bytes(label).length == 0) revert EmptyLabel();
         if (newOwner == address(0)) revert ZeroOwner();
         _requireParentAuth(parentNode);
@@ -252,7 +261,7 @@ contract AgentNameRegistry {
      *         Authorized to the node's owner ONLY — labels can't be
      *         changed once set, preventing display spoofing.
      */
-    function backfillLabel(bytes32 node, string calldata label_) external {
+    function backfillLabel(bytes32 node, string calldata label_) external whenNotPaused {
         _requireNodeAuth(node);
         if (bytes(label_).length == 0) revert EmptyLabel();
         if (keccak256(bytes(label_)) != _records[node].labelhash) revert NotAuthorized();
@@ -262,26 +271,26 @@ contract AgentNameRegistry {
 
     // ─── Setters ────────────────────────────────────────────────────
 
-    function setOwner(bytes32 node, address newOwner) external {
+    function setOwner(bytes32 node, address newOwner) external whenNotPaused {
         _requireNodeAuth(node);
         if (newOwner == address(0)) revert ZeroOwner();
         _records[node].owner = newOwner;
         emit OwnerChanged(node, newOwner);
     }
 
-    function setResolver(bytes32 node, address resolverContract) external {
+    function setResolver(bytes32 node, address resolverContract) external whenNotPaused {
         _requireNodeAuth(node);
         _records[node].resolver = resolverContract;
         emit ResolverChanged(node, resolverContract);
     }
 
-    function setSubregistry(bytes32 node, address subregistryContract) external {
+    function setSubregistry(bytes32 node, address subregistryContract) external whenNotPaused {
         _requireNodeAuth(node);
         _records[node].subregistry = subregistryContract;
         emit SubregistryChanged(node, subregistryContract);
     }
 
-    function renew(bytes32 node, uint64 newExpiry) external {
+    function renew(bytes32 node, uint64 newExpiry) external whenNotPaused {
         _requireNodeAuth(node);
         _records[node].expiry = newExpiry;
         emit NameRenewed(node, newExpiry);
@@ -293,7 +302,10 @@ contract AgentNameRegistry {
      *         NOT verify the forward record points back here. The
      *         universal resolver enforces the round-trip on reads.
      */
-    function setPrimaryName(bytes32 node) external {
+    function setPrimaryName(bytes32 node) external whenNotPaused {
+        // R6.3: `registeredAt == 0` is a sentinel "record-never-created" check.
+        // Storage default IS exactly 0; not a numeric precision concern.
+        // slither-disable-next-line incorrect-equality
         if (node != bytes32(0) && _records[node].registeredAt == 0) revert NodeNotFound();
         _primaryName[msg.sender] = node;
         if (node == bytes32(0)) emit PrimaryNameCleared(msg.sender);

package/src/naming/AgentNameUniversalResolver.sol

@@ -122,7 +122,7 @@ contract AgentNameUniversalResolver {
     /**
      * @notice Reverse-resolve a Smart Agent address to its primary name
      *         STRING in a single external call. Per spec/222 this is
-     *         the ENS-aligned reverse path — no log walks, no name
+     *         the on-chain reverse path — no log walks, no name
      *         reconstruction in the SDK, no event indexer required.
      *
      *         Walks `parent(node)` up the registry, reading `label(node)`

package/src/naming/PermissionlessSubregistry.sol

@@ -2,6 +2,7 @@
 pragma solidity ^0.8.28;
 
 import "./AgentNameRegistry.sol";
+import {ReentrancyGuard} from "@openzeppelin/contracts/utils/ReentrancyGuard.sol";
 
 /**
  * @title PermissionlessSubregistry
@@ -36,7 +37,15 @@ import "./AgentNameRegistry.sol";
  *     through whatever authority `newOwner` represents (EOA wallet,
  *     PSA CustodyPolicy quorum, etc.).
  */
-contract PermissionlessSubregistry {
+/// @dev R6.2 — `ReentrancyGuard` closes the Slither finding
+///      `reentrancy-no-eth` on `register()`: the prior-claim check
+///      (`claimedBy[msg.sender] != 0`) was followed by an external
+///      call to `REGISTRY.register(...)` BEFORE the corresponding
+///      state write. A malicious resolver invoked by the registry
+///      could re-enter `register()` and pass the check a second time.
+///      The guard prevents any nested call into `register()`, closing
+///      the window. Recon doc § 4.1 / `docs/audits/r6-contracts-recon-2026-05-31.md`.
+contract PermissionlessSubregistry is ReentrancyGuard {
     AgentNameRegistry public immutable REGISTRY;
     bytes32 public immutable PARENT_NODE;
     address public immutable DEFAULT_RESOLVER;
@@ -77,12 +86,20 @@ contract PermissionlessSubregistry {
      *         fee — fee gating belongs in a different subregistry
      *         shape if needed.
      */
-    function register(string calldata label, address newOwner) external returns (bytes32 childNode) {
+    function register(string calldata label, address newOwner) external nonReentrant returns (bytes32 childNode) {
         if (bytes(label).length == 0) revert EmptyLabel();
         if (bytes(label).length < MIN_LABEL_LENGTH) revert LabelTooShort();
         if (newOwner == address(0)) revert ZeroNewOwner();
         bytes32 prior = claimedBy[msg.sender];
         if (prior != bytes32(0)) revert AlreadyClaimed(prior);
+        // R9 / docs/audits/r9-static-analysis-triage.md § Slither M-1:
+        // Slither flags this as cross-function reentrancy because state is
+        // written AFTER the external call. The function is `nonReentrant`
+        // (line 89) + REGISTRY is an immutable contract we control
+        // (`AgentNameRegistry`) that does not call back into this contract.
+        // The cross-function reader (`hasClaimed`) is view-only. No invariant
+        // is violated by the pre-write-window. Triaged false positive.
+        // slither-disable-next-line reentrancy-no-eth
         childNode = REGISTRY.register(PARENT_NODE, label, newOwner, DEFAULT_RESOLVER, 0);
         claimedBy[msg.sender] = childNode;
         unchecked {

package/src/relationships/AgentRelationship.sol

@@ -34,6 +34,13 @@ pragma solidity ^0.8.28;
  *     Off-chain JSON published at `metadataURI` MUST hash to
  *     `metadataHash`; consumers reject mismatched fetches.
  */
+// R6.3 — Every `e.createdAt == 0` comparison in this contract is a
+//        sentinel "edge-never-created" check. Storage default IS exactly
+//        0 for unset records, so the equality is semantically a
+//        "does-not-exist" probe — not a numeric-precision concern.
+//        Disabling Slither's `incorrect-equality` at the contract scope
+//        keeps these inline reads idiomatic.
+// slither-disable-start incorrect-equality
 contract AgentRelationship {
     enum EdgeStatus {
         NONE,        // 0 — never set (sentinel)
@@ -287,3 +294,4 @@ contract AgentRelationship {
         }
     }
 }
+// slither-disable-end incorrect-equality

package/src/skills/SkillDefinitionRegistry.sol

@@ -0,0 +1,181 @@
+// SPDX-License-Identifier: MIT
+pragma solidity ^0.8.28;
+
+/**
+ * @title SkillDefinitionRegistry
+ * @notice Versioned PUBLIC skill definitions — the definition layer of the
+ *         definition-vs-claim model (spec 251). Small, stable, public, indexable
+ *         anchors only: id, version, steward, kind, content hashes, metadata URI,
+ *         validity. The full SKOS expansion + taxonomy live OFF chain behind
+ *         `metadataURI` + `ontologyMerkleRoot`.
+ *
+ *   ─── Doctrine ───
+ *
+ * SDR-01 Keyed by Smart Agent ADDRESS (the `stewardAccount`); names are never
+ *        authority (ADR-0010).
+ * SDR-02 Authorization is `msg.sender == stewardAccount` — the steward SA
+ *        publishes through its own `execute()` path. NO `isOwner(address)`
+ *        staticcall fallback (AP diverges from smart-agent; see AgentRelationship).
+ * SDR-03 Monotonic per-`skillId` versioning; each version chains the prior
+ *        version's `ontologyMerkleRoot` as `predecessorRoot` (auditable taxonomy
+ *        refresh). A skill is never deleted; `deactivate` flips `active`.
+ * SDR-04 `skillKind` is a C-box-anchored codelist value: `keccak256(<cbox URI>)`,
+ *        gate-checked against `packages/ontology` (ADR-0009 lockstep).
+ * SDR-05 NO domain/faith vocabulary. This is reusable substrate (spec 251
+ *        "People groups are excluded").
+ * SDR-06 SANITIZED metadata only. `metadataURI` + `conceptHash` carry NEUTRAL,
+ *        public, non-operational skill vocabulary — never anything that implies
+ *        private operational data about who holds the skill or where it is used.
+ *        The agent↔skill association is an OFF-chain vault credential (spec 251).
+ * SDR-07 NO on-chain skill↔geo mapping. This registry holds skills only and has
+ *        ZERO reference to GeoFeatureRegistry (or any geo id). A "skill X in
+ *        region Y" co-occurrence is an off-chain claim/credential, never an
+ *        on-chain link between the two definition registries.
+ *
+ * Ported from smart-agent `SkillDefinitionRegistry`; diverges per spec 251 (AP
+ * auth model, C-box-anchored kinds, no `.skill` name binding in v1).
+ */
+contract SkillDefinitionRegistry {
+    // ─── C-box skill-kind codelist (keccak of the cbox vocabulary URIs) ──
+    //   Concept URIs are declared in packages/ontology cbox/skill-vocabulary.ttl
+    //   (scheme aps:skillKind); the lockstep gate asserts these equal keccak of
+    //   the declared skos:Concept URIs (ADR-0009).
+    /// @dev A leaf skill in a controlled taxonomy (e.g. an OASF leaf).
+    bytes32 public constant KIND_LEAF = keccak256(bytes("https://agenticprimitives.dev/ns/skill#Leaf"));
+    /// @dev A domain/grouping concept (a non-leaf category).
+    bytes32 public constant KIND_DOMAIN = keccak256(bytes("https://agenticprimitives.dev/ns/skill#Domain"));
+    /// @dev A steward-defined custom skill outside the controlled set.
+    bytes32 public constant KIND_CUSTOM = keccak256(bytes("https://agenticprimitives.dev/ns/skill#Custom"));
+
+    // ─── Errors ─────────────────────────────────────────────────────────
+    error NotSteward();
+    error SkillNotFound();
+    error EmptyMetadata();
+    error EmptyId();
+
+    // ─── Storage ────────────────────────────────────────────────────────
+    struct SkillRecord {
+        bytes32 skillId; // stable id across versions
+        uint64 version; // monotonic per skillId (1-based; 0 = absent)
+        address stewardAccount; // governing steward SA
+        bytes32 skillKind; // C-box kind codelist value
+        bytes32 conceptHash; // keccak of canonical SKOS prefLabel + ancestors
+        bytes32 ontologyMerkleRoot; // anchors the RDF/SKOS expansion (off chain)
+        bytes32 predecessorRoot; // prior version's ontologyMerkleRoot (0 for v1)
+        string metadataURI; // ipfs://… or https://… JSON-LD blob
+        uint64 validAfter; // 0 = since inception
+        uint64 validUntil; // 0 = indefinite
+        bool active;
+        uint64 registeredAt;
+    }
+
+    /// @dev skillId => version => record.
+    mapping(bytes32 => mapping(uint64 => SkillRecord)) private _records;
+    /// @dev skillId => latest version (0 = unknown).
+    mapping(bytes32 => uint64) public latestVersion;
+    bytes32[] private _allSkills;
+
+    // ─── Events ─────────────────────────────────────────────────────────
+    event SkillPublished(
+        bytes32 indexed skillId,
+        uint64 indexed version,
+        address indexed steward,
+        bytes32 skillKind,
+        bytes32 conceptHash,
+        bytes32 ontologyMerkleRoot,
+        bytes32 predecessorRoot,
+        string metadataURI
+    );
+    event SkillDeactivated(bytes32 indexed skillId, uint64 version);
+    event SkillValidityChanged(bytes32 indexed skillId, uint64 version, uint64 validAfter, uint64 validUntil);
+
+    // ─── Publish ────────────────────────────────────────────────────────
+    struct PublishInput {
+        bytes32 skillId;
+        bytes32 skillKind;
+        address stewardAccount;
+        bytes32 conceptHash;
+        bytes32 ontologyMerkleRoot;
+        string metadataURI;
+        uint64 validAfter;
+        uint64 validUntil;
+    }
+
+    /// @notice Publish a new skill definition, or a new version of an existing one.
+    function publish(PublishInput calldata p) external returns (uint64 version) {
+        if (p.skillId == bytes32(0)) revert EmptyId();
+        if (bytes(p.metadataURI).length == 0) revert EmptyMetadata();
+        // SDR-02 — only the steward SA, acting through its own execute() path.
+        if (msg.sender != p.stewardAccount) revert NotSteward();
+
+        uint64 prevVer = latestVersion[p.skillId];
+        if (prevVer != 0 && _records[p.skillId][prevVer].stewardAccount != p.stewardAccount) {
+            // SDR-03 — a new version must come from the SAME steward.
+            revert NotSteward();
+        }
+
+        version = prevVer + 1;
+        bytes32 predecessorRoot = prevVer == 0 ? bytes32(0) : _records[p.skillId][prevVer].ontologyMerkleRoot;
+
+        _records[p.skillId][version] = SkillRecord({
+            skillId: p.skillId,
+            version: version,
+            stewardAccount: p.stewardAccount,
+            skillKind: p.skillKind,
+            conceptHash: p.conceptHash,
+            ontologyMerkleRoot: p.ontologyMerkleRoot,
+            predecessorRoot: predecessorRoot,
+            metadataURI: p.metadataURI,
+            validAfter: p.validAfter,
+            validUntil: p.validUntil,
+            active: true,
+            registeredAt: uint64(block.timestamp)
+        });
+        latestVersion[p.skillId] = version;
+        if (prevVer == 0) _allSkills.push(p.skillId);
+
+        emit SkillPublished(p.skillId, version, p.stewardAccount, p.skillKind, p.conceptHash, p.ontologyMerkleRoot, predecessorRoot, p.metadataURI);
+    }
+
+    /// @notice Deactivate the latest version (history is preserved).
+    function deactivate(bytes32 skillId) external {
+        uint64 v = latestVersion[skillId];
+        if (v == 0) revert SkillNotFound();
+        SkillRecord storage r = _records[skillId][v];
+        if (msg.sender != r.stewardAccount) revert NotSteward();
+        r.active = false;
+        emit SkillDeactivated(skillId, v);
+    }
+
+    /// @notice Update the validity window of a published version.
+    function setValidity(bytes32 skillId, uint64 version, uint64 validAfter, uint64 validUntil) external {
+        SkillRecord storage r = _records[skillId][version];
+        if (r.version == 0) revert SkillNotFound();
+        if (msg.sender != r.stewardAccount) revert NotSteward();
+        r.validAfter = validAfter;
+        r.validUntil = validUntil;
+        emit SkillValidityChanged(skillId, version, validAfter, validUntil);
+    }
+
+    // ─── Views ──────────────────────────────────────────────────────────
+    function getSkill(bytes32 skillId, uint64 version) external view returns (SkillRecord memory) {
+        SkillRecord memory r = _records[skillId][version];
+        if (r.version == 0) revert SkillNotFound();
+        return r;
+    }
+
+    function getLatest(bytes32 skillId) external view returns (SkillRecord memory) {
+        uint64 v = latestVersion[skillId];
+        if (v == 0) revert SkillNotFound();
+        return _records[skillId][v];
+    }
+
+    /// @notice True if `version` of `skillId` exists (used by the claim registry to pin a version).
+    function exists(bytes32 skillId, uint64 version) external view returns (bool) {
+        return _records[skillId][version].version != 0;
+    }
+
+    function allSkills() external view returns (bytes32[] memory) {
+        return _allSkills;
+    }
+}