Source: docs/integration/compatibility-and-versioning.md

Compatibility and versioning

Forgium versions its published public contract with

Semantic Versioning. The authoritative version is

info.version in the OpenAPI contract, which must match

contract_version in agent-manifest.json.

The changelog records every released public-contract change. It is not a

deployment log and does not describe internal-only changes.

Compatibility policy

Within a major version, existing clients that send valid requests and consume

documented responses continue to work without a code change.

Enum additions follow the same rule as response-shape additions when the enum

is published as a closed OpenAPI enum. Protocol enums (for example action and

capability lifecycle states) are therefore not extended within a major

version. Diagnostic codes are intended to be parsed tolerantly: their stable

catalog may grow without changing the meaning of existing codes, but clients

must not treat an unknown diagnostic code as impossible.

Closed objects (additionalProperties: false) are intentionally strict. A

client may validate response objects as strictly as the published schema, so a

new response property can break it even when that property is optional in the

new schema. Such changes require a new major contract version, a migration

guide, and a supported coexistence period or replacement route.

For a minor release, consumers should still regenerate types and review the

changelog before adopting optional additions. Clients must not rely on

undocumented fields, ordering, or platform-default text.

Contract 5 capability boundary

Contract 5 capabilities are read-only. Forgium rejects mutation capabilities,

approval metadata, candidate-resolution metadata, and legacy action or

resolution workflows. Use result_handling: "host_interaction" when a host

application needs a bounded preparation result; the host owns confirmation,

selection, authorization, idempotency, and any mutation.

Changelog

[7.0.0] - 2026-09-11

• Removes the draft → test → active capability lifecycle and the
  /activate operation.
• Imports and complete validated replacement revisions publish atomically as
  active; the only persisted lifecycle states are active and disabled.
• Adds explicit revision-guarded /enable and /disable operations. PATCH
  preserves lifecycle state, capability IDs remain immutable, and contract
  tests are independent records that do not change state or revision.
• Extends the private Admin service-audit projection with policy revisions,
  sanitized per-capability decisions, and terminal fallback phase; the public
  /messages contract is unchanged.
• Adds the diagnostic business_outcome_failed trace reason for capabilities
  that opt into the closed outcome contract; mutation execution remains
  host-owned.

[6.0.1] - 2026-09-08

• Clarifies that host-operation preparation is a just-in-time preflight and
  that the host must validate eligibility during preparation and again before
  mutation.
• Clarifies that not_found means zero currently eligible operations and
  covers both no matching resource and matching-but-ineligible resources.
• Replaces the potentially misleading not_found assistant text with the
  neutral deterministic response “No hay una operación disponible para esta
  consulta.”

[6.0.0] - 2026-09-05

• Replaces the unused JSON/base64 image attachment shape with the binary
  multipart/form-data contract using payload and image parts.
• Adds one-image JPEG, PNG, and WebP transport guidance with a 4 MiB limit.
• Documents multi-turn image-assisted operation preparation, bounded pending
  drafts, cancellation, and host-owned confirmation.

[5.2.0] - 2026-09-03

• Adds optional context_bindings metadata so capabilities can declare which
  validated reference fields and producer capabilities may fill a name-like
  input.
• Makes routing candidate selection bounded without requiring exact word
  overlap; capability descriptions, schemas, examples, and validated context
  remain the semantic sources for model selection.
• Keeps deterministic contextual recovery fail-closed for negation,
  conflicting entities, ambiguous references, incompatible provenance, and
  invalid constructed arguments.

[5.1.1] - 2026-09-03

• Adds fail-closed deterministic recovery for a bounded contextual read when
  every routing model omits a tool call and exactly one eligible capability can
  be completed from provenance-compatible validated references.
• Clarifies that explicit entities, ambiguous references or capabilities,
  incompatible scopes, routing exclusions, and invalid arguments prevent
  contextual recovery.

[5.1.0] - 2026-09-02

• Adds account-isolated capability-gap diagnostics for coverage_gap and
  agent_dead_end events.
• Adds the account-owned diagnostic_message_mode setting, with metadata as
  the default, message text as an explicit opt-in projection, and disabled as
  an opt-out of the account-facing report.
• Documents that diagnostic projection does not change the separate core
  conversation message-storage policy.

[5.0.1] - 2026-09-01

• Publishes the exact confirmation, selection, and not-found preparation
  bodies, bounds, and canonical host_interaction output schema.
• Makes capability contract tests enforce the same discriminated
  host-interaction parser used by conversational runtime.
• Documents deterministic contract-test scope, not-found behavior,
  interaction expiry, correlation retention, and opaque-reference
  non-persistence guarantees.

[5.0.0] - 2026-08-31

• Removes the 4.x action and resolution routes and response fields.
• Makes public capabilities read-only and rejects mutation and approval
  metadata during import and activation.
• Adds the host-owned host_interaction result-handling mode for bounded
  confirmation, selection, and not-found preparation results.
• Adds the operation-results callback for hosts to report terminal outcomes
  without transferring operation ownership to Forgium.

[4.1.0] - 2026-08-31

• Defines the optimistic-concurrency convention for mutations over existing
  resources: capabilities use a public resource identifier and monotonic
  expected revision, checked atomically by the host endpoint.
• Defines RESOURCE_CHANGED as a terminal, non-retryable stale-resource
  conflict. Reconfirmation creates a new action and idempotency key; the old
  action's arguments are never changed.

[4.0.0] - 2026-08-28

• Adds structured candidate resolution for capabilities that declare
  resolution_capabilities. Multiple candidates are returned as
  pending_resolution; POST /v1/resolutions/{resolution_id}/select creates
  a separate pending_action and never executes the mutation.
• Defines resolver output as { candidates: [{ label, arguments }] }. Forgium
  keeps candidate arguments server-side and exposes only opaque option IDs and
  labels to the UI.

[3.0.0] - 2026-08-28

• Adds optional resolution_capabilities to capability definitions. It lists
  read-only fallback helpers for mutations that require a canonical identifier
  when the mutation endpoint cannot resolve the user's alias directly. The
  mutation endpoint remains the preferred fast path; the field does not
  require an immediate previous call, guarantee helper invocation, or
  authorize a side effect.
• Removes requires_previous_capability. It was not a reliable workflow
  precondition and is no longer accepted in manifests or capability records.

[2.7.2] - 2026-08-25

• Documents the fail-closed routing guard for explicit capability exclusion
  clauses. A matching exclusion prevents executor I/O and returns the bounded

unresolved safe fallback; account authorization and policy remain

authoritative.

[2.7.1] - 2026-08-25

• Documents optional-but-recommended opaque user_id attribution for HTTP
  channel chat without imposing a migration deadline.
• Clarifies that Prompt Integration AI usage is attributed to its account and
  does not require a user identifier.
• Documents the internal AI usage ledger's content-free audit and versioned
  pricing behavior; no usage or cost fields are added to public responses.

[2.7.0] - 2026-08-24

• Adds POST /v1/capabilities for creating a single capability as a draft
  without wrapping it in an array. This is the recommended path for adding one
  capability; POST /v1/capabilities/import remains available for bulk creation.
• Adds CapabilityCreateRequest schema with domain and capability (single
  object) to the OpenAPI contract.

[2.6.0] - 2026-08-19

• Extends current-run capability diagnostics with sanitized unresolved and
  runtime_failed statuses, including stage-specific selection and grounded
  inference failure categories.
• Documents the complete capability-trace status and reason-code semantics,
  selection and grounded-generation criteria, and a correlation-based
  diagnostic checklist.

[2.5.0] - 2026-08-19

• Adds pattern to the bounded input_schema keyword matrix for string
  arguments that declare maxLength. Patterns use ECMAScript regular-expression
  syntax and are enforced before a capability invocation.
• Keeps pattern unsupported for output_schema; capability endpoints remain
  authoritative for validation, authorization, and business rules.

[2.4.1] - 2026-08-12

• Defines the current Public API contract, including HTTP messaging,
  capabilities, agent policies, actions, and prompt integrations.
• Establishes this compatibility and versioning policy. No endpoint or schema
  behavior changes are introduced by this documentation entry.

Upgrade process

Before using a new contract version:

1. Retrieve agent-manifest.json from the supplied Forgium base URL and
   compare contract_version with the version your integration supports.
2. Read the changelog and any linked migration guide.
3. Retrieve and validate the matching
   OpenAPI contract.
4. Run contract tests in staging before production rollout.

If a major version is not supported by your integration, keep using the

documented compatible version during its announced support window and contact

the Forgium administrator for the migration path.