Compare a baseline and reapprove a source change

View as Markdown

Use this procedure when a source changes product version, protocol profile, request shape, response shape, or adapter logic and the deployment needs a reviewable comparison with its approved product baseline.

Prerequisites

Keep the current authored project unchanged as the review baseline.
Obtain the verified signed Relay baseline and its product trust anchor.
Obtain the separate Notary baseline and anchor when the project includes Notary.
Define the source-owner evidence required to move a version label from unverified to tested.
Use synthetic fixtures until separate authority permits a live compatibility check.

Ownership and trust boundary

The integration declares product-neutral inputs, one http, script, or snapshot capability, source authority, outputs, and limits. source.product and source.versions record interoperability evidence. They do not select a runtime executor, enable a protocol helper, or grant source authority.

The environment binds the source origin, credential reference, private trust, rate, concurrency, and timeout without widening the integration. Registry Relay owns source access and adaptation. Registry Notary owns service policy, claim evaluation, disclosure, and issuance.

Establish the verified baseline

Run the unchanged project against the signed baseline before editing:

registryctl check \
  --project-dir <project> \
  --environment <environment> \
  --against <relay-baseline-bundle> \
  --anchor <relay-trust-anchor> \
  --explain \
  --format json

For a combined project, use product-specific baseline pairs with promote. Do not substitute one product bundle for a project-root baseline.

registryctl promote \
  --project-dir <project> \
  --environment <environment> \
  --relay-against <relay-baseline-bundle> \
  --relay-anchor <relay-trust-anchor> \
  --notary-against <notary-baseline-bundle> \
  --notary-anchor <notary-trust-anchor> \
  --format json

The report is an offline promotion decision. The command does not sign, activate, deploy, contact a source, or mutate either environment.

Make the narrow source change

Update the source product or version label only when the transport contract is unchanged. Keep the new version unverified until the required evidence exists.
When transport behavior changes, edit only the required method, path, query, headers, body, response mapping, Script branch, or protocol profile.
Keep the origin, credentials, private CA, and deployment controls in the environment.
Do not add a wider wildcard, another origin, another credential, another HTTP method, more outputs, a larger call or byte budget, or a longer deadline unless the review explicitly approves that authority.
Update every affected fixture interaction and expected outcome. Preserve match, no-match, ambiguity, subject mismatch, source rejection, and minimized-output evidence that applies to the integration.

The project configuration reference identifies field ownership, sensitivity, environment behavior, validation, and migration intent. Use the bounded Script guide when the change requires reviewed orchestration.

Compare and reapprove

Run the complete offline gates:

PROJECT_DIR=registry-project
ENVIRONMENT=staging
RELAY_BASELINE=operator-inputs/reviewed-relay-bundle
RELAY_TRUST_ANCHOR=operator-inputs/relay-trust-anchor.json
registryctl test --project-dir "$PROJECT_DIR"
registryctl check \
  --project-dir "$PROJECT_DIR" \
  --environment "$ENVIRONMENT" \
  --against "$RELAY_BASELINE" \
  --anchor "$RELAY_TRUST_ANCHOR" \
  --explain \
  --format json
registryctl preflight \
  --project-dir "$PROJECT_DIR" \
  --environment "$ENVIRONMENT" \
  --format json

Review the semantic change dimensions, effective source authority, canonical requests, output and claim changes, disclosure changes, service policy, operator-security changes, and generated artifact manifest. For a combined project, run the four-argument product-pair promote comparison again.

Build against the same verified baseline:

registryctl build \
  --project-dir <project> \
  --environment <environment> \
  --against <relay-baseline-bundle> \
  --anchor <relay-trust-anchor> \
  --format json

The build produces unsigned review material. Sign and verify each generated product input independently after the authorized reviewer approves the report. Stage Relay first and Notary second, then admit traffic only after both product checks pass.

Expected evidence

Retain:

The baseline verification result and exact product identities.
Fixture traces for each changed request, response, branch, output, and claim.
The redacted semantic comparison and promotion report.
The preflight report showing required bindings without secret values.
Separate verified Relay and Notary bundle reports when both products changed.
Source-owner compatibility evidence with scope, version, date, and limitations.

What this proves

Fixture tests prove deterministic behavior against synthetic observations. Baseline comparison proves the classified authored and generated delta against verified signed approval state. Preflight proves offline binding availability and non-widening. Product verification proves each signed bundle boundary.

These gates do not prove live source interoperability, source-owner acceptance, legal approval, production readiness, or atomic activation. A version label alone proves none of those properties.

Roll back or recover

Before signing, discard the candidate and restore the unchanged authored project. Before traffic admission, restore the prior product recovery set. After a higher product sequence is accepted, create a reviewed higher-sequence recovery bundle instead of deleting anti-rollback state.

If only Relay changes, keep Notary traffic blocked until Notary validates the exact new Relay consultation contract. If the source contract cannot remain narrow, split the change into a separately reviewed integration or a separate registry trust domain.

Escalate

Escalate to the source owner and security reviewer when the change adds an origin, write-like operation, wildcard authority, output, credential, private trust root, call, byte, or deadline budget. Escalate to the product owners when the change alters both Relay and Notary semantics or requires a source capability that current closed contracts do not support.