The Dillweed Namespace Standard defines how capabilities are named and governed. DillClaw defines how they are found, evaluated, and selected. These are complementary specifications: the namespace provides stable identity; the resolver provides operational access.

DillClaw is a resolver specification and implementation layer — a structured intermediary that accepts agent queries expressed against the Dillweed namespace, consults the authoritative registry, applies trust and policy filters, and returns ranked, invocable Capability Records. It is not a proxy, not a gateway, and not a capability provider itself. Its role is resolution: mapping names to endpoints in a way that is trustworthy, auditable, and consistent across time.

Without a resolver layer, a namespace remains descriptive. DillClaw makes it operational.

This specification defines the resolution protocol, the query syntax, the trust evaluation model, the HTTP API, integration patterns for MCP and A2A, error semantics, and the caching strategy. Implementations that conform to this specification are considered DillClaw-compliant resolvers.

Conformance Terminology

The key words MUST, MUST NOT, REQUIRED, SHALL, SHALL NOT, SHOULD, SHOULD NOT, RECOMMENDED, MAY, and OPTIONAL in this document are to be interpreted as described in BCP 14 [RFC 2119] [RFC 8174] when, and only when, they appear in all capitals, as shown here.

DillClaw occupies a specific position in the agentic AI infrastructure stack. Understanding that position is essential to understanding what it does — and what it deliberately does not do.

DillClaw's role is narrow by design. It does not store capabilities, does not proxy requests to them, and does not make policy decisions about which agents may invoke what. It resolves names to endpoints and returns the information needed for an agent to invoke a capability directly.

Without this layer, agents must rely on hardcoded endpoints, brittle registries, or provider-specific abstractions — none of which survive scale, substitution, or time. Today, this function is fragmented across hardcoded endpoints, provider registries, and prompt-level tool selection. DillClaw replaces that fragmentation with a single, governed resolution layer.

Resolver operations produce observable coordination events — query breadth, no-match patterns, signature failures, stale-cache responses, and revocation-cache behavior — that may be emitted as Anthill signals for coordination-layer observability. DillClaw does not depend on Anthill for its normative behavior; the relationship is one of optional emission rather than required coupling. The hook interface for this emission is tracked in Appendix A.7.

A DillClaw Resolver consists of five functional components. These may be deployed as a single service or as independent modules; the specification is agnostic to deployment topology as long as the external behavior is conformant.

2.1 Functional Components

2.2 Data Flow

2.3 Deployment Modes

The resolution protocol defines the contract between a calling agent and a DillClaw Resolver. It specifies what a valid request contains, what a conformant response MUST include, and how failure states are communicated.

3.1 Request Structure

The version_pref field accepts three forms. "stable" selects the highest semver version (per semver.org) without a pre-release identifier and without a build-metadata tag, from among candidates surviving the trust filter. "latest" selects the highest semver version including pre-release identifiers. An explicit semver string or semver range (for example 1.2.0 or ^1.2) selects the highest version satisfying that constraint.

The max_results field accepts integers between 1 and 50. Requests specifying a value outside this range MUST be rejected with QUERY_MALFORMED. The allow_unsigned field controls whether candidates with missing or unverifiable signatures are eligible for inclusion in the result set. When false (the default), unsigned candidates are eliminated during signature filtering (§6.1). When true, unsigned candidates are retained and marked with the sig_unverified trust signal. This field implements the §6.1 provision that missing-signature candidates "MAY be returned only if caller policy permits unsigned records." A resolver MAY also support a DILLCLAW_DIAGNOSTIC_MODE environment variable that, when set to 1, enables unsigned-record inclusion globally for debugging and development contexts.

3.2 Response Structure

The resolved_at field MUST be formatted as an RFC 3339 date-time in UTC with the Z offset and second precision (YYYY-MM-DDTHH:MM:SSZ). Non-UTC offsets and fractional seconds MUST NOT be used. This matches the format used for the last_updated field in the Registry Specification §3.1.

The scoring_profile field identifies the deterministic scoring profile under which the trust scores in this response were computed. Conformant resolvers MUST return this field; the default profile is dillclaw-default-v1, defined in §6.2. Future profiles may be introduced for governance-approved scoring variants; profile identifiers are versioned independently of this specification's document version. Callers comparing scores across responses MUST verify that the responses share the same scoring profile.

3.3 Resolution Guarantees

• Determinism — Given the same query and registry state, a conformant resolver MUST return the same ranked result. Determinism requires pinned arithmetic for trust scoring and deterministic tie-breaking — both specified in §6.2.
• No silent failure — Every request MUST return a structured response. A resolver that cannot answer MUST return a documented error state, never an empty body or unhandled exception.
• Auditability — Every response MUST include a trace_id that can be used to reconstruct the full resolution decision from resolver logs.
• Trust transparency — The trust signals used in ranking MUST always be returned alongside the result, so the calling agent can evaluate the basis for selection.
• Signature pass-through — DNSO cryptographic signatures on Capability Records MUST NOT be stripped or modified by the resolver. The agent receives them verbatim for independent verification.

DillClaw queries are expressed as Dillweed namespace URIs, extended with a small set of matching operators. The query language is deliberately minimal — sufficient for precise and pattern-based resolution, but not expressive enough to become a general-purpose query system with attendant complexity.

4.1 Exact Match

A fully qualified path resolves to exactly one registered capability:

4.2 Wildcard Matching

A single asterisk (*) matches any single path component. This allows agents to express intent at a category level without specifying an exact provider:

4.3 Version Pinning

A version suffix pins the query to a specific capability version or range:

4.4 Query Constraints

• Wildcards MUST NOT appear in the first path component (the domain segment)
• A query MUST contain at most two wildcards
• Double-star (**) recursive matching is not supported; a future revision may introduce it (see Appendix A)
• A wildcard query whose expansion would match more than 200 candidates MUST be rejected with QUERY_TOO_BROAD (see §8.2). The caller is expected to narrow the query.
• Queries with no matching results MUST return status: "no_match" with a documented reason — never an empty results array without explanation

A DillClaw Resolver exposes a minimal HTTP API. All endpoints accept and return application/json. Authentication is OPTIONAL but RECOMMENDED for production deployments.

5.1 Core Endpoints

5.2 Request Headers

Trust evaluation is the core value proposition of DillClaw beyond simple registry lookup. A raw registry can return what exists. DillClaw determines which eligible capability has the strongest verified standing — through a documented, auditable evaluation process applied to every candidate.

The trust score ranks candidates that survive hard eligibility filters; it does not override tier gates, permission checks, signature policy, or caller-defined constraints. Scoring is a ranking mechanism applied to already-eligible candidates, not an authorization decision.

6.1 Evaluation Pipeline

6.2 Trust Score Composition

Trust scores are computed deterministically using the formula and signal values specified below. Every conformant resolver MUST produce the same trust score for the same candidate given the same inputs — this is the foundation of the determinism guarantee in §3.3.

The aggregate score is the weighted sum of the four signal values:

The aggregate score MUST be rounded to three decimal places using banker's rounding (round-half-to-even, IEEE 754 roundTiesToEven). For example, a raw value of 0.7245 rounds to 0.724; 0.7255 rounds to 0.726. Conformant implementations MUST produce byte-identical rounded values for the same inputs.

The weights and signal value mappings above define the default scoring profile, identified as dillclaw-default-v1. Future governance-approved profiles may revise weights or signal mappings, provided that profile identifiers are returned in resolver responses (see §3.2) and that scoring remains deterministic within each profile. The determinism guarantee in §3.3 holds within a profile, not across profiles. Profile versioning is independent of this specification's document version: the profile identifier tracks scoring behavior, not document edits.

6.3 Tie-Breaking

When two candidates produce identical rounded trust scores, the ranking engine MUST break the tie as follows, evaluating each rule in order until the tie is resolved:

• Rule 1 — Namespace path. Ascending lexicographic order on the fully qualified namespace path, comparing UTF-8 bytes. Since namespace components are restricted to lowercase ASCII (per Registry Specification §3.1), this is equivalent to ASCII sort order.
• Rule 2 — Semver version. Ascending semver precedence (per semver.org §11) on the capability version string.

No further tie-breaking rules are defined; the combination of namespace path and version is unique per active record by registry design, so these two rules suffice to order any candidate set deterministically.

6.4 Score Semantics and Consumer Guidance

The trust_score is a deterministic composite resolution index produced by a named scoring profile. It represents the resolver's current assessment of a capability record's standing based on declared trust tier and verifiable resolution signals at the time of resolution.

What the Score Is

• Deterministic — the same record resolved under the same scoring profile always produces the same score. The formula, weights, signal values, and rounding rules are fully specified in §6.2.
• Composite — the score combines four independent signals (trust tier, usage history, signature validity, endpoint liveness), each weighted and bounded between 0 and 1.
• Profile-relative — scores are meaningful only within a named scoring profile. Consumers comparing scores across responses MUST verify that the responses share the same scoring_profile value.
• An explanatory resolver output — the score explains the resolver's assessment. It is returned alongside the trust_signals array so that consumers can evaluate the basis for the assessment rather than treating the number as opaque.

What the Score Is Not

• The trust score is not a probability of safety, correctness, or reliability. A score of 0.85 does not mean an 85% chance of trustworthiness.
• The trust score is not an authorization decision. The resolver resolves capability standing; it does not decide whether the caller should invoke the capability. Authorization, admissibility, and execution governance are the responsibility of the consumer's own policy layer.
• The trust score is not a guarantee of any kind. A high score indicates that the verifiable signals available to the resolver were favorable at the time of resolution. It does not certify the quality, safety, or correctness of the underlying capability.
• The trust score is not comparable across scoring profiles. A score of 0.70 under dillclaw-default-v1 has no defined relationship to a score of 0.70 under a future profile with different weights.

Consumer Guidance

The resolver does not enforce accept/reject thresholds. Different consumers will have different tolerance levels depending on their deployment context and risk posture. The following table provides interpretive guidance under the dillclaw-default-v1 profile:

These ranges are guidance, not policy. Consumers SHOULD establish their own minimum score thresholds based on their deployment context, risk tolerance, and regulatory requirements. The resolver's role is to compute and return the score transparently; the consumer's role is to decide what to do with it.

Resolution latency is a first-class concern. For agentic systems making many capability decisions in sequence, resolver overhead accumulates quickly. DillClaw's caching model is designed to make the common case — repeated resolution of stable, frequently-used capabilities — extremely fast.

7.1 Cache Architecture

• Registry snapshot cache — The resolver maintains a complete local snapshot of the Registry's active record set, refreshed periodically via the Registry's /list endpoint. On each refresh, the resolver MUST paginate to completion: fetching successive pages (using limit and offset) until all records indicated by the total envelope field have been retrieved. The resolver SHOULD send If-None-Match with the previously received ETag on each refresh; a 304 Not Modified response indicates the catalog has not changed and no records need to be re-fetched.
• Local record cache — Capability Records retrieved from the registry are cached locally. Cache key is the fully qualified namespace path. TTL is resolver-configured (default 300 seconds).
• Liveness probe cache — Endpoint liveness results are cached independently with a shorter TTL (default: 60 seconds). Probes MUST NOT be repeated on every resolution request.
• Negative cache — Not-found responses from the registry are cached with a short TTL (default: 30 seconds) to prevent thundering-herd behavior on repeated queries for nonexistent paths.

7.2 TTL Rules

The stale-while-revalidate window governs how long a resolver may continue serving stale cached records after the registry becomes unreachable. When the window expires, subsequent requests MUST return REGISTRY_UNAVAILABLE rather than older stale data.

7.3 Stale-While-Revalidate

When the registry is unreachable, DillClaw MUST NOT fail open by silently serving stale data without disclosure. Conformant behavior: serve the most recently cached Capability Record if within the stale window, and include a stale: true flag and cached_at timestamp (RFC 3339 UTC, second precision, per §3.2) in the response. If no cached record exists and the registry is unreachable, return a structured error.

7.4 Performance Targets

7.5 Cache Freshness and Revocation Propagation

Caching introduces a freshness window during which the Resolver may serve data that is no longer current at the Registry. If a capability record is revoked at the Registry, the revocation does not take effect at the Resolver until the cached entry expires and is refreshed. During this window, the Resolver will continue to return the pre-revocation record as valid.

This is an intentional design tradeoff between two competing requirements:

• Performance and availability — cached resolution avoids per-request Registry latency and allows the Resolver to continue operating during temporary Registry unavailability (the stale-while-revalidate property documented in §7.3).
• Revocation freshness — the guarantee that a revoked capability is no longer returned as valid by any Resolver in the system.

A shorter TTL improves revocation freshness at the cost of increased Registry load and reduced availability during outages. A longer TTL improves performance and resilience at the cost of a wider revocation propagation window.

Operator Guidance

Conformant implementations MUST document their cache TTL and refresh behavior. Operators SHOULD configure the TTL based on their deployment's freshness requirements.

Operators deploying Resolvers for high-assurance contexts — where the revocation of a capability must take effect as quickly as possible — SHOULD configure a shorter TTL and SHOULD monitor Registry fetch latency to ensure the TTL does not exceed the Registry's ability to respond.

Force-Refresh Semantics

A conformant Resolver MAY support a force-refresh mechanism that bypasses the cache and fetches the current record directly from the Registry. If supported:

• Force-refresh MUST be explicitly requested by the caller. It MUST NOT be the default behavior, as it defeats the purpose of caching.
• Force-refresh SHOULD be rate-limited to prevent abuse.
• Force-refresh MUST return the same response structure as a cached resolution, with the cache_hit field set to false.

The reference implementation does not currently support force-refresh. This is tracked as a future enhancement (see Appendix A).

Freshness Guarantee

The Dillweed Namespace's trust model asserts that capability standing should be verified at the moment of use — not cached from initial approval or registration time. The cache TTL does not contradict this principle; it bounds the operational definition of "at the moment of use":

• A resolution performed within the TTL window is operationally current.
• A resolution performed after TTL expiry triggers a fresh Registry fetch.
• Between these two states, the stale-while-revalidate property (§7.3) ensures the Resolver remains available while a background refresh completes.

The freshness guarantee is therefore bounded, not absolute. The TTL defines the maximum acceptable age of a resolution result. Operators who require absolute freshness (zero cache window) MAY configure the TTL to zero, but SHOULD understand that this eliminates the availability benefit of caching and creates a hard dependency on Registry uptime.

Revocation Propagation Guarantee

A conformant Resolver MUST guarantee that a revoked capability record is no longer returned as valid within one registry refresh interval after the revocation is committed at the Registry. The reference implementation refreshes its registry snapshot at a base interval of 60 seconds (configurable via DILLCLAW_REGISTRY_REFRESH_MS), with ±20% random jitter applied to each cycle to prevent synchronized polling across resolver fleets. On registry fetch failure, the resolver applies exponential backoff (doubling the interval on each consecutive failure, capped at 15 minutes) and resumes the base interval on the first successful fetch. Under failure backoff, the effective revocation propagation bound may exceed the base interval; operators SHOULD monitor resolver health endpoints to detect extended stale windows. Implementations that use a different refresh mechanism — for example, per-record TTL-driven cache invalidation rather than snapshot refresh — MUST document their revocation propagation bound and ensure it does not exceed the operator-configured refresh interval. Implementations with cascading caches or asynchronous replication that introduce additional propagation delay MUST document that delay.

Every error state in DillClaw MUST return a structured JSON response with a machine-readable error code, a human-readable message, and where applicable, a corrective suggestion. HTTP status codes are used in the conventional way. No error state results in an empty body.

8.1 Error Response Format

8.2 Error Codes

DillClaw is designed to be integrated into existing agent runtimes with minimal friction. The resolution step slots naturally between the point at which an agent identifies a capability need and the point at which it invokes an endpoint.

9.1 MCP Integration

For agents using the Model Context Protocol, DillClaw resolution can replace or augment hardcoded tool definitions. Instead of embedding tool endpoints in system prompts or configuration files, the agent resolves capabilities at runtime:

9.2 A2A Integration

For agent-to-agent communication using A2A, DillClaw can resolve target agents by namespace path rather than by hardcoded agent card URL. This allows agent networks to remain stable even as underlying agent implementations change providers or infrastructure:

9.3 REST / Direct Invocation

For capabilities exposed as plain REST APIs, the resolved endpoint is used directly. DillClaw returns the full Capability Record including input and output schemas, which the agent can use to construct and validate its request without additional documentation lookup:

9.4 Recommended Integration Pattern

• Resolve once, cache locally — For capabilities used repeatedly in a session, resolve once and retain the result in agent-level memory. Do not call the resolver on every tool invocation.
• Use trace IDs in logs — Include the trace_id from each resolution response in your agent's audit logs. This enables post-hoc debugging if a resolved capability later behaves unexpectedly.
• Handle TRUST_FILTERED gracefully — Design agents to surface trust filter rejections to their orchestrators rather than silently failing or falling back to lower-trust alternatives without acknowledgment.
• Verify DNSO signatures independently — For high-stakes capability invocations, verify the DNSO signature in the returned Capability Record against the public key published at https://dillweed.com/dnso_public.pem rather than relying solely on resolver trust evaluation.

To make the resolver mechanics concrete, the following traces a single resolution operation from the agent's perspective through to invocation — showing each protocol step and the data at each stage.

DillClaw's security model is deliberately limited to the resolver's scope: it does not attempt to secure capability invocation, enforce access control at the capability layer, or authenticate agents to providers. It secures the resolution step only. Production deployments SHOULD enforce per-IP or per-token rate limits on wildcard and batch resolution requests.

11.1 Threat Model

11.2 What DillClaw Does Not Secure

• The capability endpoint itself — authentication and authorization to the capability are the provider's responsibility
• The content of capability responses — DillClaw makes no representation about what a capability returns
• Agent identity — the current specification does not authenticate which agent is making a resolution request. A caller-identity model is anticipated in a future revision; see Appendix A.
• Data in transit to the capability — TLS for the resolution request is expected; TLS for the capability invocation is the agent's responsibility

This specification describes a protocol and an architecture. DillClaw becomes real infrastructure only through implementation and demonstrated operation. The following milestones define the minimum viable resolver — the point at which this specification stops being a proposal and becomes a running system. As of this revision, the Node.js reference implementation operating in local deployment has achieved milestones 01 and 02; the remaining milestones define the path to public availability.

The architectural parallels between DillClaw and DNS are intentional and instructive — but the analogy has limits that are worth stating explicitly.

13.1 Where the Analogy Holds

13.2 Where the Analogy Breaks Down

• DNS resolves to addresses; DillClaw resolves to capabilities. A Capability Record contains semantics, schemas, permissions, and trust signals that have no DNS equivalent. The resolution result is richer.
• DNS is neutral about content; DillClaw is not. Trust evaluation, permission filtering, and contextual ranking are core to DillClaw's function. DNS does not rank results or filter based on caller policy.
• DNS operates at network layer; DillClaw operates at application layer. DillClaw is not a replacement for DNS — it uses DNS for its own endpoint routing and relies on TLS in the conventional way.
• DNS has a 40-year installed base; DillClaw has none yet. The analogy is structural, not a claim of equivalence. DillClaw earns legitimacy through adoption, not through comparison to infrastructure that already won.

13.3 Attestation Scope: Namespace Layer vs. Hardware and Code Layer

DillClaw performs namespace-layer attestation — a distinct and narrower operation than the hardware attestation and code integrity verification performed by trusted execution environments, TPM-based platforms, and supply-chain security systems. Understanding this distinction matters both for correct implementation and for accurate descriptions of what DillClaw can and cannot guarantee.

What DillClaw attests: DillClaw verifies that a Capability Record — comprising a namespace path, endpoint URL, declared trust tier, permissions, protocol, and schema metadata — was signed by the DNSO private key and has not been altered since signing. This is a statement about the registry record, not about the software running at the endpoint. A capability that passes DillClaw signature verification is a capability whose declared metadata is authentic. It is not a statement that the endpoint is running unmodified code, that the server hardware is in a known good state, or that the software supply chain is intact.

What DillClaw does not attest: DillClaw does not perform firmware attestation, Trusted Platform Module (TPM) quote verification, Trusted Execution Environment (TEE) attestation, or any form of remote code measurement. It does not verify that the binary running at a capability endpoint matches a known-good hash, that the server operating system has not been modified, or that the execution environment is isolated from compromise. These are application-layer and infrastructure-layer concerns that fall outside the namespace coordination layer.

Why the distinction matters: Hardware and code attestation systems — such as those used in confidential computing, secure enclaves, and hardware root-of-trust architectures — attest the integrity of an execution environment at a given moment. Namespace-layer attestation, as performed by DillClaw, attests the integrity of a coordination record over time. Both are valid and complementary forms of trust evidence. A well-governed agent system may use both: DillClaw to establish that a capability's identity and declared metadata are authentic, and a separate attestation layer to establish that the endpoint's execution environment is trustworthy at the time of invocation.

This appendix records items intended for a future revision of the DillClaw Resolver Specification. It is non-normative: nothing in this appendix imposes conformance requirements on implementations of this specification. It is included to disclose the anticipated direction of the specification so that implementers can make informed decisions about extensibility and ecosystem participants can plan for forthcoming changes.

A.1 Resolver Authentication and Caller Identity

The current specification treats the Authorization header as optional with no prescribed format, and does not authenticate the agent making a resolution request. A future revision is expected to define: (a) a bearer-token format and validation contract for resolver authentication, (b) a caller-identity attestation model that allows a resolver to verify the agent making each request, and (c) the resolver identity certificate model referenced in §11.1 for mitigating resolver-impersonation threats. These changes will affect §5.2, §11.1, and §11.2.

A.2 Caller-Controlled Endpoint Liveness Probing

The probe_liveness request field has been promoted to §3.1 and §6.1 as of v0.1.8. Future work may extend this to support enumerated probe modes (e.g., shallow HTTP HEAD vs. deep health-check) and per-endpoint probe configuration.

A.3 Richer Permission Semantics

The current specification performs exact-string matching on permissions declared by the caller against permissions declared by the capability. A future revision is expected to introduce structured permission scopes, hierarchical permissions (for example data.read implying data.read.metadata), and permission negotiation where a capability may declare that it conditionally supports permissions depending on caller identity. This change will affect §6.1.

A.4 Recursive Wildcard Matching

The current specification supports single-asterisk wildcards matching exactly one namespace component, with a limit of two wildcards per query. A future revision is expected to evaluate the addition of recursive wildcard matching (**) for matching any number of intervening components, subject to stricter candidate-expansion limits to prevent query cost amplification. This change will affect §4.2 and §4.4.

A.5 Internationalized Namespace Components in Queries

The current specification restricts namespace components in queries to lowercase ASCII letters, digits, and hyphens, matching the Registry Specification §3.1 naming rule. A future revision is expected to extend the query syntax to accept internationalized names encoded per IDNA 2008 (RFC 5891) punycode once the registry accepts such names. This change will affect §4.1, §4.2, and §8.

A.6 Trust Signal String Format

The current specification returns trust signals as unstructured strings in the trust_signals response array (for example "18mo_history"). A future revision is expected to pin the exact format of these strings — regular expressions, casing rules, zero-padding for numeric components — so that callers parsing signal strings produce consistent results across conformant resolvers. This change will affect §3.2 and §10.

A.7 Anthill Integration

This specification does not address integration with the Dillweed Anthill Observability Plane Specification, which describes resolver-side hooks for generating ANT-RC (Revocation Cascade) and ANT-RA (Resolution Anomaly) signals from resolution and verification activity (Anthill §4). A future revision is expected to define the hook interface, including conformance level for signal emission, delivery model (push to an Anthill aggregation endpoint or pull from a Resolver-exported feed), signal payload schema, and configuration surface by which a Resolver operator binds to a specific Anthill aggregation endpoint and signing key. This change will affect a new Resolver section addressing observability integration, and is intended to be developed jointly with the corresponding revision of the Anthill specification.