Registry Synchronization

The registry generator collects a provider model API catalog and its published pricing page into one registry artifact per provider.

The artifact records SHA-256 source evidence for every collection input.

Collection

The provider’s model list is the catalog. A listed model the pricing page does not price on its default tier ships in the artifact disabled; provider model lists routinely carry rows a pricing table cannot express (audio, realtime, video, dated snapshots), so this is the ordinary case rather than a collection failure. Whether that disablement reaches the live registry is the import’s decision, below.

Pricing-page names resolve to an API model identifier by exact match.

An undated page name can resolve to one dated API snapshot only when there is exactly one candidate whose suffix is an eight-digit YYYYMMDD date. A shorter numeric suffix is a version (claude-sonnet-4 is not claude-sonnet-4-6), and its price is not inherited.

An ambiguous dated-snapshot match leaves the page row unmatched and reported rather than selecting a price by guesswork.

An OpenAI tier that publishes only a (<272K context length) row for a model, with no >=272K partner, prices the model’s whole context range on that tier.

The provider rate pages are authoritative. Third-party datasets are not imported as prices. They may be used by an operator to review a deferred plan, but a dataset disagreement does not authorize a registry mutation.

Import policies

nexus registry import <artifact> plans a full-replace diff of the artifact against the provider’s live registry state. The plan is applied under one of two policies.

The full policy (the default) applies the whole plan once a reviewer has read it. Retirements and approval-required findings gate the apply; --yes states the reviewer has read it.

The unattended policy (--unattended) splits the plan per model and applies only the part that needs no reviewer:

Applied unattended	Deferred for review
New models, endpoints, aliases, and rate cards	Endpoint retirement (model absent from the artifact)
Repricing of an existing card within a fivefold bound per rate	Repricing that moves any rate more than fivefold, or between zero and non-zero
Endpoint metadata and capability additions	Disablement, capability reduction, context reduction, tier change (destructive_endpoint_change)
Retiring a superseded card for a model the artifact still prices	Re-enabling a quarantined endpoint (quarantine_recovery)
Generator, parser, and contract version transitions	Alias retirement
	Any change to a model whose pricing an operator pinned (pricing_pinned); the apply never writes a pinned model, and the plan says so instead of counting it as applied
	Any hard reject scoped to a model (partial_activation_overlap, shared_model_capability_change, …)

A deferred model is left exactly as the registry holds it: no row of it is written, including its retirement. Importing the same artifact again under the full policy therefore plans precisely the deferred remainder, and that is the review plan.

A hard reject not scoped to a model still blocks the whole import under either policy.

The CLI reports the policy it ran under (apply_policy), the whole plan (changes, findings), and the deferred part (deferred.changes, deferred.findings, deferred.models, deferred.aliases). --format json emits all of it. The policy is a property of the CLI invocation, not of the stored change set: the database schema is unchanged, a stored change set is always the whole plan, and the deferred part is re-derived from it and the policy at approve and apply time. The control plane and gateway need no update for this; a registry written by an unattended apply is an ordinary registry.

OpenAI renamed priority processing to fast mode on 2026-07-30 and accepts either service_tier value. Because the gateway prices a request by the tier name it sent, the collector states every OpenAI fast rate under priority as well (and vice versa) unless the page prices both, so requests on either name keep pricing.

Nightly host command

The nightly host command is scripts/sync-model-registry.sh in the source repository. Per provider it collects, validates offline, plans with --unattended --dry-run, applies with --unattended --yes, and then — if anything was deferred — plans the same artifact again under the full policy and writes that as <provider>.review.plan.json.

Exit status is 0 when nothing was deferred, 10 when something waits on a reviewer (or a guard held the run), and 1 on failure. A systemd unit that runs the script should list 10 as a success status (SuccessExitStatus=10) so a pending review is not logged as a failed run.

--plan-only collects and plans without applying. --apply-deferred (formerly --allow-retire) applies the whole plan, deferred part included; use it after reviewing.

--max-changes is a runaway guard on the applied part, not a review gate.

Review

Review registry-artifacts/<run-id>/REVIEW.txt. It names, per provider, the deferred models and findings, the review plan, and the one command that applies it:

cd /srv/nexus && ./cli.sh registry import /registry-artifacts/<run-id>/<provider>.json

The CLI reprints the plan and waits for confirmation. Collect again instead and the registry would be priced from a later catalog than the one reviewed.

Observability

Set NEXUS_SYNC_METRICS_DIR to a node-exporter textfile collector directory to publish nexus_registry_sync_last_run_success, nexus_registry_sync_last_run_held, nexus_registry_sync_last_run_applied_changes, nexus_registry_sync_last_run_deferred_changes, and nexus_registry_sync_last_run_unixtime.

Set NEXUS_SYNC_ALERT_WEBHOOK to notify an operator when a run deferred something or failed. The webhook receives the run’s summary.json: status, per-provider outcome and counts, and on-host paths to the plan and review plan. It carries no credentials or artifact content.