@agenticprimitives/contracts 0.1.0-alpha.2

package/src/naming/AgentNameRegistry.sol

@@ -0,0 +1,362 @@
+// SPDX-License-Identifier: MIT
+pragma solidity ^0.8.28;
+
+/**
+ * @title AgentNameRegistry
+ * @notice Hierarchical multi-root name registry for Smart Agents.
+ *
+ * Names are keyed by `node` (the ENS-style 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
+ * expiry.
+ *
+ * Adapted from smart-agent (`packages/contracts/src/AgentNameRegistry.sol`,
+ * 359 LOC) with the following simplifications per spec 215 § Phase 3 +
+ * ADR-0006:
+ *
+ *   - **No AgentRelationship dependency.** The smart-agent original
+ *     created a `NAMESPACE_CONTAINS` edge on every register; ADR-0006
+ *     rules that as parallel authority. The parent pointer in
+ *     `_records[node].parent` IS the hierarchy.
+ *
+ *   - **No OpenZeppelin AccessControl / TimelockController.** The owner
+ *     Smart Agent's CustodyPolicy module IS the timelock + RBAC.
+ *     Authorization here is purely `msg.sender == owner` (the Smart
+ *     Agent executes through its CustodyPolicy gate, then calls into
+ *     this contract).
+ *
+ *   - **No multi-owner `isOwner(address)` fallback.** Our AgentAccount
+ *     is ERC-7579 modular with no built-in owner registry; quorum
+ *     belongs to the CustodyPolicy module. The legacy smart-agent path
+ *     `staticcall isOwner(msg.sender)` does not apply.
+ *
+ * Reverse-records (primary names: address → node) ALSO live here
+ * for atomicity; the universal resolver enforces the round-trip
+ * discipline (a primary name only counts when the forward record
+ * agrees).
+ */
+contract AgentNameRegistry {
+    // ─── H7-C.4 / CON-NAMING-001 — root-initializer gate ───────────────
+    //
+    // `initializeRoot` was permissionless: any mempool observer could
+    // front-run the deployer's first `initializeRoot("agent", ...)` and
+    // own `.agent` forever. The fix is to pin the initializer to an
+    // immutable address set at construction; the deploy script performs
+    // both steps in a single transaction so no front-run window exists.
+    //
+    // The role is INITIALIZATION-ONLY. Once a root is initialized, control
+    // belongs to its `rootOwner` (a smart-agent governance address) — the
+    // initializer cannot rotate it.
+    address public immutable initializer;
+
+    // ─── Types ──────────────────────────────────────────────────────
+
+    struct NameRecord {
+        address owner;       // Smart Agent that controls this name
+        address resolver;    // resolver contract for this node's records
+        address subregistry; // 0 = owner-only; non-zero = delegate may also register children
+        bytes32 parent;      // parent namehash; bytes32(0) for roots
+        bytes32 labelhash;   // keccak256(bytes(label))
+        uint64  expiry;      // 0 = no expiry
+        uint64  registeredAt;
+    }
+
+    // ─── Errors ─────────────────────────────────────────────────────
+
+    error NotAuthorized();
+    error NodeAlreadyExists();
+    error NodeNotFound();
+    error ParentNotFound();
+    error NameExpired();
+    error RootAlreadyInitialized();
+    error EmptyLabel();
+    error ZeroOwner();
+    /// @notice H7-C.4 / CON-NAMING-001 — `initializeRoot` may only be called
+    ///         by the immutable `initializer` set at construction. Closes the
+    ///         permissionless-frontrun vector where any mempool observer
+    ///         could claim a TLD before the deployer's first init landed.
+    error NotInitializer(address caller, address initializer);
+
+    // ─── Events ─────────────────────────────────────────────────────
+
+    event RootInitialized(bytes32 indexed rootNode, string label, address indexed owner, bytes32 kind);
+    event NameRegistered(
+        bytes32 indexed node,
+        bytes32 indexed parent,
+        string label,
+        address owner,
+        address resolver,
+        uint64 expiry
+    );
+    event OwnerChanged(bytes32 indexed node, address indexed newOwner);
+    event ResolverChanged(bytes32 indexed node, address indexed resolver);
+    event SubregistryChanged(bytes32 indexed node, address indexed subregistry);
+    event NameRenewed(bytes32 indexed node, uint64 newExpiry);
+    event PrimaryNameSet(address indexed agent, bytes32 indexed node);
+    event PrimaryNameCleared(address indexed agent);
+
+    // ─── Storage ────────────────────────────────────────────────────
+
+    mapping(bytes32 => NameRecord) private _records;
+    mapping(bytes32 => mapping(bytes32 => bytes32)) private _children; // parent => labelhash => childNode
+    mapping(bytes32 => bytes32[]) private _childLabels;                // parent => labelhash[]
+    /// @notice Plain-text label per node — the string that was passed to
+    ///         `initializeRoot` / `register` at registration time.
+    ///         Per spec/222 this enables view-call reverse resolution
+    ///         (universal resolver concatenates parents into the full
+    ///         dotted name) WITHOUT any `eth_getLogs` scan.
+    mapping(bytes32 => string) private _label;
+
+    /// @notice Multi-root registry — `true` iff `node` was initialized via `initializeRoot`.
+    mapping(bytes32 => bool) public isRoot;
+    /// @notice Per-root opaque kind tag (e.g. `keccak256("namespace:Agent")`).
+    mapping(bytes32 => bytes32) public rootKind;
+    /// @notice Lookup root node by ASCII TLD label.
+    mapping(string => bytes32) private _rootByLabel;
+    /// @notice Enumeration of every initialized root.
+    bytes32[] private _allRoots;
+
+    /// @notice Reverse-record: Smart Agent address → primary name node.
+    /// @dev    Forward agreement (resolver-addr == agent) is enforced by
+    ///         the universal resolver, NOT here — keeping registry writes
+    ///         simple. A primary-name claim with no forward agreement
+    ///         returns null on reverseResolve via the resolver.
+    mapping(address => bytes32) private _primaryName;
+
+    /// @notice Default kind tags downstream callers may use.
+    bytes32 public constant KIND_AGENT = keccak256("namespace:Agent");
+
+    // ─── 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_) {
+        if (initializer_ == address(0)) revert ZeroOwner();
+        initializer = initializer_;
+    }
+
+    // ─── Namehash Helpers ───────────────────────────────────────────
+
+    /// @notice Pure namehash for a top-level label (parent = bytes32(0)).
+    function namehashRoot(string memory label) public pure returns (bytes32) {
+        return keccak256(abi.encodePacked(bytes32(0), keccak256(bytes(label))));
+    }
+
+    /// @notice Backward-compat helper returning `namehash("agent")` — SDK
+    ///         callers use this to derive `.agent` without re-implementing
+    ///         the algorithm.
+    function AGENT_ROOT() public pure returns (bytes32) {
+        return keccak256(abi.encodePacked(bytes32(0), keccak256(bytes("agent"))));
+    }
+
+    // ─── Root Initialization (multi-root) ───────────────────────────
+
+    /**
+     * @notice Initialize a TLD root.
+     * @param label             TLD label without leading dot (e.g. "agent").
+     * @param rootOwner         Address that will own the root (Smart Agent or deployer EOA for bootstrap).
+     * @param resolverContract  Default resolver for the root (0 = none).
+     * @param kind              Opaque tag; SDK / downstream binders use it to dispatch.
+     */
+    function initializeRoot(
+        string calldata label,
+        address rootOwner,
+        address resolverContract,
+        bytes32 kind
+    ) external returns (bytes32 rootNode) {
+        // H7-C.4 / CON-NAMING-001: only the immutable initializer may claim a
+        // TLD. The deploy script bundles deploy+init in one transaction so no
+        // frontrun window exists.
+        if (msg.sender != initializer) revert NotInitializer(msg.sender, initializer);
+        if (bytes(label).length == 0) revert EmptyLabel();
+        if (rootOwner == address(0)) revert ZeroOwner();
+        rootNode = namehashRoot(label);
+        if (_records[rootNode].registeredAt != 0) revert RootAlreadyInitialized();
+
+        _records[rootNode] = NameRecord({
+            owner: rootOwner,
+            resolver: resolverContract,
+            subregistry: rootOwner,
+            parent: bytes32(0),
+            labelhash: keccak256(bytes(label)),
+            expiry: 0,
+            registeredAt: uint64(block.timestamp)
+        });
+
+        isRoot[rootNode] = true;
+        rootKind[rootNode] = kind;
+        _rootByLabel[label] = rootNode;
+        _allRoots.push(rootNode);
+        _label[rootNode] = label;
+
+        emit RootInitialized(rootNode, label, rootOwner, kind);
+    }
+
+    /// @notice Enumerate every initialized root.
+    function getRoots() external view returns (bytes32[] memory) {
+        return _allRoots;
+    }
+
+    /// @notice Look up a root by its TLD label. Returns `bytes32(0)` if not initialized.
+    function rootByLabel(string calldata label) external view returns (bytes32) {
+        return _rootByLabel[label];
+    }
+
+    // ─── Registration ───────────────────────────────────────────────
+
+    /**
+     * @notice Register a child name under a parent.
+     * @dev    Caller must be parent's owner OR parent's subregistry delegate.
+     *         Caller's Smart Agent is responsible for routing through its
+     *         CustodyPolicy before this call lands; this function trusts
+     *         `msg.sender` to be the gated entity.
+     */
+    function register(
+        bytes32 parentNode,
+        string calldata label,
+        address newOwner,
+        address resolverContract,
+        uint64 expiry
+    ) external returns (bytes32 childNode) {
+        if (bytes(label).length == 0) revert EmptyLabel();
+        if (newOwner == address(0)) revert ZeroOwner();
+        _requireParentAuth(parentNode);
+        _requireNotExpired(parentNode);
+
+        bytes32 lh = keccak256(bytes(label));
+        childNode = keccak256(abi.encodePacked(parentNode, lh));
+        if (_records[childNode].registeredAt != 0) revert NodeAlreadyExists();
+
+        _records[childNode] = NameRecord({
+            owner: newOwner,
+            resolver: resolverContract,
+            subregistry: address(0),
+            parent: parentNode,
+            labelhash: lh,
+            expiry: expiry,
+            registeredAt: uint64(block.timestamp)
+        });
+
+        _children[parentNode][lh] = childNode;
+        _childLabels[parentNode].push(lh);
+        _label[childNode] = label;
+
+        emit NameRegistered(childNode, parentNode, label, newOwner, resolverContract, expiry);
+    }
+
+    /**
+     * @notice Backfill a label for a node registered before per-node
+     *         label storage shipped (pre-spec/222 deployments).
+     *         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 {
+        _requireNodeAuth(node);
+        if (bytes(label_).length == 0) revert EmptyLabel();
+        if (keccak256(bytes(label_)) != _records[node].labelhash) revert NotAuthorized();
+        if (bytes(_label[node]).length != 0) revert NotAuthorized();
+        _label[node] = label_;
+    }
+
+    // ─── Setters ────────────────────────────────────────────────────
+
+    function setOwner(bytes32 node, address newOwner) external {
+        _requireNodeAuth(node);
+        if (newOwner == address(0)) revert ZeroOwner();
+        _records[node].owner = newOwner;
+        emit OwnerChanged(node, newOwner);
+    }
+
+    function setResolver(bytes32 node, address resolverContract) external {
+        _requireNodeAuth(node);
+        _records[node].resolver = resolverContract;
+        emit ResolverChanged(node, resolverContract);
+    }
+
+    function setSubregistry(bytes32 node, address subregistryContract) external {
+        _requireNodeAuth(node);
+        _records[node].subregistry = subregistryContract;
+        emit SubregistryChanged(node, subregistryContract);
+    }
+
+    function renew(bytes32 node, uint64 newExpiry) external {
+        _requireNodeAuth(node);
+        _records[node].expiry = newExpiry;
+        emit NameRenewed(node, newExpiry);
+    }
+
+    /**
+     * @notice Set the reverse-record (primary name) for `msg.sender`.
+     * @dev    Anyone may set their own primary name; the registry does
+     *         NOT verify the forward record points back here. The
+     *         universal resolver enforces the round-trip on reads.
+     */
+    function setPrimaryName(bytes32 node) external {
+        if (node != bytes32(0) && _records[node].registeredAt == 0) revert NodeNotFound();
+        _primaryName[msg.sender] = node;
+        if (node == bytes32(0)) emit PrimaryNameCleared(msg.sender);
+        else emit PrimaryNameSet(msg.sender, node);
+    }
+
+    /// @notice Read the unverified primary-name node for `agent`. The
+    ///         universal resolver MUST round-trip this against the
+    ///         resolver's `addr(node)`.
+    function primaryName(address agent) external view returns (bytes32) {
+        return _primaryName[agent];
+    }
+
+    // ─── Queries ────────────────────────────────────────────────────
+
+    function owner(bytes32 node) external view returns (address) { return _records[node].owner; }
+    function resolver(bytes32 node) external view returns (address) { return _records[node].resolver; }
+    function subregistry(bytes32 node) external view returns (address) { return _records[node].subregistry; }
+    function parent(bytes32 node) external view returns (bytes32) { return _records[node].parent; }
+    function labelhash(bytes32 node) external view returns (bytes32) { return _records[node].labelhash; }
+    function expiry(bytes32 node) external view returns (uint64) { return _records[node].expiry; }
+    function recordExists(bytes32 node) external view returns (bool) { return _records[node].registeredAt != 0; }
+    function registeredAt(bytes32 node) external view returns (uint64) { return _records[node].registeredAt; }
+
+    function childNode(bytes32 parentNode, bytes32 lh) external view returns (bytes32) {
+        return _children[parentNode][lh];
+    }
+    function childCount(bytes32 parentNode) external view returns (uint256) {
+        return _childLabels[parentNode].length;
+    }
+    function childLabelhashes(bytes32 parentNode) external view returns (bytes32[] memory) {
+        return _childLabels[parentNode];
+    }
+    function isExpired(bytes32 node) public view returns (bool) {
+        uint64 exp = _records[node].expiry;
+        return exp != 0 && block.timestamp > exp;
+    }
+
+    /// @notice Plain-text label for `node` (the string that was passed
+    ///         to register / initializeRoot). Empty for un-backfilled
+    ///         pre-spec/222 records.
+    function label(bytes32 node) external view returns (string memory) {
+        return _label[node];
+    }
+
+    // ─── Auth ───────────────────────────────────────────────────────
+
+    function _requireNodeAuth(bytes32 node) internal view {
+        NameRecord storage r = _records[node];
+        if (r.registeredAt == 0) revert NodeNotFound();
+        if (msg.sender != r.owner) revert NotAuthorized();
+    }
+
+    function _requireParentAuth(bytes32 parentNode) internal view {
+        NameRecord storage r = _records[parentNode];
+        if (r.registeredAt == 0) revert ParentNotFound();
+        if (msg.sender == r.owner) return;
+        if (r.subregistry != address(0) && msg.sender == r.subregistry) return;
+        revert NotAuthorized();
+    }
+
+    function _requireNotExpired(bytes32 node) internal view {
+        if (isExpired(node)) revert NameExpired();
+    }
+}
+

package/src/naming/AgentNameUniversalResolver.sol

@@ -0,0 +1,210 @@
+// SPDX-License-Identifier: MIT
+pragma solidity ^0.8.28;
+
+import "./AgentNameRegistry.sol";
+import "./AgentNameAttributeResolver.sol";
+import "./AgentNamePredicates.sol";
+
+/**
+ * @title AgentNameUniversalResolver
+ * @notice Read-only aggregator for the agent-naming registry +
+ *         ontology-backed AttributeResolver.
+ *
+ * Combines the registry (who owns what node) with the per-node typed
+ * resolver (what records are stored) into a single, gas-efficient read
+ * surface. The SDK targets this contract for `resolveName`,
+ * `reverseResolve`, and typed multi-record reads.
+ *
+ * Round-trip discipline (security invariant from spec 215 § 10):
+ *   `resolveName(reverseResolve(addr)) == addr` MUST hold. We enforce
+ *   this on the read side; `AgentNameRegistry.setPrimaryName` stays
+ *   permissive so callers can sequence forward + reverse writes
+ *   independently.
+ */
+contract AgentNameUniversalResolver {
+    AgentNameRegistry public immutable REGISTRY;
+
+    constructor(AgentNameRegistry registry) {
+        REGISTRY = registry;
+    }
+
+    // ─── Forward resolution ─────────────────────────────────────────
+
+    /**
+     * @notice Resolve `node` to its Smart Agent address.
+     *
+     * Lookup order:
+     *   1. resolver.getAddress(node, ATL_ADDR) — explicit forward record.
+     *   2. REGISTRY.owner(node) — fallback when ATL_ADDR is unset.
+     *
+     * Returns `address(0)` for unregistered nodes (does NOT revert) so
+     * a multi-call can probe many names without partial reverts.
+     */
+    function resolveName(bytes32 node) external view returns (address) {
+        if (!REGISTRY.recordExists(node)) return address(0);
+        address resolverAddr = REGISTRY.resolver(node);
+        if (resolverAddr != address(0)) {
+            try AgentNameAttributeResolver(resolverAddr).getAddress(node, AgentNamePredicates.ATL_ADDR) returns (address resolved) {
+                if (resolved != address(0)) return resolved;
+            } catch {}
+        }
+        return REGISTRY.owner(node);
+    }
+
+    /// @notice Resolve a single string-valued record by predicate id.
+    function resolveString(bytes32 node, bytes32 predicate) external view returns (string memory) {
+        address resolverAddr = REGISTRY.resolver(node);
+        if (resolverAddr == address(0)) return "";
+        try AgentNameAttributeResolver(resolverAddr).getString(node, predicate) returns (string memory value) {
+            return value;
+        } catch {
+            return "";
+        }
+    }
+
+    /// @notice Resolve a single bytes32-valued record by predicate id.
+    function resolveBytes32(bytes32 node, bytes32 predicate) external view returns (bytes32) {
+        address resolverAddr = REGISTRY.resolver(node);
+        if (resolverAddr == address(0)) return bytes32(0);
+        try AgentNameAttributeResolver(resolverAddr).getBytes32(node, predicate) returns (bytes32 value) {
+            return value;
+        } catch {
+            return bytes32(0);
+        }
+    }
+
+    /// @notice Resolve a single address-valued record by predicate id.
+    function resolveAddress(bytes32 node, bytes32 predicate) external view returns (address) {
+        address resolverAddr = REGISTRY.resolver(node);
+        if (resolverAddr == address(0)) return address(0);
+        try AgentNameAttributeResolver(resolverAddr).getAddress(node, predicate) returns (address value) {
+            return value;
+        } catch {
+            return address(0);
+        }
+    }
+
+    /// @notice Multi-read of N string records in a single static-call.
+    function resolveStringBatch(bytes32 node, bytes32[] calldata predicates)
+        external
+        view
+        returns (string[] memory values)
+    {
+        values = new string[](predicates.length);
+        address resolverAddr = REGISTRY.resolver(node);
+        if (resolverAddr == address(0)) return values;
+        for (uint256 i = 0; i < predicates.length; i++) {
+            try AgentNameAttributeResolver(resolverAddr).getString(node, predicates[i]) returns (string memory value) {
+                values[i] = value;
+            } catch {
+                values[i] = "";
+            }
+        }
+    }
+
+    // ─── Reverse resolution (round-trip enforced) ───────────────────
+
+    /**
+     * @notice Resolve a Smart Agent address back to its primary-name node.
+     * @return node The primary-name node, OR `bytes32(0)` when no primary
+     *              name is set OR when the forward record does not point
+     *              back to `agent` (round-trip fails — squat protection).
+     */
+    function reverseResolve(address agent) external view returns (bytes32 node) {
+        node = REGISTRY.primaryName(agent);
+        if (node == bytes32(0)) return bytes32(0);
+        if (!REGISTRY.recordExists(node)) return bytes32(0);
+        address forward = _resolveNameView(node);
+        if (forward != agent) return bytes32(0);
+        return node;
+    }
+
+    /**
+     * @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
+     *         reconstruction in the SDK, no event indexer required.
+     *
+     *         Walks `parent(node)` up the registry, reading `label(node)`
+     *         at each level, joining with `.`. All view calls. Returns
+     *         `""` when (a) no primary set, (b) round-trip fails (squat
+     *         protection), or (c) any node along the parent chain has
+     *         no on-chain label string (pre-spec/222 backfill not done).
+     */
+    function reverseResolveString(address agent) external view returns (string memory) {
+        bytes32 node = REGISTRY.primaryName(agent);
+        if (node == bytes32(0)) return "";
+        if (!REGISTRY.recordExists(node)) return "";
+        if (_resolveNameView(node) != agent) return "";
+        return _composeName(node);
+    }
+
+    /**
+     * @notice Compose the full dotted name string for `node` by walking
+     *         the parent chain. Generalizes: works for ANY registered
+     *         node, not just an agent's primary. Returns `""` if any
+     *         label in the chain is missing on chain.
+     */
+    function nameOf(bytes32 node) external view returns (string memory) {
+        if (node == bytes32(0)) return "";
+        if (!REGISTRY.recordExists(node)) return "";
+        return _composeName(node);
+    }
+
+    function _composeName(bytes32 startNode) internal view returns (string memory) {
+        // Collect labels walking up to root. Bounded depth = 10 to
+        // match the SDK's previous _reconstructName cap (no demo path
+        // exceeds 4 — alice7.demo.agent is 3).
+        string[10] memory labels;
+        uint256 depth = 0;
+        bytes32 cur = startNode;
+        while (cur != bytes32(0) && depth < 10) {
+            string memory lbl = REGISTRY.label(cur);
+            if (bytes(lbl).length == 0) return "";
+            labels[depth] = lbl;
+            cur = REGISTRY.parent(cur);
+            unchecked { depth++; }
+        }
+        if (depth == 0) return "";
+
+        // Concatenate labels[0..depth-1] with '.' separators.
+        uint256 totalLen = depth - 1; // for the dots
+        for (uint256 i = 0; i < depth; i++) totalLen += bytes(labels[i]).length;
+        bytes memory out = new bytes(totalLen);
+        uint256 pos = 0;
+        for (uint256 i = 0; i < depth; i++) {
+            bytes memory lbl = bytes(labels[i]);
+            for (uint256 j = 0; j < lbl.length; j++) out[pos++] = lbl[j];
+            if (i + 1 < depth) out[pos++] = 0x2e; // '.'
+        }
+        return string(out);
+    }
+
+    function _resolveNameView(bytes32 node) internal view returns (address) {
+        address resolverAddr = REGISTRY.resolver(node);
+        if (resolverAddr != address(0)) {
+            try AgentNameAttributeResolver(resolverAddr).getAddress(node, AgentNamePredicates.ATL_ADDR) returns (address resolved) {
+                if (resolved != address(0)) return resolved;
+            } catch {}
+        }
+        return REGISTRY.owner(node);
+    }
+
+    // ─── Directory listing ──────────────────────────────────────────
+
+    /// @notice List a node's children and their resolved addresses.
+    function getChildren(bytes32 parentNode)
+        external
+        view
+        returns (bytes32[] memory childNodes, address[] memory owners)
+    {
+        bytes32[] memory labelhashes = REGISTRY.childLabelhashes(parentNode);
+        childNodes = new bytes32[](labelhashes.length);
+        owners = new address[](labelhashes.length);
+        for (uint256 i = 0; i < labelhashes.length; i++) {
+            bytes32 child = REGISTRY.childNode(parentNode, labelhashes[i]);
+            childNodes[i] = child;
+            owners[i] = REGISTRY.owner(child);
+        }
+    }
+}

package/src/naming/PermissionlessSubregistry.sol

@@ -0,0 +1,98 @@
+// SPDX-License-Identifier: MIT
+pragma solidity ^0.8.28;
+
+import "./AgentNameRegistry.sol";
+
+/**
+ * @title PermissionlessSubregistry
+ * @notice Anyone-can-register subregistry for a single parent name.
+ *
+ * Design:
+ *   - At deploy: bound to a specific `PARENT_NODE` + a default
+ *     resolver address. The parent's owner (typically the deployer
+ *     during demo bootstrap) MUST call
+ *     `AgentNameRegistry.setSubregistry(PARENT_NODE, address(this))`
+ *     once after deploy to grant this contract authority to register
+ *     children under `PARENT_NODE`.
+ *
+ *   - Any caller (EOA or Smart Agent) may invoke `register(label,
+ *     newOwner)` to claim `<label>.<parent>`. The registered child
+ *     is owned by `newOwner` (caller decides — typically themselves
+ *     OR a PSA they control).
+ *
+ * Spam prevention:
+ *   - Minimum label length (`MIN_LABEL_LENGTH = 3`).
+ *   - One name per caller `msg.sender` (`claimedBy[caller] != 0`
+ *     reverts). Designed for demos / sybil-resistant rollups; a
+ *     production subregistry would gate on a registration fee or a
+ *     governance allowlist instead.
+ *
+ * Authority model:
+ *   - The contract calls `REGISTRY.register(...)`; the registry sees
+ *     `msg.sender == address(this)` AND `r.subregistry == this` and
+ *     authorizes the registration. The new child's owner is the
+ *     caller-supplied `newOwner` argument — NOT this contract.
+ *   - Anyone wanting to update records on the new child does so
+ *     through whatever authority `newOwner` represents (EOA wallet,
+ *     PSA CustodyPolicy quorum, etc.).
+ */
+contract PermissionlessSubregistry {
+    AgentNameRegistry public immutable REGISTRY;
+    bytes32 public immutable PARENT_NODE;
+    address public immutable DEFAULT_RESOLVER;
+
+    uint256 public constant MIN_LABEL_LENGTH = 3;
+
+    /// @notice msg.sender → the child node they've already claimed.
+    mapping(address => bytes32) public claimedBy;
+    /// @notice Total claims served by this subregistry instance.
+    uint256 public claimCount;
+
+    event NameClaimed(
+        address indexed caller,
+        bytes32 indexed childNode,
+        string label,
+        address newOwner
+    );
+
+    error AlreadyClaimed(bytes32 existingNode);
+    error LabelTooShort();
+    error EmptyLabel();
+    error ZeroNewOwner();
+
+    constructor(AgentNameRegistry registry, bytes32 parentNode, address defaultResolver) {
+        REGISTRY = registry;
+        PARENT_NODE = parentNode;
+        DEFAULT_RESOLVER = defaultResolver;
+    }
+
+    /**
+     * @notice Claim `<label>.<parent>` for `newOwner`. Reverts if the
+     *         caller has already claimed a name through this
+     *         subregistry, OR if the label fails the minimum-length
+     *         guard, OR if the registry rejects the registration
+     *         (e.g. label already taken).
+     *
+     *         The caller pays gas. The contract does NOT collect a
+     *         fee — fee gating belongs in a different subregistry
+     *         shape if needed.
+     */
+    function register(string calldata label, address newOwner) external 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);
+        childNode = REGISTRY.register(PARENT_NODE, label, newOwner, DEFAULT_RESOLVER, 0);
+        claimedBy[msg.sender] = childNode;
+        unchecked {
+            claimCount += 1;
+        }
+        emit NameClaimed(msg.sender, childNode, label, newOwner);
+    }
+
+    /// @notice Has `caller` already claimed a name? Convenience read.
+    function hasClaimed(address caller) external view returns (bool) {
+        return claimedBy[caller] != bytes32(0);
+    }
+}