| name | endor-model-sync-drift |
| description | Use when triaging OpenAPI / model-sync upstream drift—CI or pre-push
verify-upstream-only failures, or published endorctl newer than committed
provenance. Covers regenerating registry_contract, stubs, and reference docs;
reviewing generated diffs; optional local endorctl upgrades. Not for runtime SDK
API errors (endor-troubleshoot-sdk). |
Model-sync upstream drift
When OpenAPI SHA-256 in live upstream differs from src/endorlabs/generated/registry_contract.py provenance, CI and pre-push fail. Pre-commit runs local regen + ship git diff (no upstream fetch) before linters when generated paths change. A newer published endorctl alone is a warning only until you re-run model sync.
Quick diagnose
uv run python devtools/codegen/model_sync.py --verify-upstream-only
Exit 0 = committed artifacts match upstream. Non-zero = regen required (message includes committed vs upstream digests).
Optional: compare published CLI version (no auth):
uv run python .github/scripts/check_endorctl_version.py
Regenerate (canonical)
From repo root (public spec download):
uv run python devtools/codegen/model_sync.py --fetch-spec --generate-stubs --generate-reference-docs
Spec already in .endorlabs-context/platform/openapi/openapiv2.swagger.json:
uv run python devtools/codegen/model_sync.py --generate-stubs --generate-reference-docs
Refresh only if verify failed:
uv run python devtools/codegen/model_sync.py --verify-and-sync-if-stale
Provenance watermark (endorctl_version, spec_sha256) comes from GET /meta/version and the downloaded OpenAPI file during generation—not from a stale local endorctl binary.
Review checklist before push
| Area | What to scan |
|---|
src/endorlabs/generated/ | registry_contract.py, models/, create_convenience.py, provenance headers |
src/endorlabs/client_surface.pyi | Stub drift after registry/facade changes |
docs/generated-reference/ | Per-resource pages if generator touched resources |
| Overlays | src/endorlabs/registry_overlay.py, devtools/codegen/model_sync_profiles/ only if API introduced new resources or scope fixes |
Run locally before push:
uv run ruff check .
uv run pyright --project pyproject.toml
uv run pytest
Pre-commit runs verify_ship_artifacts.py --skip-upstream before ruff/pyright on
model-sync changes. Pre-push runs verify_ship_artifacts.py --fetch-spec (upstream SHA +
agent-knowledge verify) and contract validation.
When this is not enough
Local endorctl upgrade (optional, for parity with UI/endorctl)
SDK model-sync does not require a matching local endorctl for regen. To upgrade the CLI for manual endorctl api checks: npm update -g endorctl then endorctl --version, or follow Endor CLI install (stop processes locking endorctl.exe on Windows before replacing the binary).
References
