@agenticprimitives/agent-naming 1.0.0-alpha.4 → 1.0.0-alpha.40

package/AUDIT.md

@@ -1,7 +1,8 @@
 # @agenticprimitives/agent-naming — package audit
 
 **Status:** Phase 1 (SDK skeleton + spec + pure helpers).
-**Last refreshed:** 2026-05-23.
+**Last refreshed:** 2026-06-01 (R9 substrate coverage references + R11.1 fail-hard audit + R11.3 public-surface cleanup)
+**Prior refresh:** 2026-05-23
 **Owner:** [security-auditor](../../docs/agents/security-auditor.md) +
 [technical-architect-auditor](../../docs/agents/technical-architect-auditor.md).
 **System audit cross-ref:** see
@@ -14,7 +15,7 @@ on-chain authority paths, and demo integration land in Phase 3+.
 ## Charter (what's audit-relevant in this package)
 
 - Pure helpers (`normalizeAgentName`, `labelhash`, `namehash`): MUST
-  be deterministic + match the reference ENS algorithm + reject
+  be deterministic + match the standard recursive-namehash algorithm + reject
   malformed input.
 - Record schema (`AgentNameRecords` + `records` subpath): MUST
   refuse unknown keys on encode (fail-loud write) AND drop unknown
@@ -39,9 +40,9 @@ on-chain authority paths, and demo integration land in Phase 3+.
   non-ASCII / oversize labels. Throws `InvalidNameError`. Covered in
   `test/normalize.test.ts`.
 - ✅ `normalize` is idempotent: `normalize(normalize(x)) === normalize(x)`.
-- ✅ `namehash('')` = `ZERO_NODE` (`0x00…00`) per the ENS sentinel
+- ✅ `namehash('')` = `ZERO_NODE` (`0x00…00`) per the root-sentinel
   convention.
-- ✅ `namehash` matches the ENS reference algorithm under an
+- ✅ `namehash` matches the standard recursive-namehash algorithm under an
   in-band independent reimplementation (`test/namehash.test.ts`
   golden-vector table).
 - ✅ `namehash` rejects malformed input by delegating to `normalize`.
@@ -84,3 +85,13 @@ client doesn't yet take an `auditSink`; Phase 2 will add the optional
 | Date | Wave | What changed |
 | --- | --- | --- |
 | 2026-05-23 | NS Phase 1 | Initial audit. AN-1/2/3 open; security invariants verified by unit tests. |
+
+## R9 substrate coverage (2026-06-01)
+
+- Locked by R6.2 + R6.8 contract-side hardening:
+  - `AgentNameRegistry.initializeRoot` cannot be frontrun (immutable initializer + same-tx deploy) — H7-C.4 / CON-NAMING-001.
+  - `PermissionlessSubregistry.register` is `nonReentrant` — R6.2 / CON-SUBREGISTRY-003.
+  - Pause coverage: 7 mutating functions (register, backfillLabel, setOwner, setResolver, setSubregistry, renew, setPrimaryName) are `whenNotPaused` — R6.8.
+  - ADR-0012 / ADR-0013: NO `eth_getLogs` in product read paths; `reverseResolveString` is the canonical single-call.
+- See [`packages/contracts/AUDIT.md` § 3.8](../contracts/AUDIT.md).
+

package/CLAUDE.md

@@ -5,11 +5,24 @@ Names are a **facet registration** pointing AT the canonical Smart Agent ([ADR-0
 
 ## What this package owns
 
-- The `.agent` TLD constant (`AGENT_TLD`).
-- Name normalization (`normalizeAgentName`) — NFC + lowercase + label
-  validation. Rejects empty / hyphen-prefixed / non-ASCII labels in v0.
-- `labelhash` + `namehash` — ENS-compatible keccak256 hashes for
-  identifier nodes.
+- The **typed TLD registry** (`AGENT_TLDS` = `me org team svc workspace treasury registry church circle`, alias `ws`,
+  legacy `impact`/`agent`) — a suffix names the DERIVED agent type, never a root, a role or the
+  hierarchy ([ADR-0061](../../docs/architecture/decisions/0061-derived-agent-types-and-typed-name-suffixes.md),
+  [spec 346](../../specs/346-typed-agent-naming-and-registry.md)). `derivedTypeForTld` / `rootClassForTld`.
+- The name **grammar** (`parseAgentName`): `x.t` canonical, `x.t@c.u` context-issued (path form
+  `c.u/x.t`, on-chain form `x.t.c.u`), type-nodes, roots, legacy. One context level in v1.
+- Name normalization (`normalizeAgentName`) — NFC + lowercase + label validation + alias rewrite;
+  returns the canonical display form.
+- The **federated reference** (`federatedAgentName` → `FederatedAgentNameV1 { name, chain }`, `displayAgentName` —
+  bare only inside the home chain, qualified everywhere else; spec 346 §3.7, ap-federation spec 440 §C). The chain is
+  a record beside the name, never a name component: `alice.me@faithchain` is refused by the grammar.
+- The **DNS/A2A projection** (`dnsHostForHandle`, zone caller-supplied — ADR-0021) and the two
+  protocol paths (`/api/a2a`, `/.well-known/agent-card.json`).
+- **Claim-time validation** (`validateTypedClaim`, `findUniqueLabel`, `buildDeclareAgentTypeCalls`,
+  `buildTypedClaimCalls`): the suffix is a CLAIM, the SA-keyed on-chain `atl:agentType` record is
+  the authority; a mismatch fails closed (`resolveTyped` → `null`, `checkTypedName` → reason).
+- `labelhash` + `namehash` — recursive keccak256 hashes
+  (`keccak256(parentNode || labelhash)`) for identifier nodes.
 - Record schemas (`AgentNameRecords`) and predicate constants
   (subpath `/records`).
 - `AgentNamingClient` — read API (resolve / reverse-resolve / get
@@ -19,25 +32,19 @@ Names are a **facet registration** pointing AT the canonical Smart Agent ([ADR-0
 
 ## What this package does NOT own
 
-- Smart-account internals → [`agent-account`](../agent-account)
-  (we consume `AgentAccountClient` for ERC-1271 verification +
-  counterfactual address derivation).
-- Custody policy, scheduling, quorum → [`custody`](../account-custody).
-  We expose call builders only — never import.
-- Delegation / caveat / mint → [`delegation`](../delegation).
-- Passkey ceremonies → [`connect-auth`](../connect-auth).
-- MCP / A2A transport → demo apps + future `a2a-runtime`.
-- Contract source — that lives in `packages/contracts/src/naming/`
-  (Phase 3+); this package ships ABIs + client only.
+Smart-account internals → `agent-account`; custody policy → `account-custody` (call builders only,
+never imported); delegation → `delegation`; passkeys → `connect-auth`; MCP/A2A transport → apps;
+contract source → `packages/contracts/src/naming/` (ABIs + client only here); the composed typed
+resolver / invitation flows → `registry-resolution` (spec 346 §6.3).
 
 ## Vocabulary
 
 **Owns:** `AgentName`, `Label`, `Node` (namehash), `NameRecord`,
 `AgentNamingClient`, `Subregistry`, `Resolver`, `PrimaryName`,
-`AGENT_TLD`.
+`AgentTld`, `ParsedAgentName`, `TypedNameRecord`.
 **Disambiguation:**
 
-- **"resolver"** here = on-chain ENS-v2 resolver. Distinct from
+- **"resolver"** here = our on-chain registry + resolver. Distinct from
   any other package.
 - **"registry"** here = `AgentNameRegistry` contract. Distinct from
   the factory deploy-registry in `agent-account`.
@@ -51,14 +58,15 @@ Names are a **facet registration** pointing AT the canonical Smart Agent ([ADR-0
 
 1. `capability.manifest.json` — boundary.
 2. `src/index.ts` — public API.
-3. `../../specs/215-agent-naming.md` — the spec.
+3. `../../specs/346-typed-agent-naming-and-registry.md` §2–§5 — the typed model (spec 215 = records/contracts prior art).
 4. `src/namehash.ts` + `src/normalize.ts` — the pure substrate.
 5. `src/client.ts` — the client skeleton.
 
 ## Stable public exports
 
-**Constants + helpers:** `AGENT_TLD`, `normalizeAgentName`,
-`labelhash`, `namehash`.
+**Constants + helpers:** `AGENT_TLDS`, `derivedTypeForTld`, `rootKindForTld`, `parseAgentName`,
+`formatAgentName`, `normalizeAgentName`, `labelhash`, `namehash`, `dnsHostForHandle`,
+`findUniqueLabel`, `validateTypedClaim`, `federatedAgentName`, `displayAgentName`.
 **Types:** `AgentNameRecords`, `RegisterSubnameInput`,
 `SetPrimaryNameInput`, `SetAgentRecordsInput`,
 `SetSubregistryInput`.
@@ -68,6 +76,8 @@ Names are a **facet registration** pointing AT the canonical Smart Agent ([ADR-0
 **Subpaths:**
 
 - `/records` — predicate constants + encoders/decoders.
+  Includes `cardDigest` (bytes32 sha256 of the RELEASED A2A Agent Card) + `cardUri` — spec 347 §8.3; the AP Naming
+  projection writes them, `resolve()` reads them, `registry-resolution` surfaces `bindings.cardDigest`. Evidence, never authority.
 - `/custody` — pure encoded call builders for custody-gated name
   rotation (no `@agenticprimitives/account-custody` import).
 
@@ -103,30 +113,13 @@ Names are a **facet registration** pointing AT the canonical Smart Agent ([ADR-0
 - "Reach for an MCP transport" — **STOP.** Out of scope.
 - "Auto-resolve name via a system-wide hook in the worker" — **STOP.**
   Demo-app integration only; the package itself is transport-agnostic.
-
-## Decision Tree
-
-- Adding a new record field? Start in `src/types.ts` and
-  `src/records.ts`; update tests and `docs/api.md`.
-- Adding resolver reads? Start in `src/client.ts`.
-- Adding name rotation calls? Start in `src/custody.ts`; do not import
-  `@agenticprimitives/account-custody`.
-- Adding passkey behavior? Stop. Route to `connect-auth`.
-- Adding delegation or caveat behavior? Stop. Route to `delegation`.
-- Adding MCP/A2A transport? Stop. Route to app/runtime packages.
-
-## Before you write code
-
-- [ ] Is the change in the resolver-records / namehash / normalize /
-      client surface?
-- [ ] Did I avoid importing from `delegation`, `account-custody`,
-      `mcp-runtime`, `tool-policy`, `key-custody`, `audit`?
-- [ ] Did I keep `normalize` deterministic (NFC + lowercase + label
-      validation)?
-- [ ] Did I write golden-vector tests for any namehash / labelhash
-      change?
-- [ ] Did I update `specs/215-agent-naming.md` if the public API or
-      records schema changed?
+- "Infer the agent type from the suffix / the DNS label" or "let the suffix
+  override `atl:agentType`" — **STOP.** ADR-0061 §5: the record is the
+  authority; `checkTypedName` fails closed on a mismatch.
+- "Bake a zone / hostname into `dns.ts`" — **STOP.** ADR-0021: the zone is
+  caller-supplied; `check:no-domain-in-packages` enforces it.
+- "Add `'team'`/`'treasury'` to `AgentKind`" — **STOP.** Roots are closed;
+  the derived type is `DerivedAgentType` on the SA subject.
 
 ## Security invariants (DO NOT BREAK)
 
@@ -161,15 +154,9 @@ pnpm check:forbidden-terms
 
 ## Capabilities this package participates in
 
-- **Agent identity + service discovery** — the naming graph IS the
-  on-chain authority for "which Smart Agent answers to which
-  human-readable name." Demos use it to resolve service endpoints
-  (`a2a-endpoint`, `mcp-endpoint`) without hardcoded URLs.
-- **Audit / forensics trail** — emits (via consumer-supplied
-  `AuditSink`): `agent-naming.{resolve,register,records.update,
-primary-name.update,subregistry.update}`.
-- Index of cross-cutting capabilities:
-  [`docs/architecture/cross-cutting-capabilities.md`](../../docs/architecture/cross-cutting-capabilities.md).
+- **Agent identity + service discovery** — which Smart Agent answers to which typed name, and the
+  DNS/A2A binding projected from it. Index: [`cross-cutting-capabilities.md`](../../docs/architecture/cross-cutting-capabilities.md).
+- **Audit trail** — emits `agent-naming.{resolve,register,records.update,primary-name.update,subregistry.update}` via a consumer-supplied `AuditSink`.
 
 ## Documentation map
 

package/README.md

@@ -1,44 +1,40 @@
 # @agenticprimitives/agent-naming
 
-Human-readable `.agent` **naming facets** for Smart Agents.
+> Part of **[Agentic Primitives](https://agenticprimitives.dev)** — the open-source trust substrate for agentic applications: identity that can sign, authority checked at act time, evidence the owner carries. [Developer kit](https://github.com/agentictrustlabs/agentic-primitives) · [All packages](https://agenticprimitives.dev/developers)
 
-The canonical identifier is the Smart Agent address
-(`@agenticprimitives/agent-account`). This package registers names and records
-that point **at** that address — it does not create or own identity.
+**The name is a facet. The address is the identity.** Agent naming is being settled right now — GoDaddy launched an Agent Naming Service, ERC-8004 put agent registries on mainnet, and every discovery stack needs an answer to "which agent answers to this name?" Most naming systems get the dependency backwards: the name becomes the identity, and losing the name (or the registrar) means losing everything attached to it. Here, every person, org, service agent, and treasury is a canonical ERC-4337 Smart Agent address — and a `.agent` name is a replaceable record pointing *at* that address ([ADR-0010](../../docs/architecture/decisions/0010-smart-agent-canonical-identifier.md)). Rotate the name, keep the identity. Rotate your credentials, keep the name. Nothing downstream breaks.
+
+Part of [agenticprimitives](../../README.md) — the trust substrate for the agent economy: one canonical Smart Agent identity with custody, delegation, naming, credentials, and audit evidence designed as one system.
+
+Use this package to resolve names like `alice.agent` and `treasury.acme.agent` to Smart Agent addresses, read typed service-discovery records (A2A endpoint, MCP endpoint, CAIP-10 `nativeId`), and build encoded calls for name-management transactions. Names are hierarchical — orgs hand out subnames under their own subregistry — and normalization is deterministic and on-chain-verifiable.
 
 > **Layer:** Discover — a naming **facet** (not canonical identity — that is `agent-account`).
 > **Canonical key:** the Smart Agent address the name resolves to.
 
-Use this package to resolve names like `alice.agent`, `acme.agent`, and
-`treasury.acme.agent` to Smart Agent addresses, read typed service-discovery
-records, and build encoded calls for name-management transactions.
-
-## Use This When
+## Use this when
 
-- You need forward resolution: `alice.agent -> 0x...`.
-- You need reverse resolution from a Smart Agent address to its primary name.
-- You need typed records such as `displayName`, `a2aEndpoint`, `mcpEndpoint`,
-  `nativeId`, or `metadataUri`.
-- You need pure call builders for name registration, resolver updates, primary
-  name updates, or owner rotation.
+- You need forward resolution: `alice.agent → 0x…`.
+- You need reverse resolution from a Smart Agent address to its primary name — with a round-trip check, so a name is only trusted when it resolves back to the same address.
+- You need typed records such as `displayName`, `a2aEndpoint`, `mcpEndpoint`, `nativeId`, or `metadataUri` — service discovery without hardcoded URLs.
+- You need pure call builders for name registration, resolver updates, primary-name updates, or owner rotation that compose into custody-policy ceremonies.
 
-## Do Not Use This For
+## Do not use this for
 
-- Passkey ceremonies or auth flows. Use `@agenticprimitives/connect-auth`.
-- Smart-account deployment or UserOps. Use `@agenticprimitives/agent-account`.
-- Account safety policy and approval scheduling. Use `@agenticprimitives/account-custody`.
-- Permission-token minting or attenuation. Use `@agenticprimitives/delegation`.
-- MCP/A2A transport wiring. Use demo apps or runtime packages.
+- Passkey ceremonies or auth flows — `@agenticprimitives/connect-auth`.
+- Smart-account deployment or UserOps — `@agenticprimitives/agent-account`.
+- Account safety policy and approval scheduling — `@agenticprimitives/account-custody`.
+- Permission-token minting or attenuation — `@agenticprimitives/delegation`.
+- MCP/A2A transport wiring — demo apps or runtime packages.
 
 ## Install
 
-This package is workspace-internal and not yet published.
+Workspace-internal; not yet published.
 
 ```bash
 pnpm add @agenticprimitives/agent-naming
 ```
 
-## 60-Second Quickstart
+## 60-second quickstart
 
 ```ts
 import {
@@ -64,22 +60,28 @@ const primaryName = await naming.reverseResolve('0x00000000000000000000000000000
 const records = await naming.getRecords('treasury.acme.agent');
 ```
 
-## Main Concepts
+## How it's different
+
+The reference points are **ENS and Unstoppable Domains** — both excellent at what they do, both built around a different center of gravity:
+
+- **Name-as-asset vs. name-as-facet.** ENS and Unstoppable treat the name as the prized object; identity accretes around it. Here the Smart Agent address is canonical and forced-unique names are assigned at identity bootstrap ([spec 220 §5](../../specs/220-agent-identity-bootstrap.md)) — the name is a pointer, replaceable without identity loss, and `addr` + `nativeId` must reference the same Smart Agent.
+- **Agent-native records.** Typed predicates for `a2aEndpoint`, `mcpEndpoint`, CAIP-10 `nativeId`, and a public-safe passkey credential digest — the records an agent economy actually resolves, not a TXT free-for-all. Unknown predicates are ignored on decode and rejected by typed encoders.
+- **Custody-governed rotation.** Name-owner rotation ships as pure encoded call builders (`/custody` subpath) that compose into the owner Smart Agent's custody-policy ceremonies — quorums and trustees, not a private key that can be phished once.
+- **Disciplined reads.** Product reads use `readContract` only — no `eth_getLogs` walks, no silent fallbacks ([ADR-0012](../../docs/architecture/decisions/0012-no-eth-getlogs-in-product-read-paths.md), [ADR-0013](../../docs/architecture/decisions/0013-no-silent-fallbacks.md)). Reverse resolution is a single on-chain `reverseResolveString` read, then a forward round-trip before it is trusted.
 
-- **Canonical SA**: the ERC-4337 address every name must reference (`addr`,
-  `nativeId`). Owned by `agent-account`, not this package.
+The `.agent` TLD is the naming protocol; which names a given deployment registers is app-layer configuration — this package stays generic.
+
+## Main concepts
+
+- **Canonical SA**: the ERC-4337 address every name must reference (`addr`, `nativeId`). Owned by `agent-account`, not this package.
 - **AgentName**: a normalized dotted name under `.agent` (a facet label).
-- **Label**: one segment of a name, such as `treasury`.
-- **Node**: ENS-compatible `namehash(name)`.
-- **Registry**: owns name records: owner, resolver, parent, subregistry.
-- **Resolver**: stores typed records for a node.
-- **Primary name**: reverse record for a Smart Agent address.
-- **Records**: typed data such as endpoints, display name, CAIP-10 `nativeId`,
-  and public-safe passkey credential digest.
+- **Label / Node**: one segment (`treasury`); the recursive `namehash(name)`.
+- **Registry / Resolver**: name records (owner, resolver, parent, subregistry); typed records for a node.
+- **Primary name**: the reverse record for a Smart Agent address.
 
 See [`docs/concepts.md`](docs/concepts.md).
 
-## Common Recipes
+## Common recipes
 
 ```ts
 import {
@@ -102,40 +104,37 @@ const decoded = decodeRecords({
 });
 ```
 
-More examples:
+More examples: [`examples/basic.ts`](examples/basic.ts) · [`examples/records.ts`](examples/records.ts) · [`examples/custody-rotation.ts`](examples/custody-rotation.ts)
+
+## Released A2A card records (spec 347 §8.3)
 
-- [`examples/basic.ts`](examples/basic.ts)
-- [`examples/records.ts`](examples/records.ts)
-- [`examples/custody-rotation.ts`](examples/custody-rotation.ts)
+`atl:cardDigest` (bytes32 = sha256 of the released A2A Agent Card's RFC 8785 bytes) and `atl:cardUri` (only when the
+card is not at the a2a host's `/.well-known/agent-card.json`) are ordinary name-node records: `encodeRecords({ cardDigest,
+cardUri })`, read back by `resolve()`. A verifier fetches the card and compares digests; the record proves nothing by
+itself. Existing deployments register the terms with `contracts/script/AddCardPredicates.s.sol`.
 
-## Runtime Support
+## Runtime support
 
-Pure helpers and record encoders work in browser, Node, and Workers. The client
-uses `viem` public and wallet clients and requires an RPC URL for chain reads or
-transaction submission.
+Pure helpers and record encoders work in browser, Node, and Workers. The client uses `viem` public and wallet clients and requires an RPC URL for chain reads or transaction submission.
 
-## Subpath Exports
+## Subpath exports
 
 - `@agenticprimitives/agent-naming` — public helpers, client, ABIs, and types.
-- `@agenticprimitives/agent-naming/records` — predicate ids and typed
-  record encode/decode helpers.
-- `@agenticprimitives/agent-naming/custody` — pure encoded call builders for
-  name-management transactions.
+- `@agenticprimitives/agent-naming/records` — predicate ids and typed record encode/decode helpers.
+- `@agenticprimitives/agent-naming/custody` — pure encoded call builders for name-management transactions.
 
-## Security Invariants
+## Security invariants
 
-- Product reads use `readContract`; no `eth_getLogs` in hot paths
-  ([ADR-0012](../../docs/architecture/decisions/0012-no-eth-getlogs-in-product-read-paths.md)).
-  `reverseResolve` string reconstruction is transitional log debt — do not copy.
-- Name normalization is deterministic.
+- Name normalization is deterministic — equal normalizations produce equal namehashes.
 - Reverse resolution must round-trip before it is trusted.
 - Unknown predicates are ignored on decode and rejected by typed encoders.
-- Raw passkey credential IDs are never stored.
+- Raw passkey credential IDs are never stored — only a digest.
 - Endpoint records are discovery hints, not proof of endpoint control.
+- Product reads use `readContract`; no `eth_getLogs` in hot paths ([ADR-0012](../../docs/architecture/decisions/0012-no-eth-getlogs-in-product-read-paths.md)).
 
 See [`docs/security.md`](docs/security.md) and [`AUDIT.md`](AUDIT.md).
 
-## Documentation Map
+## Documentation map
 
 - [`docs/concepts.md`](docs/concepts.md) — naming model and vocabulary.
 - [`docs/api.md`](docs/api.md) — human-readable public API guide.
@@ -153,6 +152,10 @@ pnpm check:public-exports
 pnpm check:forbidden-terms
 ```
 
+## Status
+
+Testnet/pilot-ready. Production launch is gated on the public checklist in the root [`README.md`](../../README.md#status--honest-version) — including third-party contract audit and governance key rotation. Track every security finding live in [`docs/audits/findings.yaml`](../../docs/audits/findings.yaml).
+
 ## License
 
 UNLICENSED.