@agenticprimitives/agent-naming 0.1.0-alpha.2

package/dist/records.js

@@ -0,0 +1,193 @@
+/**
+ * Predicate ids + typed record encoders/decoders for the on-chain
+ * ontology-backed resolver (ADR-0009 / NS Phase 3 pivot).
+ *
+ * Subpath: `@agenticprimitives/agent-naming/records`.
+ *
+ * The `AgentNameAttributeResolver` (packages/contracts/src/naming/) inherits
+ * `AttributeStorage` and validates every write against the
+ * `OntologyTermRegistry`. Predicate keys are `bytes32` ids
+ * (`keccak256("atl:displayName")` etc.), not strings; this module is
+ * the canonical TS mirror of those ids — kept in lockstep with
+ * `packages/contracts/src/naming/AgentNamePredicates.sol`.
+ *
+ * Datatype binding:
+ *   - `addr`, `custodyPolicy`                 → on-chain `address`
+ *   - `agentKind`, `metadataHash`,
+ *     `passkeyCredentialDigest`              → on-chain `bytes32`
+ *   - `displayName`, `a2aEndpoint`,
+ *     `mcpEndpoint`, `metadataUri`,
+ *     `nativeId`                              → on-chain `string`
+ *
+ * The encoder routes each predicate to its typed setter; the decoder
+ * routes each predicate to its typed getter. Unknown predicates are
+ * dropped on decode (fail-closed on read); encoders refuse unknown
+ * predicates (fail-loud on write).
+ */
+import { keccak256, toHex } from 'viem';
+// ─── Predicate ids (mirror AgentNamePredicates.sol) ─────────────────
+/**
+ * keccak256 of the `atl:*` CURIE. Computed at module load. These
+ * MUST equal the `AgentNamePredicates.ATL_*` constants in the
+ * Solidity library — verified by `predicates.test.ts` golden vectors.
+ */
+function _predId(curie) {
+    return keccak256(toHex(curie));
+}
+export const PREDICATE_ID = {
+    addr: _predId('atl:addr'),
+    agentKind: _predId('atl:agentKind'),
+    displayName: _predId('atl:displayName'),
+    a2aEndpoint: _predId('atl:a2aEndpoint'),
+    mcpEndpoint: _predId('atl:mcpEndpoint'),
+    metadataUri: _predId('atl:metadataURI'),
+    metadataHash: _predId('atl:metadataHash'),
+    passkeyCredentialDigest: _predId('atl:passkeyCredentialDigest'),
+    custodyPolicy: _predId('atl:custodyPolicy'),
+    nativeId: _predId('atl:nativeId'),
+};
+// ─── Enum value ids (mirror AgentNamePredicates.sol AGENT_KIND_*) ──
+export const AGENT_KIND_ID = {
+    person: _predId('person'),
+    org: _predId('org'),
+    service: _predId('service'),
+};
+const KNOWN_AGENT_KINDS = new Set([
+    'person',
+    'org',
+    'service',
+]);
+// ─── Class + enum-set ids ──────────────────────────────────────────
+/** `keccak256("atl:AgentName")` — the ShapeRegistry class id. */
+export const CLASS_AGENT_NAME = _predId('atl:AgentName');
+/** `keccak256("atl:AgentKindEnum")` — the enum-set id bound to `atl:agentKind`. */
+export const AGENT_KIND_ENUM = _predId('atl:AgentKindEnum');
+// ─── CAIP-10 namespace allowlist (ADR-0008) ────────────────────────
+/**
+ * Phase 1 CAIP-10 namespace allowlist for `nativeId`. Strict on
+ * encode (validate-at-write), permissive on decode (forward-compat).
+ */
+export const CAIP10_NAMESPACE_ALLOWLIST = new Set([
+    'eip155',
+    'hedera',
+    'solana',
+]);
+const CAIP10_GRAMMAR = /^([-a-z0-9]{3,8}):([-_a-zA-Z0-9]{1,32}):([-.%a-zA-Z0-9]{1,128})$/;
+/**
+ * Encode the typed `AgentNameRecords` bundle into per-predicate
+ * encoded-call args. Caller dispatches each to the resolver's typed
+ * `setXxxAttribute(node, predicate, value)` setter.
+ */
+export function encodeRecords(records) {
+    const out = [];
+    if (records.addr !== undefined) {
+        out.push({ predicate: PREDICATE_ID.addr, datatype: 'address', value: _validateAddress(records.addr) });
+    }
+    if (records.agentKind !== undefined) {
+        out.push({ predicate: PREDICATE_ID.agentKind, datatype: 'bytes32', value: _encodeAgentKind(records.agentKind) });
+    }
+    if (records.displayName !== undefined) {
+        out.push({ predicate: PREDICATE_ID.displayName, datatype: 'string', value: records.displayName });
+    }
+    if (records.a2aEndpoint !== undefined) {
+        out.push({ predicate: PREDICATE_ID.a2aEndpoint, datatype: 'string', value: records.a2aEndpoint });
+    }
+    if (records.mcpEndpoint !== undefined) {
+        out.push({ predicate: PREDICATE_ID.mcpEndpoint, datatype: 'string', value: records.mcpEndpoint });
+    }
+    if (records.metadataUri !== undefined) {
+        out.push({ predicate: PREDICATE_ID.metadataUri, datatype: 'string', value: records.metadataUri });
+    }
+    if (records.metadataHash !== undefined) {
+        out.push({ predicate: PREDICATE_ID.metadataHash, datatype: 'bytes32', value: _validateBytes32(records.metadataHash) });
+    }
+    if (records.passkeyCredentialDigest !== undefined) {
+        out.push({ predicate: PREDICATE_ID.passkeyCredentialDigest, datatype: 'bytes32', value: _validateBytes32(records.passkeyCredentialDigest) });
+    }
+    if (records.custodyPolicy !== undefined) {
+        out.push({ predicate: PREDICATE_ID.custodyPolicy, datatype: 'address', value: _validateAddress(records.custodyPolicy) });
+    }
+    if (records.nativeId !== undefined) {
+        out.push({ predicate: PREDICATE_ID.nativeId, datatype: 'string', value: _encodeNativeId(records.nativeId) });
+    }
+    return out;
+}
+export function decodeRecords(input) {
+    const out = {};
+    const addr = input.addresses[PREDICATE_ID.addr];
+    if (addr)
+        out.addr = addr;
+    const kind = input.bytes32s[PREDICATE_ID.agentKind];
+    if (kind) {
+        const k = _decodeAgentKind(kind);
+        if (k)
+            out.agentKind = k;
+    }
+    const displayName = input.strings[PREDICATE_ID.displayName];
+    if (displayName)
+        out.displayName = displayName;
+    const a2aEndpoint = input.strings[PREDICATE_ID.a2aEndpoint];
+    if (a2aEndpoint)
+        out.a2aEndpoint = a2aEndpoint;
+    const mcpEndpoint = input.strings[PREDICATE_ID.mcpEndpoint];
+    if (mcpEndpoint)
+        out.mcpEndpoint = mcpEndpoint;
+    const metadataUri = input.strings[PREDICATE_ID.metadataUri];
+    if (metadataUri)
+        out.metadataUri = metadataUri;
+    const metadataHash = input.bytes32s[PREDICATE_ID.metadataHash];
+    if (metadataHash)
+        out.metadataHash = metadataHash;
+    const digest = input.bytes32s[PREDICATE_ID.passkeyCredentialDigest];
+    if (digest)
+        out.passkeyCredentialDigest = digest;
+    const custodyPolicy = input.addresses[PREDICATE_ID.custodyPolicy];
+    if (custodyPolicy)
+        out.custodyPolicy = custodyPolicy;
+    const nativeId = input.strings[PREDICATE_ID.nativeId];
+    if (nativeId)
+        out.nativeId = nativeId;
+    return out;
+}
+// ─── Internal validators ───────────────────────────────────────────
+function _validateAddress(value) {
+    if (!/^0x[0-9a-fA-F]{40}$/.test(value)) {
+        throw new Error(`[agent-naming/records] expected a 20-byte hex address (got "${value}")`);
+    }
+    return value.toLowerCase();
+}
+function _validateBytes32(value) {
+    if (!/^0x[0-9a-fA-F]{64}$/.test(value)) {
+        throw new Error(`[agent-naming/records] expected a 32-byte hex value (got "${value}")`);
+    }
+    return value.toLowerCase();
+}
+function _encodeAgentKind(value) {
+    if (!KNOWN_AGENT_KINDS.has(value)) {
+        throw new Error(`[agent-naming/records] agent-kind must be one of person|org|service (treasury is a service subtype, set via the profile, not the agent kind) (got "${value}")`);
+    }
+    return AGENT_KIND_ID[value];
+}
+function _decodeAgentKind(id) {
+    for (const [name, value] of Object.entries(AGENT_KIND_ID)) {
+        if (value.toLowerCase() === id.toLowerCase())
+            return name;
+    }
+    return undefined;
+}
+function _encodeNativeId(value) {
+    const m = CAIP10_GRAMMAR.exec(value);
+    if (!m) {
+        throw new Error(`[agent-naming/records] native-id must match CAIP-10 grammar (got "${value}")`);
+    }
+    const namespace = m[1];
+    if (!CAIP10_NAMESPACE_ALLOWLIST.has(namespace)) {
+        throw new Error(`[agent-naming/records] native-id namespace "${namespace}" not in allowlist ` +
+            `(${[...CAIP10_NAMESPACE_ALLOWLIST].join('|')}). PR to expand if needed.`);
+    }
+    if (namespace === 'eip155') {
+        return `${namespace}:${m[2]}:${m[3].toLowerCase()}`;
+    }
+    return value;
+}
+//# sourceMappingURL=records.js.map

package/dist/records.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"records.js","sourceRoot":"","sources":["../src/records.ts"],"names":[],"mappings":"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"}

package/dist/types.d.ts

@@ -0,0 +1,117 @@
+import type { Address, Hex } from '@agenticprimitives/types';
+/**
+ * Discriminator for the KIND of Smart Agent a name points to. Three kinds only
+ * — mirrors `@agenticprimitives/types` `AgentType` and the on-chain
+ * `AGENT_KIND_ENUM` (must stay in lockstep). `treasury` is NOT an agent kind: a
+ * treasury is a SERVICE agent (`'service'`) distinguished at the profile layer
+ * (`ProfileType: 'treasury'` / `serviceType`; specs 217/225 §6).
+ * Demo UIs use this to render different cards; audit context attaches it so
+ * forensics can filter "all events involving a service agent."
+ */
+export type AgentKind = 'person' | 'org' | 'service';
+/**
+ * The typed bag of records a resolver may hold for a name. Every
+ * field is optional; an unresolved record is `undefined`. Encoders
+ * (`agent-naming/records`) refuse unknown keys; decoders quietly
+ * drop unknown predicates (fail-closed on read, fail-loud on write).
+ *
+ * Spec § 5 — record schema. New predicates must update both the
+ * type and the encoder/decoder pair AND a golden-vector test.
+ */
+export interface AgentNameRecords {
+    /** Forward resolution target — the Smart Agent address this name points to. */
+    addr?: Address;
+    /** Discriminator for UI + audit context. */
+    agentKind?: AgentKind;
+    /** Human-friendly label (may differ from the normalized name). */
+    displayName?: string;
+    /** A2A service endpoint URL. */
+    a2aEndpoint?: string;
+    /** MCP service endpoint URL. */
+    mcpEndpoint?: string;
+    /** Off-chain JSON manifest URL. */
+    metadataUri?: string;
+    /**
+     * Public-safe identifier for the controlling passkey
+     * (`keccak256(credentialId)` — NEVER raw credentialId).
+     * Useful for UI affordances like "this name is controlled by
+     * the same passkey as <other-name>".
+     */
+    passkeyCredentialDigest?: Hex;
+    /** Address of the CustodyPolicy governing the owner Smart Agent. */
+    custodyPolicy?: Address;
+    /**
+     * Off-chain JSON profile content-hash
+     * (matches `agent-profile.profileContentHash(profile)`). Stored
+     * as `bytes32` via the `atl:metadataHash` predicate. Pairs with
+     * `metadataUri` for the standard URI + content-hash anchoring
+     * pattern (ADR-0009 / NS Phase 3 pivot).
+     */
+    metadataHash?: Hex;
+    /**
+     * CAIP-10 chain-agnostic account identifier (e.g.
+     * `eip155:84532:0xabc...`). Per ADR-0008, this enables low-cost
+     * cross-resolver interop with HCS-14 / ERC-8004 indexers without
+     * us generating UAID strings. Consumers MAY derive a UAID locally
+     * by canonical-JSON-hashing this with their own context.
+     */
+    nativeId?: string;
+}
+/**
+ * Input to `AgentNamingClient.registerSubname` — request to register
+ * `<label>.<parent>` under the `parent` namespace.
+ *
+ * The CALLER must own `parent` (verified on-chain by the registry).
+ * Phase 2+ will accept a custody-gated `Signer`; Phase 1 throws
+ * `NS Phase 2` from the client write methods.
+ */
+export interface RegisterSubnameInput {
+    /** Parent name (e.g. `'acme.agent'`). */
+    parent: string;
+    /** Child label (single label, no dots; e.g. `'treasury'`). */
+    label: string;
+    /** Smart Agent address that will own the new subname. */
+    owner: Address;
+    /** Resolver contract address to install for the new name. */
+    resolver?: Address;
+    /** Optional subregistry contract to grant further-down issuance. */
+    subregistry?: Address;
+    /** Optional initial record bundle. */
+    initialRecords?: AgentNameRecords;
+}
+/**
+ * Input to `AgentNamingClient.setPrimaryName` — set the reverse-record
+ * on a Smart Agent address so `reverseResolve(agent)` returns `name`.
+ *
+ * Round-trip verification: the resolver must also have `addr(name) ==
+ * agent`. If forward resolution disagrees, `reverseResolve` returns
+ * null. This prevents primary-name squatting.
+ */
+export interface SetPrimaryNameInput {
+    agent: Address;
+    name: string;
+}
+/** Input to `AgentNamingClient.setAgentRecords`. */
+export interface SetAgentRecordsInput {
+    name: string;
+    records: AgentNameRecords;
+}
+/**
+ * Input to `AgentNamingClient.setSubregistry` — delegate child-name
+ * issuance authority for a subtree to a subregistry contract.
+ * Setting `subregistry = address(0)` reverts to the default registry.
+ */
+export interface SetSubregistryInput {
+    name: string;
+    subregistry: Address;
+}
+/** Read-only client constructor options. */
+export interface AgentNamingClientOpts {
+    rpcUrl: string;
+    chainId: number;
+    /** AgentNameRegistry contract address for this chain. */
+    registry: Address;
+    /** AgentNameUniversalResolver contract address for this chain. */
+    universalResolver: Address;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,GAAG,EAAE,MAAM,0BAA0B,CAAC;AAE7D;;;;;;;;GAQG;AACH,MAAM,MAAM,SAAS,GAAG,QAAQ,GAAG,KAAK,GAAG,SAAS,CAAC;AAErD;;;;;;;;GAQG;AACH,MAAM,WAAW,gBAAgB;IAC/B,+EAA+E;IAC/E,IAAI,CAAC,EAAE,OAAO,CAAC;IACf,4CAA4C;IAC5C,SAAS,CAAC,EAAE,SAAS,CAAC;IACtB,kEAAkE;IAClE,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,gCAAgC;IAChC,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,gCAAgC;IAChC,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,mCAAmC;IACnC,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB;;;;;OAKG;IACH,uBAAuB,CAAC,EAAE,GAAG,CAAC;IAC9B,oEAAoE;IACpE,aAAa,CAAC,EAAE,OAAO,CAAC;IACxB;;;;;;OAMG;IACH,YAAY,CAAC,EAAE,GAAG,CAAC;IACnB;;;;;;OAMG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAED;;;;;;;GAOG;AACH,MAAM,WAAW,oBAAoB;IACnC,yCAAyC;IACzC,MAAM,EAAE,MAAM,CAAC;IACf,8DAA8D;IAC9D,KAAK,EAAE,MAAM,CAAC;IACd,yDAAyD;IACzD,KAAK,EAAE,OAAO,CAAC;IACf,6DAA6D;IAC7D,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,oEAAoE;IACpE,WAAW,CAAC,EAAE,OAAO,CAAC;IACtB,sCAAsC;IACtC,cAAc,CAAC,EAAE,gBAAgB,CAAC;CACnC;AAED;;;;;;;GAOG;AACH,MAAM,WAAW,mBAAmB;IAClC,KAAK,EAAE,OAAO,CAAC;IACf,IAAI,EAAE,MAAM,CAAC;CACd;AAED,oDAAoD;AACpD,MAAM,WAAW,oBAAoB;IACnC,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,gBAAgB,CAAC;CAC3B;AAED;;;;GAIG;AACH,MAAM,WAAW,mBAAmB;IAClC,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,OAAO,CAAC;CACtB;AAED,4CAA4C;AAC5C,MAAM,WAAW,qBAAqB;IACpC,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,EAAE,MAAM,CAAC;IAChB,yDAAyD;IACzD,QAAQ,EAAE,OAAO,CAAC;IAClB,kEAAkE;IAClE,iBAAiB,EAAE,OAAO,CAAC;CAK5B"}

package/dist/types.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=types.js.map

package/dist/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":""}

package/docs/api.md

@@ -0,0 +1,110 @@
+# Agent Naming API
+
+This is the human-readable guide to the public exports in
+`capability.manifest.json`. Keep it in sync with `src/index.ts`.
+
+## Constants
+
+- `AGENT_TLD`: the canonical top-level label, currently `"agent"`.
+- `AgentTld`: type of the canonical top-level label.
+- `ZERO_NODE`: the all-zero ENS root node.
+
+## Name Helpers
+
+- `normalizeAgentName(name)`: returns the canonical lowercase ASCII name or
+  throws `InvalidNameError`.
+- `isValidAgentName(name)`: boolean wrapper around `normalizeAgentName`.
+- `labelhash(label)`: keccak256 hash of a single label.
+- `namehash(name)`: ENS-compatible recursive namehash of a normalized name.
+
+## Client
+
+- `AgentNamingClient`: viem-backed read/write client for registry and resolver
+  contracts.
+- `AgentNamingClientOpts`: constructor options: `rpcUrl`, `chainId`,
+  `registry`, and `universalResolver`.
+- `WriteContext`: per-call wallet context used by write methods.
+
+Read methods:
+
+- `resolveName(name)`: returns the resolved Smart Agent address or `null`.
+- `reverseResolve(agent)`: returns the primary name only when the round-trip
+  check passes.
+- `getRecords(name)`: returns a typed `AgentNameRecords` bundle.
+
+Write methods:
+
+- `registerSubname(input, ctx)`: registers `<label>.<parent>`.
+- `setPrimaryName(input, ctx)`: updates a Smart Agent's primary name.
+- `setAgentRecords(input, ctx)`: writes typed resolver records.
+- `setSubregistry(input, ctx)`: changes child-name issuance authority.
+
+## Core Types
+
+- `AgentKind`: `'person' | 'org' | 'service'` (treasury is a service subtype at the profile layer, not an agent kind — specs 217/225 §6).
+- `AgentNameRecords`: typed resolver record bundle.
+- `RegisterSubnameInput`: registration input for child names.
+- `SetPrimaryNameInput`: reverse-record update input.
+- `SetAgentRecordsInput`: typed resolver-record update input.
+- `SetSubregistryInput`: subregistry update input.
+
+## Errors
+
+- `InvalidNameError`: thrown when normalization rejects a name.
+- `NameNotFoundError`: reserved for callers that need a hard failure instead
+  of `null` on missing names.
+- `UnauthorizedNameOwnerError`: reserved for name-owner auth failures.
+
+## Records Subpath
+
+Import from `@agenticprimitives/agent-naming/records`.
+
+- `PREDICATE_ID`: bytes32 ids for resolver predicates.
+- `AGENT_KIND_ID`: bytes32 ids for `AgentKind` values.
+- `CLASS_AGENT_NAME`: ShapeRegistry class id for an agent name.
+- `AGENT_KIND_ENUM`: enum-set id for `agentKind`.
+- `CAIP10_NAMESPACE_ALLOWLIST`: allowed namespaces for encode-side
+  `nativeId` validation.
+- `encodeRecords(records)`: converts an `AgentNameRecords` bundle to typed
+  predicate writes.
+- `decodeRecords(input)`: converts typed getter output into `AgentNameRecords`.
+- `PredicateName`: union of known record names.
+- `EncodedRecord`: typed encoded record shape.
+- `DecodeInput`: grouped decode input shape.
+
+## Call Builder Subpath
+
+Import from `@agenticprimitives/agent-naming/custody`.
+
+These helpers return `{ to, value, data }` and do not submit transactions.
+
+- `buildRegisterSubnameCall`: encodes registry `register`.
+- `buildRotateNameOwnerCall`: encodes registry `setOwner`.
+- `buildRotateNameResolverCall`: encodes registry `setResolver`.
+- `buildSetSubregistryCall`: encodes registry `setSubregistry`.
+- `buildSetPrimaryNameCall`: encodes registry `setPrimaryName`.
+- `buildSetStringAttributeCall`: encodes resolver `setStringAttribute`.
+- `buildSetAddressAttributeCall`: encodes resolver `setAddressAttribute`.
+- `buildSetBytes32AttributeCall`: encodes resolver `setBytes32Attribute`.
+- `buildRecordCalls`: converts `AgentNameRecords` into resolver call array.
+- `buildSubregistryRegisterCall`: encodes permissionless subregistry
+  registration.
+- `ContractCall`: standard encoded call shape.
+
+## ABIs
+
+- `agentNameRegistryAbi`
+- `agentNameAttributeResolverAbi`
+- `agentNameUniversalResolverAbi`
+- `ontologyTermRegistryAbi`
+- `shapeRegistryAbi`
+- `permissionlessSubregistryAbi`
+
+ABIs are exported for consumers that need direct viem reads or custom
+transaction flows.
+
+## Examples
+
+- [`../examples/basic.ts`](../examples/basic.ts)
+- [`../examples/records.ts`](../examples/records.ts)
+- [`../examples/custody-rotation.ts`](../examples/custody-rotation.ts)

package/docs/concepts.md

@@ -0,0 +1,159 @@
+# Agent Naming Concepts
+
+`@agenticprimitives/agent-naming` registers a **naming facet** for Smart
+Agents: human-readable `.agent` labels and typed discovery records that **point
+at** the canonical Smart Agent address ([ADR-0010](../../../docs/architecture/decisions/0010-smart-agent-canonical-identifier.md)).
+
+This package does **not** own identity. The ERC-4337 Smart Agent address
+(from `@agenticprimitives/agent-account`) is the canonical identifier. Names are
+facet registrations — useful for UX and discovery, never the root authority.
+
+## Canonical Identifier Vs Naming Facet
+
+| Concept | Owner | Example |
+| --- | --- | --- |
+| Canonical identity | `agent-account` | `0xabc…` / `eip155:84532:0xabc…` |
+| Naming facet | `agent-naming` | `alice.agent` → `addr` + `nativeId` records |
+| Profile facet | `agent-profile` | AgentCard at `metadata-uri` |
+| Control credentials | `connect-auth` + `custody` | Passkey / SIWE → custodian on the SA |
+
+Cross-package APIs use `Address` or CAIP-10 `nativeId`, not bare names.
+
+## AgentName
+
+An `AgentName` is a normalized dotted name under `.agent`, such as
+`alice.agent`, `acme.agent`, or `treasury.acme.agent`.
+
+Names are **not** login credentials and **not** CREATE2 salt inputs. A name
+resolves to a Smart Agent address via resolver records. The Smart Agent and its
+custody policy decide who can change that name or its records.
+
+## Label
+
+A label is one segment of a name: `alice`, `acme`, or `treasury`.
+
+Phase 1 labels are intentionally conservative:
+
+- ASCII lowercase letters, numbers, and hyphens only.
+- No empty labels.
+- No leading or trailing hyphens.
+- Maximum 63 characters per label.
+
+This avoids Unicode spoofing until a full IDN/punycode policy exists.
+
+## Node And Namehash
+
+A node is the ENS-compatible `bytes32` namehash of a normalized name.
+
+```ts
+namehash('agent');
+namehash('acme.agent');
+namehash('treasury.acme.agent');
+```
+
+`ZERO_NODE` is the all-zero root sentinel. `labelhash(label)` hashes one label;
+`namehash(name)` recursively hashes the full path from root to leaf.
+
+## Registry
+
+The registry owns the namespace tree. For each node, it records:
+
+- owner Smart Agent
+- resolver contract
+- parent node
+- optional subregistry
+- optional expiry
+
+The registry answers "who controls this name?" and "where are this name's
+records stored?"
+
+## Resolver
+
+The resolver stores typed records for a node. The current record bundle is
+`AgentNameRecords`:
+
+- `addr`
+- `agentKind`
+- `displayName`
+- `a2aEndpoint`
+- `mcpEndpoint`
+- `metadataUri`
+- `metadataHash`
+- `passkeyCredentialDigest`
+- `custodyPolicy`
+- `nativeId`
+
+The resolver is for discovery and metadata. It is not an authorization system.
+
+## Subregistry
+
+A subregistry manages child-name issuance for a subtree.
+
+For example, `acme.agent` can set a subregistry that manages
+`*.acme.agent`. That subregistry may be permissioned, invite-gated,
+credential-gated, or permissionless with anti-spam rules.
+
+The package exposes call builders for setting a subregistry and for claiming
+names through a permissionless subregistry. The package does not decide which
+policy is appropriate for a product.
+
+## Primary Name
+
+A primary name is the reverse record for a Smart Agent address.
+
+Forward resolution:
+
+```text
+alice.agent -> 0xAliceSmartAgent
+```
+
+Reverse resolution:
+
+```text
+0xAliceSmartAgent -> alice.agent
+```
+
+Reverse resolution is trusted only when it round-trips: resolving the returned
+name must return the same address.
+
+## CAIP-10 Native ID
+
+`nativeId` is the canonical Smart Agent identifier in CAIP-10 form:
+
+```text
+eip155:84532:0x0000000000000000000000000000000000000003
+```
+
+It MUST equal the `addr` record for EVM chains. It back-links external registries
+(ERC-8004, HCS, ANS) to the same canonical SA. This package does not generate
+UAID strings ([ADR-0008](../../../docs/architecture/decisions/0008-caip10-nativeid-record-predicate.md)).
+
+Encode-side validation is strict. Decode-side behavior is more permissive for
+forward compatibility.
+
+## Forced-Unique Labels
+
+When `alice.agent` is taken, bootstrap uses a sequential suffix:
+`alice2.agent`, `alice3.agent`, … ([spec 220 § 5](../../../specs/220-agent-identity-bootstrap.md)).
+The canonical SA address does not change when the suffix increments — only the
+naming facet label does.
+
+## Records And Service Discovery
+
+Records make names useful to agents and tools:
+
+- `a2aEndpoint` tells clients where a service agent's A2A endpoint lives.
+- `mcpEndpoint` tells clients where its MCP endpoint lives.
+- `metadataUri` and `metadataHash` anchor an off-chain profile.
+- `displayName` gives UI a stable label.
+
+Endpoint records are discovery hints. A consumer that needs endpoint-control
+proof should compose with `@agenticprimitives/agent-profile`.
+
+## Read Paths (No `eth_getLogs`)
+
+Forward resolve and record reads use `readContract` only
+([ADR-0012](../../../docs/architecture/decisions/0012-no-eth-getlogs-in-product-read-paths.md)).
+`reverseResolve` still reconstructs the dotted string from registration **events**
+via chunked `getLogs` — transitional until labels are stored on chain or served
+by an indexer. Prefer caching `address → name` in apps after `setPrimaryName`.