diff --git a/adr/0021-separate-artifact-identity-from-registry-coordinates.md b/adr/0021-separate-artifact-identity-from-registry-coordinates.md index 1ce1a97..c1185a3 100644 --- a/adr/0021-separate-artifact-identity-from-registry-coordinates.md +++ b/adr/0021-separate-artifact-identity-from-registry-coordinates.md @@ -13,8 +13,8 @@ Existing registries commonly identify artifacts with native coordinates, such as a registry namespace and artifact name. When projecting those -records as AI Catalog entries, a registry may have no publisher-assigned -`urn:air` identifier. +records as AI Catalog entries, the catalog operator may have no +publisher-assigned `urn:air` identifier. Using the registry's domain in `urn:air` is easy, but the current format defines that domain as the artifact publisher. Requiring the publisher's @@ -46,33 +46,34 @@ A publisher-authorized `urn:air` identifier is one assigned by the artifact publisher or its authorized delegate, with the artifact publisher's domain in the `{publisher}` segment. -A registry uses a stateful preserve-or-mint policy: +Catalog projection creates a Catalog Entry from either a source Catalog +Entry in another AI Catalog or a source record in another system. When +incorporating a projected entry for the first time, a catalog operator +selects its identifier by applying these rules in order: -1. If the registry previously published an identifier for the artifact, - reuse it, even if another identifier becomes available later. -2. Otherwise, if the source entry contains a publisher-authorized - `urn:air` identifier, preserve it exactly. -3. Otherwise, the registry may preserve or replace a non-`urn:air` source - identifier. Non-`urn:air` identifiers have no guaranteed portability +1. If the source contains a publisher-authorized `urn:air` identifier, + preserve it exactly. +2. Otherwise, the operator may preserve a non-`urn:air` source identifier + or replace it. Non-`urn:air` identifiers have no guaranteed portability across catalogs. -4. When assigning a new identifier, a registry that becomes the artifact +3. When assigning a new identifier, an operator that becomes the artifact publisher should use `urn:air` with its own domain in the `{publisher}` - segment. A registry acting as an authorized delegate should use + segment. An operator acting as an authorized delegate should use `urn:air` with the delegating publisher's domain in that segment. An - independent registry must use a non-`urn:air` identifier under its own - control. + operator that is neither the artifact publisher nor its authorized + delegate must use a non-`urn:air` identifier under its own control. -Merely hosting or aggregating an entry does not make a registry the +Operating a catalog or aggregating an entry does not make its operator the artifact publisher. Changing a previously published primary identifier requires an explicit migration mechanism, which this decision does not define. -The registry assigning an identifier, the catalog `host`, and the -artifact `publisher` are independent roles. A registry-issued identifier -does not imply that the registry published the artifact. +The catalog operator and artifact publisher are distinct roles. An +operator-assigned identifier does not imply that the operator published +the artifact. -A registry may retain replaced source identifiers or registry-native +A catalog operator may retain replaced source identifiers or source-system coordinates. When retained, they should be stored in a namespaced entry extension. They do not affect catalog uniqueness or establish publisher identity, trust, or equivalence with another identifier. @@ -80,15 +81,15 @@ identity, trust, or equivalence with another identifier. ## Consequences - Publisher-authorized `urn:air` identifiers are preserved across - registries and mirrors. -- Non-`urn:air` identifiers remain valid, but registries may replace them - when they are unsuitable for the destination catalog. + catalogs and mirrors. +- Non-`urn:air` identifiers remain valid, but catalog operators may preserve + or replace them. - Legacy records can be projected without publisher enrollment by using - a registry-issued identifier. -- Two registries may assign different identifiers to the same artifact - when no publisher-authorized `urn:air` identity is available. The model - does not claim equivalence it cannot establish. -- No new core field is added; native coordinates use `extensions`. + an operator-assigned identifier. +- Two catalog operators may assign different identifiers to the same + artifact when no publisher-authorized `urn:air` identity is available. + The model does not claim equivalence it cannot establish. +- No new core field is added; source-system coordinates use `extensions`. - Generic aliases and primary-identifier migration remain future work. ## Alternatives Considered @@ -100,5 +101,6 @@ Requiring a publisher-domain `urn:air` was rejected as a universal rule because it makes automatic projection depend on publisher enrollment. Adding `aliases`, `nativeIdentifier`, or `identifiers[]` was deferred -because registry coordinates do not necessarily assert logical identity -equivalence, and `extensions` is sufficient for the immediate use case. +because source-system coordinates do not necessarily assert logical +identity equivalence, and `extensions` is sufficient for the immediate +use case. diff --git a/specification/ai-catalog.md b/specification/ai-catalog.md index 88a026c..b37c74e 100644 --- a/specification/ai-catalog.md +++ b/specification/ai-catalog.md @@ -203,9 +203,9 @@ A Catalog Entry object describes a single AI artifact in the catalog. It MUST contain the following members: `identifier` -: A string uniquely identifying this artifact. This field is an open text format (e.g., any valid URI or URN is accepted). Consumers that do not recognize an identifier scheme MUST treat the value as opaque. Identifier syntax alone does not verify publisher identity or establish trust. For open or federated systems, a globally unique absolute URI is RECOMMENDED. An artifact publisher that wants an entry identifier to be preserved when the artifact appears in other catalogs SHOULD use the AI Catalog-specific `urn:air` naming structure with its own domain in the `{publisher}` segment. A catalog incorporating an entry for the first time with a publisher-authorized `urn:air` identifier MUST preserve that identifier exactly. +: A string uniquely identifying this artifact. This field is an open text format (e.g., any valid URI or URN is accepted). Consumers that do not recognize an identifier scheme MUST treat the value as opaque. Identifier syntax alone does not verify publisher identity or establish trust. For open or federated systems, a globally unique absolute URI is RECOMMENDED. An artifact publisher that wants an entry identifier to be preserved when the artifact appears in other catalogs SHOULD use the AI Catalog-specific `urn:air` naming structure with its own domain in the `{publisher}` segment. A catalog operator incorporating an entry for the first time with a publisher-authorized `urn:air` identifier MUST preserve that identifier exactly. - **AI Catalog Publisher Naming Format:** + **`urn:air` Identifier Format:** `urn:air:{publisher}:{namespace}:{name}` - `{publisher}`: The domain name of the organization publishing the artifact (e.g., `example.com`). @@ -219,7 +219,7 @@ It MUST contain the following members: For closed or local systems where a different identifier format is used, client implementations are responsible for parsing and processing the custom format as appropriate. - See [Multi-Version Entries](#multi-version-entries) for uniqueness rules when multiple versions are present, and [Registry Projection](#registry-projection) for identifiers assigned while projecting an existing registry. + See [Multi-Version Entries](#multi-version-entries) for uniqueness rules when multiple versions are present, and [Catalog Projection](#catalog-projection) for identifiers assigned while projecting an existing Catalog Entry or source-system record. `type` : A string containing the identifier that specifies the type of the @@ -435,7 +435,7 @@ When `version` is present, the combination of `identifier` and `version` MUST be unique within the catalog. When `version` is absent, `identifier` alone MUST be unique. The `identifier` SHOULD be stable across versions. Only publisher-authorized `urn:air` identifiers receive a cross-catalog -preservation requirement, as defined in [Registry Projection](#registry-projection). +preservation requirement, as defined in [Catalog Projection](#catalog-projection). Clients that need only the latest version SHOULD sort entries sharing the same `identifier` by `version` (when parseable as a semantic @@ -469,46 +469,44 @@ For example, a catalog listing two versions of the same agent: Both entries share the same `identifier` but have distinct `version` values, so the combination is unique. -## Registry Projection +## Catalog Projection A publisher-authorized `urn:air` identifier is one assigned by the artifact publisher or its authorized delegate, with the artifact publisher's domain in the `{publisher}` segment. -A registry creating an entry from an existing record or catalog entry -MUST select its primary identifier by applying these rules in order: +Catalog projection creates a Catalog Entry from either a source Catalog +Entry in another AI Catalog or a source record in another system. When +incorporating a projected entry for the first time, a catalog operator +MUST select its identifier by applying these rules in order: -1. If the registry previously published an identifier for the artifact, - it MUST reuse that identifier, even if another identifier becomes - available later. -2. Otherwise, if the source entry contains a publisher-authorized - `urn:air` identifier, it MUST preserve the identifier exactly. -3. Otherwise, the registry MAY preserve a non-`urn:air` source identifier +1. If the source contains a publisher-authorized `urn:air` identifier, + the operator MUST preserve it exactly. +2. Otherwise, the operator MAY preserve a non-`urn:air` source identifier or replace it. Non-`urn:air` identifiers have no guaranteed portability across catalogs. -4. When assigning a new identifier, a registry that becomes the artifact +3. When assigning a new identifier, an operator that becomes the artifact publisher SHOULD use `urn:air` with its own domain in the `{publisher}` - segment. A registry acting as an authorized delegate SHOULD use + segment. An operator acting as an authorized delegate SHOULD use `urn:air` with the delegating publisher's domain in that segment. An - independent registry MUST use a non-`urn:air` identifier under its own - control. + operator that is neither the artifact publisher nor its authorized + delegate MUST use a non-`urn:air` identifier under its own control. -Merely hosting or aggregating an entry does not make a registry the -artifact publisher. -A registry MUST NOT infer publisher authorization from the artifact's URL -or an unsigned `publisher` field. +Operating a catalog or aggregating an entry does not make its operator the +artifact publisher. A catalog operator MUST NOT infer publisher +authorization from the artifact's URL or an unsigned `publisher` field. Adopting a different primary identifier after publication requires an explicit migration mechanism, which this specification does not define. -A registry-assigned identifier identifies the artifact, not a particular -version or registry record. It MUST remain stable across -versions, registry-coordinate changes, and retrieval-URL changes, and -MUST NOT be reassigned to another artifact. The registry assigning the -identifier, the catalog `host`, and the artifact `publisher` are -independent roles. +An identifier assigned by a catalog operator identifies the artifact, not +a particular version or source record. It MUST remain stable across +versions, source-coordinate changes, and retrieval-URL changes, and MUST +NOT be reassigned to another artifact. The catalog operator and artifact +publisher are distinct roles. The operator is the entity identified by the +top-level `host` field when that field is present. -A registry MAY retain replaced source identifiers or registry-native +A catalog operator MAY retain replaced source identifiers or source-system coordinates. If retained, they SHOULD be stored in a namespaced entry extension. They do not participate in catalog uniqueness or establish publisher identity, trust, or equivalence with another identifier.