DillClaw Resolver
The resolution layer for the Dillweed Namespace — turning stable names into trusted, invocable capabilities.
A namespace without a resolver is a map with no roads. Agents can call tools. They cannot reliably choose the right one across providers and time. DillClaw is the resolution engine for the Dillweed Namespace. It takes a namespace URI, applies trust policy, selects the best capability, and returns an invocable endpoint — in a single, auditable operation.
This document specifies the protocol, API, trust evaluation logic, integration patterns, and deployment requirements for DillClaw implementations. As the number of capabilities grows beyond human-scale, resolution becomes a prerequisite, not an optimization. At sufficient scale, capability selection becomes the bottleneck. Resolution is not optional — it is required infrastructure.
DillClaw does not replace MCP, A2A, or any capability protocol. It sits above them — providing the naming, trust, and routing layer that makes those protocols usable at scale, across providers, across time.
Abstract
The Dillweed Namespace Standard defines how capabilities are named and governed. DillClaw defines how they are found and used. 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.
This document specifies the DillClaw Resolver layer only. Capability Record schema, namespace URI syntax, trust tier definitions, and governance rules are defined in the Dillweed Namespace Standard v0.4. This document defers to that specification on those topics and should be read alongside it.
Role in the Stack
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.
Human Gateway Layer
Platform-scale access, identity, and policy. Examples: Meta, Google, Apple, Microsoft, Salesforce. These layers surface capabilities to end users and enterprise systems.
Dillweed Namespace Layer
Stable naming, trust accumulation, and governance. Defines the URI structure, Capability Record schema, and trust tiers. Governed by the DNSO (Dillweed Namespace Stewardship Organization). Defined in the Dillweed Namespace Standard v0.4.
DillClaw Resolver Layer ← this document
Query parsing, registry lookup, trust evaluation, candidate ranking, and invocation routing. The operational bridge between namespace and capability.
Capability Layer
Individual tools, agents, APIs, and data sources registered within the Dillweed Namespace. Invoked using MCP, A2A, REST, gRPC, or custom protocols as specified in their Capability Records.
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.
Given a valid Dillweed namespace query and a caller's trust policy, DillClaw returns the best available Capability Record — or a structured explanation of why none could be returned. That is the complete contract. Everything else is implementation detail.
Architecture
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
| Component | Responsibility |
|---|---|
| Query Parser | Validates and normalizes incoming namespace queries. Rejects malformed paths before any network operation. Expands wildcard patterns into candidate path sets. |
| Registry Client | Communicates with the authoritative Dillweed Registry to retrieve Capability Records matching parsed query paths. Handles registry unavailability gracefully. |
| Trust Evaluator | Filters and scores candidate records against the caller's declared trust policy. Applies tier minimums, permission checks, and signature verification. |
| Ranking Engine | When multiple candidates remain after trust filtering, ranks them by relevance, trust tier, usage history, and version preference. |
| Response Composer | Packages the selected Capability Record into the standardized resolver response, including resolution metadata, trust signals, and audit identifiers. |
2.2 Data Flow
Receive Query
Agent submits a resolution request containing a namespace path (or pattern), a minimum trust tier, required permissions, and optional context hints.
Parse & Validate
The Query Parser validates URI syntax, normalizes path components, and expands wildcards. Malformed queries return immediately with a structured error — no registry contact occurs.
Cache Check
The resolver checks its local cache for a valid, non-expired Capability Record matching the query. Cache hits bypass registry contact entirely and proceed directly to trust evaluation.
Registry Lookup
On cache miss, the Registry Client queries the authoritative Dillweed Registry, retrieves all matching Capability Records, and stores them in the local cache with appropriate TTLs.
Trust Filter & Rank
The Trust Evaluator removes records that fail the caller's minimum trust tier or lack required permissions. The Ranking Engine orders remaining candidates by trust score and contextual relevance.
Compose & Return
The top-ranked record is packaged into a resolver response. The response includes the full Capability Record, a resolution trace for audit, and the trust signals used in ranking.
2.3 Deployment Modes
| Mode | Description | Typical Use |
|---|---|---|
| Hosted | DillClaw operated as a shared service at a known endpoint. Agents query it via HTTP. | Most agents; lowest integration overhead |
| Embedded | DillClaw library linked directly into an agent runtime. Shares process with the agent. | Latency-sensitive or airgapped deployments |
| Sidecar | DillClaw runs as a local process alongside an agent container, communicating over loopback. | Containerized deployments requiring isolation |
| Gateway | DillClaw integrated into a platform gateway layer, resolving on behalf of all downstream agents. | Enterprise or platform-scale deployments |
Resolution Protocol
The resolution protocol defines the contract between a calling agent and an 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
{
"query": "dillweed://research.market.*.vendors", // required
"trust_minimum": "verified", // optional, default: "experimental"
"permissions": ["query", "export"], // optional
"version_pref": "stable", // optional: "stable" | "latest" | semver
"context": {
"caller_id": "agent:procurement-v2",
"session_id": "sess_abc123"
},
"max_results": 3 // optional, default: 1
}
3.2 Response Structure
{
"status": "resolved", // "resolved" | "no_match" | "error"
"query": "dillweed://research.market.*.vendors",
"resolved_at": "2026-03-27T14:22:01Z",
"trace_id": "trc_9f2a...",
"results": [
{
"rank": 1,
"capability": { /* full Capability Record */ },
"trust_score": 0.94,
"trust_signals": ["dnso_verified", "14mo_history", "sig_valid"],
"cache_hit": false
}
],
"resolver_version": "dillclaw/0.1.0"
}
3.3 Resolution Guarantees
- Determinism — Given the same query and registry state, a conformant resolver must return the same ranked result.
- No silent failure — Every request returns a structured response. A resolver that cannot answer returns a documented error state, never an empty body or unhandled exception.
- Auditability — Every response includes a
trace_idthat can be used to reconstruct the full resolution decision from resolver logs. - Trust transparency — The trust signals used in ranking are always returned alongside the result, so the calling agent can evaluate the basis for selection.
- Signature pass-through — DNSO cryptographic signatures on Capability Records are never stripped or modified by the resolver. The agent receives them verbatim for independent verification.
Query Language
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:
dillweed://research.market.intel.vendors
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:
dillweed://research.market.*.vendors
dillweed://research.market.*
4.3 Version Pinning
A version suffix pins the query to a specific capability version or range:
dillweed://research.market.intel.vendors:1.2.0
dillweed://research.market.intel.vendors:^1.2
4.4 Query Constraints
- Wildcards may not appear in the first path component (the domain segment)
- A query may contain at most two wildcards
- Double-star (
**) recursive matching is not supported in v0.1 - Queries with no matching results always return
status: "no_match"with a documented reason — never an empty results array without explanation
API Reference
A DillClaw Resolver exposes a minimal HTTP API. All endpoints accept and return application/json. Authentication is optional in v0.1 but recommended for production deployments.
5.1 Core Endpoints
Primary resolution endpoint. Accepts a resolution request body and returns a ranked list of matching Capability Records. This is the only endpoint required for a minimally conformant implementation.
POST /resolve HTTP/1.1
Content-Type: application/json
{
"query": "dillweed://research.market.intel.vendors"
}
Direct Capability Record retrieval by fully qualified namespace path. Returns a single record or 404 if not found. No trust filtering is applied — the raw registered record is returned. Useful for verification and tooling workflows.
GET /capability/research.market.intel.vendors HTTP/1.1
Returns resolver health status, current registry connection state, cache statistics, and the resolver's own version string. Required for all conformant implementations.
Returns the full resolution trace for a past resolution operation, identified by the trace_id included in every response. Enables audit and debugging. Traces are retained for a minimum of 72 hours.
Accepts an array of resolution requests (maximum 50 per batch) and returns an array of responses in matching order. Useful for agents that need to resolve multiple capabilities in a single operation. Partial failure is permitted — individual request failures return error objects in-place without failing the entire batch.
5.2 Request Headers
| Header | Required | Description |
|---|---|---|
| Content-Type | Yes | Must be application/json |
| X-DillClaw-Caller | No | Caller identifier for audit logging. Recommended for production. |
| X-DillClaw-Session | No | Session identifier for grouping related resolution operations in traces. |
| Authorization | No (v0.1) | Bearer token if the resolver requires authentication. Format TBD in v0.2. |
Trust Evaluation Engine
Trust evaluation is the core value proposition of DillClaw beyond simple registry lookup. A raw registry can return what exists. DillClaw answers what should be used — through a documented, auditable evaluation process applied to every candidate.
6.1 Evaluation Pipeline
Tier Gate
Any candidate with a trust tier below the caller's trust_minimum is rejected immediately. This is a hard filter — no scoring applied to eliminated candidates.
Permission Check
Any candidate lacking a required permission from the caller's permissions array is rejected. Permission checking is exact-match only in v0.1.
Signature Verification
DNSO cryptographic signatures are verified against the published DNSO public key. Candidates with invalid or missing signatures are marked sig_unverified and may be filtered depending on caller policy.
Endpoint Liveness
Optionally (controlled by caller policy), the resolver performs a lightweight endpoint probe to confirm the capability endpoint is reachable. Results are cached per TTL to avoid probe overhead on every request.
Trust Scoring
Surviving candidates are scored on a 0–1 scale using a weighted combination of: trust tier (40%), usage history (30%), signature validity (20%), and endpoint liveness (10%). Weights are fixed in v0.1 for determinism and comparability across implementations.
6.2 Trust Score Composition
| Signal | Weight | Notes |
|---|---|---|
| Trust tier | 40% | Canonical=1.0, Verified=0.85, Trusted=0.65, Experimental=0.30 |
| Usage history | 30% | Months of continuous valid registration, capped at 24 months for full score |
| Signature validity | 20% | DNSO sig present and valid=1.0, absent=0.5, invalid=0.0 |
| Endpoint liveness | 10% | Reachable=1.0, unchecked=0.5, unreachable=0.0 |
Trust scores are always returned with their constituent signals, never as a single opaque number. An agent receiving a result with a score of 0.72 should also receive the breakdown showing why — so it can apply its own judgment to the resolver's recommendation rather than treating it as authoritative.
Caching & Performance
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
- Local record cache — Capability Records retrieved from the registry are cached locally. Cache key is the fully qualified namespace path. TTL is set by the registry per record and must be respected.
- Liveness probe cache — Endpoint liveness results are cached independently with a shorter TTL (default: 60 seconds). Probes are not 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
| Cache Type | Source of TTL | Default TTL | Maximum TTL |
|---|---|---|---|
| Capability Record | Registry-provided per record | 300s | 3600s |
| Endpoint liveness | Resolver-configured | 60s | 300s |
| Negative (not found) | Resolver-configured | 30s | 120s |
| Registry unavailable | Resolver-configured | Stale-while-revalidate | 1800s |
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 in the response. If no cached record exists and the registry is unreachable, return a structured error.
7.4 Performance Targets
| Scenario | Target P50 | Target P99 |
|---|---|---|
| Cache hit, no liveness probe | < 5ms | < 20ms |
| Cache miss, registry reachable | < 80ms | < 300ms |
| Cache miss + liveness probe | < 150ms | < 500ms |
Error Handling
Every error state in DillClaw returns 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
{
"status": "error",
"error_code": "QUERY_MALFORMED",
"message": "Path component 'RESEARCH' must be lowercase ASCII",
"suggestion": "Use 'research' instead of 'RESEARCH'",
"trace_id": "trc_err_7c3f...",
"query": "dillweed://RESEARCH.market.intel"
}
8.2 Error Codes
| HTTP | Error Code | Meaning |
|---|---|---|
| 400 | QUERY_MALFORMED | Namespace URI fails syntax validation. Resolver stopped before registry contact. |
| 400 | QUERY_TOO_BROAD | Wildcard pattern would match more than 200 candidates. Narrow the query. |
| 404 | NO_MATCH | Query is valid but no registered capabilities match it. |
| 404 | TRUST_FILTERED | Candidates exist but all were eliminated by the caller's trust policy. |
| 422 | PERMISSION_MISMATCH | Candidates exist and meet trust tier, but none carry all required permissions. |
| 503 | REGISTRY_UNAVAILABLE | Resolver could not contact the authoritative registry and has no valid cached data. |
| 503 | REGISTRY_STALE | Serving stale cached data. Registry unreachable. Includes cached_at timestamp. |
| 500 | RESOLVER_FAULT | Internal resolver error. Includes trace ID for diagnostics. Should be reported. |
Integration Guide
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:
# Instead of: tool = hardcoded_tools["vendor_comparison"]
result = dillclaw.resolve(
query = "dillweed://research.market.intel.vendors",
trust_min = "verified",
permissions = ["query", "export"]
)
# Result contains MCP-compatible endpoint and schema
tool = MCPTool(
endpoint = result.capability.endpoint,
input_schema= result.capability.input_schema,
protocol = "mcp"
)
response = tool.call(vendor_list)
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:
# Resolve the target agent by namespace path
result = dillclaw.resolve(
query = "dillweed://agents.analysis.financial.*",
trust_min= "trusted"
)
# Use the resolved endpoint to fetch the A2A agent card
agent_card = A2A.fetch_card(result.capability.endpoint)
response = A2A.send_task(agent_card, task_payload)
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:
result = dillclaw.resolve("dillweed://data.enrichment.company.profile")
# Validate request body against resolved input schema
validate(request_body, result.capability.input_schema)
# Invoke directly
response = http.post(
url = result.capability.endpoint,
body = request_body
)
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_idfrom 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 published DNSO public key rather than relying solely on resolver trust evaluation.
A Worked Example
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.
Agent identifies capability need
A financial analysis agent needs to enrich a company identifier with current firmographic data. It has been configured to use the Dillweed namespace for capability resolution rather than a hardcoded endpoint.
Agent submits resolution request
The agent posts to /resolve with query dillweed://data.enrichment.company.*, trust_minimum: "verified", and permissions: ["query", "export"]. The * wildcard signals intent to find the best available enrichment capability, not a specific provider.
DillClaw parses and checks cache
The Query Parser validates the URI and expands the wildcard. The cache contains a 4-minute-old record for data.enrichment.company.profile within TTL — the registry is not contacted. Trust evaluation proceeds against the cached record.
Trust evaluation filters and scores
Three candidates exist in the expanded match set. One is experimental — eliminated by tier gate. One is trusted but lacks the export permission — eliminated by permission check. The remaining candidate is verified, carries a valid DNSO signature, and has 18 months of continuous registration. Trust score: 0.91.
Response returned to agent
DillClaw returns status: "resolved" with the full Capability Record, trust score 0.91, signals ["dnso_verified", "18mo_history", "sig_valid"], cache_hit: true, and a trace_id. Total resolver latency: 3ms.
Agent validates signature and invokes
The agent verifies the DNSO signature independently, validates its request payload against the returned input_schema, then calls the resolved endpoint directly. The resolver is not in the invocation path — it returned the map; the agent navigates it.
The agent never knew the underlying provider. It never needed to. It expressed an intent, received a trusted endpoint, verified it cryptographically, and invoked. If the underlying provider changes next week, the namespace path remains stable, the trust signals are re-evaluated at the next resolution, and the agent's code is unchanged.
Security Model
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.
11.1 Threat Model
| Threat | Mitigation |
|---|---|
| Registry poisoning | DNSO cryptographic signatures on Capability Records. Invalid signatures result in trust score penalty or elimination per caller policy. |
| Cache poisoning | TTLs enforced strictly. Cached records include the DNSO signature, verified at scoring time regardless of cache source. |
| Resolver impersonation | Resolvers should be identified by DNS + TLS. In v0.2, a resolver identity certificate model will be defined. |
| Stale trust signals | Stale responses are disclosed explicitly. Agents may reject stale results by policy. Trust score does not degrade on staleness alone. |
| Query enumeration | Wildcard queries return a maximum of 200 results. Rate limiting is recommended at the resolver deployment level. |
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 — DillClaw does not authenticate which agent is making a resolution request in v0.1
- Data in transit to the capability — TLS for the resolution request is expected; TLS for the capability invocation is the agent's responsibility
What Must Be Built
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.
Conformant Resolver Implementation
A working implementation of the /resolve and /health endpoints, passing against a reference test suite. Language-agnostic; the first implementation may be any stack.
Live Registry Connection
The resolver connected to a live Dillweed Registry endpoint returning real Capability Records for at least three registered capabilities across two namespace categories.
End-to-End Resolution Trace
A publicly documented resolution trace — query in, Capability Record out, DNSO signature verified — demonstrating the full protocol path as specified in §10.
MCP or A2A Integration Example
A working integration with at least one of MCP or A2A, demonstrated with a real agent making at least one capability invocation via an DillClaw-resolved endpoint.
Public Reference Deployment
A hosted DillClaw endpoint at a stable URL (DillClaw.ai or equivalent) accepting resolution requests from any caller, with uptime monitoring and a public health status page.
Relationship to DNS
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
- Maps human-readable names to IP addresses
- Hierarchical namespace with a governed root
- Caching at multiple layers for performance
- Authoritative + recursive resolver model
- Stable names survive infrastructure changes
- Maps semantic names to invocable endpoints
- Hierarchical namespace with a governed root
- Caching at resolver layer with TTL discipline
- Authoritative registry + resolver model
- Stable names survive provider changes
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.
DillClaw tells you what to trust and use.
DillClaw is the operational layer for the Dillweed Namespace. The namespace defines what can exist and what it means. DillClaw defines how it is found and used. Neither document is complete without the other. The full infrastructure is the combination: a governed naming layer and a conformant resolver that brings those names into operational reality.