Contract Pull Requests

AxiomCore contract pull requests are native project records. They do not require a repository, branch, webhook, or GitHub account connection.

Each request permanently records one ordered pair of signed releases:

earlier immutable release  ->  later immutable release

The pair cannot be edited after creation. If a newer artifact is released, open another request rather than mutating the evidence under an existing review.

Open a review

1. Release at least two contract versions to the same project.
2. Open Pull requests in the project dashboard.
3. Select New pull request.
4. Choose the earlier From release and newer To release, add a title, and open the review or save it as a draft.

Project owners and maintainers can create and change review state. Every project member can participate in the discussion.

Review the evidence

The detail page presents the existing persisted semantic comparison in five purposeful views:

• All changes — a plain-language summary of each persisted change with its compatibility level.
• Domain — entities, relationships, invariants, safe projections, and endpoint bindings compiled from Domain Model v1.
• Security — signed policy and deterministic finding changes.
• Runtime configuration — authentication, field validation, streaming, cache, retry, and other runtime behavior.
• Raw change data — the technical before/after JSON, opened only when needed.

Every change can carry its own discussion thread. A project member can add a comment directly below the affected change, then reply within that thread; general review notes remain in the discussion panel.

Breaking, risky, and compatible counts are shown immediately from the saved analysis. The page loads individual changes in cursor pages of at most 50 rows, so a very large contract diff never blocks the initial review screen or creates an unbounded browser DOM. Raw values are requested only by Raw change data and are capped at 4 KiB per before/after side; use the immutable artifact or a focused local diff for a larger value.

The diff is generated by the release worker from the two stored contract artifacts. A browser never calculates a compatibility result, and opening a review never recomputes the comparison.

When a comparison has Domain Model v1 evidence, the review sidebar calls a separate compact impact endpoint. It follows the signed dependency graph to the affected endpoint routes and combines that with bounded, attributable source-release telemetry. This is intentionally not the full diff endpoint: large patches remain cursor-paged and the impact panel never causes a large browser download.

Domain removals and changed relationship/projection boundaries are marked breaking. Invariant changes are marked risky because an application must review the enforcement effect. The absence of observed consumers remains unknown usage, not proof of safety.

An optional model-field addition remains compatible, including its compiler-generated mirrored validator-index update. The comparison engine recognizes that pairing so a new optional field (and its own validation rule) is not mislabeled as a risky whole-model validation change.

Discuss and complete

Comments and replies are persisted with the request and visible to project members. The review lifecycle is explicit:

draft <-> open -> merged
           \-> closed <-> open/draft

merged records that the review has been accepted. It deliberately does not move the project’s /latest release channel: release promotion remains an explicit, auditable pipeline operation.

Evidence chain

native contract pull request
  -> two immutable signed releases
  -> persisted semantic diff
  -> release attempt
  -> runtime trace and artifact SHA-256

An empty list of observed consumers is not proof that a breaking change is safe. It means AxiomCore has no attributable runtime evidence for the bounded observation window.