The Problem

Agents evolve. Breaking changes ship. Consumers need time to migrate. Yet today, ARD provides no mechanism for publishers to communicate:

1. How many versions are concurrently available — Can consumers still use v1.x while v2.0 is live? For how long?
2. What's coming next — Is a breaking change imminent? Can I discover preview/beta versions to plan ahead?
3. Migration expectations — How long do I have before the old version disappears? Will I be force-upgraded?
4. Impact assessment — Is this a minor patch or a rewrite that breaks my integration?

The existing spec has only an optional version string with no semantics. #45 (@marianogonzalez) adds lifecycle and deprecation — which answers "this version is dying." But consumers also need the forward-looking signal: "here's what's coming, when, and what it means for you."

This is especially critical in multi-registry/federated environments where consumers may be in a different organization than the publisher, with no out-of-band channel to learn about upcoming changes.

Prior Art & Dependencies

• Spec Proposal: No Lifecycle or Deprecation Model #45 (@marianogonzalez) — Lifecycle / Deprecation Model: Defines deprecated.replacedBy, endOfLifeDate, breakingChanges, migrationGuide. Our proposal is the forward-looking complement — signaling what's coming before deprecation happens, and formalizing the multi-version availability contract.
• Spec Proposal: Deployment metadata #44 (@marianogonzalez) — Deployment Metadata: Different versions may have different instance deployments (v2 only in us-east-1 during canary). Release policy and deployment metadata compose naturally.
• Spec Proposal: Dependencies manifest #42 (@marianogonzalez) — Dependencies Manifest: A new version may change its dependency requirements (e.g., identityType moves from API key to OBO). Release notes should surface dependency-breaking changes so consumers can pre-flight before upgrading.
• Semver (semver.org) — Industry standard for version numbering. This proposal does not mandate semver but provides a field to declare the versioning strategy.

Proposal: releasePolicy

Add an optional releasePolicy object to catalog entries that communicates the publisher's version management contract:

{
  "identifier": "urn:air:acme.com:finance:invoice-processor",
  "version": "2.0.0",
  "releasePolicy": {
    "versioningStrategy": "semver",
    "concurrentVersionsSupported": 2,
    "migrationWindow": "P90D",
    "availableVersions": [
      {
        "version": "1.5.2",
        "status": "stable",
        "releasedAt": "2025-11-01T00:00:00Z",
        "supportedUntil": "2027-01-01T00:00:00Z",
        "url": "https://api.acme.com/agents/invoice/v1"
      },
      {
        "version": "2.0.0",
        "status": "stable",
        "releasedAt": "2026-06-01T00:00:00Z",
        "lastModifiedAt": "2026-06-25T14:00:00Z",
        "contentDigest": "sha256:a3f2b8c9d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0c1d2e3f4a5b6c7d8e9f0a1",
        "url": "https://api.acme.com/agents/invoice/v2"
      },
      {
        "version": "3.0.0-beta",
        "status": "preview",
        "expectedRelease": "2026-09-01T00:00:00Z",
        "url": "https://preview.acme.com/agents/invoice/v3"
      }
    ],
    "releaseNotes": {
      "3.0.0-beta": {
        "breakingChanges": [
          "Authentication changed from API key to OAuth2",
          "Response schema now uses ISO 8601 dates",
          "Removed legacy XML output format"
        ],
        "newCapabilities": ["batch_processing", "multi_currency"],
        "removedCapabilities": ["xml_export"],
        "dependencyChanges": [
          {
            "identifier": "urn:air:salesforce.com:mcp:sales-cloud",
            "change": "minVersion bumped from 2.x to 3.0.0"
          }
        ],
        "impactAssessment": "high",
        "migrationGuide": "https://docs.acme.com/invoice-v3-migration"
      }
    },
    "deprecationPolicy": {
      "minimumNotice": "P60D",
      "gracePeriodAfterEOL": "P30D",
      "forceUpgradeAllowed": false
    }
  }
}

Field Definitions

Top-Level Fields

availableVersions[] Entry

releaseNotes[version]

deprecationPolicy

Discovery Value

Interaction With Other Proposals

Discussion Questions

1. Should availableVersions include all historical versions (full changelog) or only currently-accessible ones?
2. Should status: "preview" entries be excluded from default search results (opt-in discovery)?
3. Is impactAssessment (low/medium/high) too subjective? Should we define criteria, or leave it publisher-declared?
4. Should deprecationPolicy be per-version or per-agent (i.e., does the publisher commit to the same policy for all versions)?
5. How does this interact with version range queries in §7.1 search facets (e.g., "find agents with stable versions ≥ 2.0")?