The Dillweed Registry is the authoritative persistence layer for the Dillweed Namespace. It stores Capability Records — the structured documents that define what a registered capability is, how it behaves, and how it can be invoked. It signs each record cryptographically at registration time using the DNSO (Dillweed Namespace Stewardship Organization) private key, making every record independently verifiable by any party holding the published DNSO public key. It exposes a governed HTTP API for registration, lookup, revocation, and trust tier management.

This document specifies the Registry's data model, API contract, signing protocol, storage requirements, registration rules, revocation semantics, and integration with the DillClaw Resolver layer. Implementations that conform to this specification are considered Dillweed Registry-compliant.

This is the third core infrastructure document in the Dillweed specification stack. It should be read alongside the Dillweed Namespace Standard v0.4 and the DillClaw Resolver Specification v0.1. Those documents define the naming model and the resolution protocol respectively. This document defines the authoritative data store that makes both operational.

The Dillweed Registry occupies the foundational position in the three-layer agentic coordination stack. It is the layer all other layers depend on — without it, neither the namespace nor the resolver has authoritative data to operate against.

The Registry's relationship to the resolver mirrors the relationship between a DNS zone file and a DNS resolver — the resolver handles queries, but the authoritative data lives in the zone. The Registry is the zone. Unlike DNS zone files, Registry records carry cryptographic signatures and structured trust metadata that resolvers evaluate beyond simple presence.

A conformant Dillweed Registry consists of four functional components. These may be deployed together as a single service or independently — the specification is agnostic to deployment topology provided the external API behavior is conformant.

2.1 Functional Components

2.2 Deployment Modes

The reference implementation described in this document is a local development mode registry. It is fully conformant with this specification and may be promoted to authoritative status by operating it at a stable public endpoint and publishing its DNSO public key at the canonical URL.

The Capability Record (CR) is the atomic unit of the registry. Every registered capability is represented by exactly one CR per version. The schema defined here is the canonical storage schema — a superset of the CR schema defined in the Dillweed Namespace Standard, which defines only the fields relevant to resolution.

3.1 Field Definitions

3.2 Example Capability Record

3.3 Uniqueness Constraint

A name + version pair must be unique among active (non-revoked) records. Attempting to register a duplicate returns 409 ALREADY_EXISTS. A revoked record's name and version may be re-registered — revocation frees the slot for a corrected submission.

The Registry exposes a minimal HTTP API. All endpoints accept and return application/json except /pubkey, which returns PEM text. Write endpoints should be protected by a bearer token in production deployments via the REGISTRY_ADMIN_TOKEN environment variable.

4.1 Error Response Format

Every Capability Record stored in the Registry carries a DNSO cryptographic signature. The signature is the mechanism that makes records authoritative — it allows any agent or resolver to verify independently that a record was written by the DNSO and has not been altered since registration.

5.1 Algorithm

The Registry uses Ed25519 (Edwards-curve Digital Signature Algorithm, RFC 8032) for all record signing. Ed25519 was chosen for its combination of strong security, compact signatures (~88 base64url characters), fast verification, and wide support across languages and runtimes including Node.js built-ins, Python, Go, Rust, and browser WebCrypto APIs.

5.2 Canonical JSON

Signatures are computed over a deterministic canonical JSON representation of the record, not the full stored document. This ensures the signature is stable regardless of storage format, field ordering, or whitespace. The canonical JSON includes exactly the eight fields below, with keys sorted alphabetically and no whitespace:

5.3 Signature Format

Signatures are serialized as a prefixed base64url string: dnso_v1_ followed by the base64url-encoded raw Ed25519 signature bytes (ieee-p1363 encoding). The version prefix enables future algorithm migration without breaking existing parsers.

5.4 Independent Verification Steps

5.5 Keypair Custody

The DNSO private key is the root of trust for the entire namespace. It must be stored at file mode 0600, never committed to version control, never transmitted over any network interface, and backed up to at least two encrypted, physically separate media. If the private key is lost, all existing signatures become unverifiable and a keypair reset is required.

5.6 Planned Key Rotation

Routine DNSO key rotation — distinct from emergency keypair reset — should be performed periodically to limit the blast radius of undetected key compromise. During planned rotation, the prior public key must be preserved and served alongside the new key for a defined overlap window (recommended minimum: 30 days). This permits staged resolver refresh: resolvers that have cached the old public key continue to verify existing records while they refresh to the new key at their next scheduled update cycle. Records signed under the prior key remain valid during the overlap window. At the close of the overlap window, all active records must be re-signed under the new key and the prior key retired. The overlap window start and end dates must be disclosed publicly and logged to the registration audit trail.

The Registry uses a relational data model. The reference implementation uses SQLite with WAL (Write-Ahead Logging) journal mode, providing ACID guarantees, crash safety, and zero-configuration deployment. Alternative conformant implementations may use any storage system that satisfies the durability and query requirements.

6.1 Core Tables

6.2 Soft-Delete Revocation

Revoked records are not deleted — they are marked with a revoked=1 flag and a revoke_reason. This preserves the audit trail: a revoked record demonstrates that a capability existed, was registered by a real party, and was retired for a documented reason. All API read responses filter on revoked=0 unless explicitly querying history.

6.3 Durability Requirements

• Records must survive process restart and system reboot without loss
• The registration log must be append-only — no rows may be deleted or modified
• WAL journal mode (or equivalent) is required for SQLite deployments to prevent corruption on unclean shutdown
• The DNSO keypair must be stored outside the database, in a file with mode 0600 or equivalent OS-level access control
• A backup of both the database and the keypair must be maintained on a separate physical medium, verified at least monthly

6.4 Schema Migration Philosophy

The meta.schema_version field records the current schema revision of the registry database. Schema migrations must be forward-readable for at least one minor version — a registry running schema version N+1 must remain capable of serving records to a resolver or client built against schema version N without error. This requirement ensures that ecosystem participants can upgrade on independent schedules without coordination failures. Breaking schema changes require a major version increment and must be announced with a minimum 60-day advance notice period.

The Registry enforces the following validation rules on all POST /register requests. A submission that fails any rule is rejected with 422 VALIDATION_FAILED and a structured errors array listing every failure simultaneously — callers receive all problems in a single response.

Revocation removes a Capability Record from active resolution immediately and permanently, while preserving it in the database for audit purposes. It is the governance mechanism that makes the trust layer meaningful — a namespace that cannot revoke bad actors cannot be trusted.

8.1 Revocation Semantics

• Immediate effect — A revoked record disappears from /lookup and /list at the moment of revocation. DillClaw Resolver caches may serve the record until their TTL expires; this is expected behavior, mirroring DNS TTL semantics.
• Reason required — All revocations must include a reason string. This is logged to the audit trail and provides the accountability the governance model requires.
• Scoped or full — Revocation may target a single name:version pair or all active versions of a capability by omitting the version field.
• Slot freed — After revocation, the name:version pair may be re-registered. This allows a capability to be replaced with a corrected version under the same name without breaking the namespace path.
• Audit retained — Revoked records remain in the database with revoked=1, the revocation reason, and a timestamp. They are never deleted.

8.2 Who May Revoke

In v0.1, any caller holding a valid admin token may revoke any record. In v0.2, a registrant identity model will allow registrants to revoke only their own records, while the DNSO retains authority to revoke any record for governance reasons. Until then, the admin token is the sole access control mechanism and should be held exclusively by the DNSO steward.

Trust tiers are the Registry's current assessment of a capability's reliability and standing. They are assigned at registration and updated through the /promote endpoint as a capability earns or loses standing over time.

Tier demotions — from a higher tier to a lower one — are permitted and logged. A capability that was verified but has become unreliable may be demoted to trusted or experimental without revocation, preserving its registration history while accurately reflecting its current standing.

The DillClaw Resolver connects to the Dillweed Registry as its authoritative data source. The integration is intentionally simple: the resolver polls /list to warm its local cache and queries /lookup on cache miss.

10.1 Connection Model

• Cache warm on startup — On startup, a DillClaw Resolver configured with DILLCLAW_REGISTRY_URL calls /list to load all active records into its in-process cache.
• Periodic refresh — The resolver re-fetches /list every 60 seconds by default. Revocations and tier changes propagate within this window.
• Graceful fallback — If the registry is unreachable, the resolver continues from its stale cache, disclosing staleness to callers via stale: true and cached_at in the response.
• Signature pass-through — The resolver never modifies DNSO signatures. They are returned verbatim to calling agents for independent verification.

10.2 Local Mac Mini Setup

10.3 Mirror Registry Semantics

Read-only mirror registries may be operated by third parties to improve availability and reduce latency for geographically distributed resolver deployments. Mirror registries must expose two additional fields in their /health response to permit resolver freshness validation:

• authoritative_snapshot_timestamp — the ISO 8601 timestamp of the most recent full synchronization from the authoritative registry. Resolvers use this to detect staleness beyond their acceptable threshold.
• authoritative_signature_hash — a hash of the authoritative registry's most recent /list response payload, as signed by the DNSO. Resolvers may compare this against a fresh fetch from the authoritative registry to confirm the mirror is not serving a divergent record set.

A resolver that cannot confirm mirror freshness within its acceptable staleness window should fall back to the authoritative registry or disclose staleness to callers via the stale: true flag. Mirror registries may not modify DNSO signatures and may not promote or revoke records — all writes are the exclusive authority of the authoritative DNSO registry.

The Registry's security model has two scopes: protecting the registry itself from unauthorized writes, and protecting consumers of registry data from tampered or spoofed records.

11.1 Threat Model

11.2 What the Registry Does Not Secure

• The capability endpoint itself — authentication to the capability is the provider's responsibility
• The content of capability responses — the registry makes no representation about what a capability returns
• Network transit to the registry — TLS is strongly recommended for production deployments but not enforced by this specification in v0.1

11.3 Rate Limiting and Abuse Prevention

Public read endpoints — /list, /lookup, and /verify — should enforce per-IP rate controls to prevent registry scraping and availability degradation. The reference implementation does not enforce rate limits in v0.1, as the primary deployment context is a controlled network. Production deployments serving public internet traffic should place the registry behind a reverse proxy (such as nginx or Caddy) configured with appropriate rate limiting rules. Write endpoints (/register, /revoke, /promote) are protected by bearer token authentication and should additionally be restricted by IP allowlist in production environments where the set of authorized callers is known and fixed.

This specification documents a system that exists as a deployable implementation and is being refined through operation. The following milestones define the transition from local development registry to authoritative public registry — the point at which this document describes operational infrastructure rather than a proposal.

The Dillweed Registry is the third core infrastructure specification in the coordination stack. Each document is necessary; none is sufficient alone.

The pattern mirrors every durable infrastructure stack in computing: a naming model, a resolution protocol, and an authoritative data store. HTTP named resources; servers served them; DNS resolved them. Kubernetes named workloads; kubelets ran them; etcd stored their state. The Dillweed stack follows the same structure — and like those predecessors, its durability depends on the registry being operated consistently, not just the protocols being specified clearly.