# Mapping to xRegistry

This guide binds the [Distribution
Substrates](distribution-substrates.md) contract to [[xRegistry]],
a hierarchical registry model organized as Registry → Groups → Resources
→ Versions. xRegistry contributes structure, identity, versioning,
cross-referencing, and a registry API; it has no native content-addressing
or signature primitive.

Of the binding invariants, the xRegistry binding **delegates** entry
identity, catalog structure, artifact content, and manifest discovery to
xRegistry's own primitives, but **carries** content integrity and signing
in the Trust Manifests' signatures and the entry's `digest`. These remain
authoritative exactly as in plain-HTTP distribution, because xRegistry
cannot express either guarantee natively.

## Conceptual Mapping

An AI Catalog document maps to an xRegistry **Group** whose **Resources**
are the catalog entries; each entry's artifact is the Resource document.

| AI Catalog (Logical) | xRegistry (Physical) |
|:---|:---|
| AI Catalog document | A Group instance (e.g. in a `aicatalogs` Group type), or the Registry root when serving a single catalog |
| Catalog Entry | A Resource within that Group |
| Entry `identifier` | Resource-local `<SINGULAR>id` and `xid`, with the complete URI preserved in the `ai-catalog.identifier` label |
| Entry `type` | Version `contenttype` (with `format` when a named format applies) |
| Entry artifact content | Resource document — inline (`<RESOURCE>` / `<RESOURCE>base64`) or external (`<RESOURCE>url`) |
| Entry metadata (displayName, description, tags) | `name`, `description`, `labels` |
| Entry version | Version `versionid` |
| Nested Catalog Entry | A nested Group referenced from the entry's Resource via `meta.xref` |
| Contributor Trust Manifests | An array in an extension attribute on the Resource, or related Resources referenced by `xref` |
| Content integrity (`entry.digest`) | Carried in a Resource extension attribute (xRegistry has no native digest) |
| Signing | Trust Manifest signatures retained in a Resource extension attribute (xRegistry has no native signature) |

## Packing: AI Catalog to xRegistry

Tooling converts an AI Catalog JSON document into xRegistry resources:

1. **The catalog** becomes a Group instance. Catalog-level metadata maps
   to Group attributes: `displayName` to `name`, host identity and other
   metadata to `labels` or extension attributes.

2. **Each catalog entry** becomes a Resource in that Group. The entry's
   artifact content is stored as the Resource document — inline via
   `<RESOURCE>` / `<RESOURCE>base64`, or by reference via `<RESOURCE>url`.
   `type` maps to `contenttype`; entry metadata maps to `name`,
   `description`, and `labels`. The complete entry `identifier` URI is
   preserved in the `ai-catalog.identifier` label. Multiple entry versions
   map to Versions.

3. **Trust Manifests** are carried as an array in a Resource
   extension attribute (for example `aicatalog_trustmanifests`), or as related
   Resources referenced from `meta.xref`, preserving each manifest, including
   its contributor, subject, and signature. Carry `entry.digest` separately,
   for example as `aicatalog_digest`. Preserve the signed manifest contents
   so signature payloads can be reconstructed unchanged.

4. **Nested catalog entries** become nested Groups; the parent entry's
   Resource references the nested Group through `meta.xref`.

## Unpacking: xRegistry to AI Catalog

Tooling converts xRegistry resources back to an AI Catalog JSON document:

1. Retrieve the Group in document view (the xRegistry `?doc` projection),
   which returns a single self-contained JSON document analogous to
   `ai-catalog.json`.
2. For each Resource, reconstruct `entry.identifier` from the
   `ai-catalog.identifier` label, read its document (inline or via
   `<RESOURCE>url`) and `contenttype` to recover the entry's artifact content
   and `type`, and map `name`, `description`, and remaining `labels` back to
   entry metadata.
3. Restore `trustManifests` and `digest`
   from their extension attributes or related Resources, then verify the
   signatures and signed artifact bindings against the reconstructed entry
   and served bytes.
4. Resolve `xref`'d nested Groups into nested catalog entries.
5. Assemble the logical `application/ai-catalog+json` document.

## xRegistry Document Example

The following shows the xRegistry document-view representation of a Group
holding two entries. This is generated by tooling, not authored by hand:

```json
{
  "aicatalogid": "acme-services",
  "self": "https://registry.acme.com/aicatalogs/acme-services",
  "xid": "/aicatalogs/acme-services",
  "epoch": 1,
  "name": "Acme Services Inc.",
  "entriesurl": "https://registry.acme.com/aicatalogs/acme-services/entries",
  "entriescount": 2,
  "entries": {
    "finance-a2a": {
      "entryid": "finance-a2a",
      "xid": "/aicatalogs/acme-services/entries/finance-a2a",
      "name": "Acme Finance A2A Agent",
      "contenttype": "application/a2a-agent-card+json",
      "labels": {
        "ai-catalog.identifier": "urn:air:acme.com:agent:finance-a2a"
      },
      "entryurl": "https://cards.acme.com/finance/a2a-card.json",
      "aicatalog_digest": "sha256:aaa111...",
      "aicatalog_trustmanifests": [
        {
          "contributor": "did:web:acme.com",
          "subject": {
            "identifier": "urn:air:acme.com:agent:finance-a2a",
            "type": "application/a2a-agent-card+json",
            "digest": "sha256:aaa111..."
          },
          "signature": {
            "signer": "did:web:acme.com",
            "profile": "did-web-v1",
            "issuedAt": "2025-01-01T00:00:00Z",
            "jws": "eyJhbGciOiJFUzI1NiIsImtpZCI6ImRpZDp3ZWI6YWNtZS5jb20jcmVsZWFzZS1zaWduaW5nLWtleSIsInR5cCI6ImFpLWNhdGFsb2ctdHJ1c3QtbWFuaWZlc3QrandzIn0..detached-JWS"
          }
        }
      ]
    },
    "finance-mcp": {
      "entryid": "finance-mcp",
      "xid": "/aicatalogs/acme-services/entries/finance-mcp",
      "name": "Acme Finance MCP Server",
      "contenttype": "application/mcp-server-card+json",
      "labels": {
        "ai-catalog.identifier": "urn:acme:server:finance-mcp"
      },
      "entryurl": "https://cards.acme.com/finance/mcp-server.json"
    }
  }
}
```

## Content Integrity and Signing

Because xRegistry has no native content-addressing or signature
primitive, this binding carries the entry digest and signed Trust Manifests.
Verification uses the reconstructed logical entry and the served Resource
document during unpacking, as in plain-HTTP distribution. Resource extension
attribute names are transport details; signatures authenticate the logical
Trust Manifests, not the xRegistry representation.