Replace openapi-freshness staleness check with live registry-compatibility type-check job

[eXamadeus]

Why

The previous openapi-freshness CI job checked whether the committed OpenAPI snapshot was recent enough (based on its Generated-At header age), but this didn't actually verify that the codebase compiles correctly against the live registry's current schema. A stale snapshot check is a weak proxy for real compatibility.

Details

The openapi-freshness job and its --check/--strict modes have been replaced with a registry-compatibility job that performs a live compatibility check:

1. Fetches the deployed registry's OpenAPI spec from the network.
2. Regenerates the engine's registry types in the ephemeral CI checkout.
3. Runs bun turbo types across the full monorepo to type-check against those freshly generated types.

The job fails only when the live schema cannot be fetched, validated, or generated, or when a type check fails. Snapshot age and diffs against the committed generated files are explicitly not failure conditions — the regenerated output is discarded with the checkout, and the committed snapshot remains authoritative for deterministic offline builds.

The --check and --strict flags, the STALENESS_THRESHOLD_DAYS env var, and all associated staleness logic have been removed from sync-registry-openapi.ts. The script now has a single mode: fetch, validate, write, and codegen.

The job requires the turbo-cache context (in addition to github) since it runs bun turbo types across the monorepo. Resource class has been bumped from small to medium to accommodate the full type-check workload.

Verification

CI on this branch runs the new registry-compatibility job.

---

Note

Low Risk
Changes are limited to CI wiring, docs, and dev-only registry sync tooling; no runtime auth or production code paths.

Overview
Replaces the openapi-freshness advisory job with registry-compatibility, which fetches the deployed registry OpenAPI spec, runs bun run --cwd packages/engine codegen:registry, then bun turbo types on the ephemeral checkout. The job fails only when the live schema cannot be fetched/validated/codegen’d or when types fail—not on snapshot Generated-At age or diffs vs committed generated files (those outputs are discarded; the committed snapshot stays the source of truth for offline builds).

The new job uses turbo-cache plus github, and resource_class: medium (was small). CircleCI docs in .circleci/AGENTS.md and packages/engine/AGENTS.md describe the new behavior.

sync-registry-openapi.ts is sync-only: --check / --strict, STALENESS_THRESHOLD_DAYS, and offline freshness logic are removed; entry is always fetch → validate → write snapshot → openapi-typescript.

^{Reviewed by Cursor Bugbot for commit 4b22182. Bugbot is set up for automated code reviews on this repo. Configure here.}

Summary by CodeRabbit

• CI Improvements

  • Replaced OpenAPI snapshot freshness checks with live registry compatibility checks.
  • CI now regenerates registry types from the live OpenAPI specification and runs repository-wide type checks.
  • Checks fail only when the live schema cannot be evaluated or type validation fails—not due to snapshot age or generated file differences.

• Documentation

  • Updated CI documentation to explain the new compatibility workflow and its behavior.

[changeset-bot]

⚠️ No Changeset found

Latest commit: 4b22182

Merging this PR will not cause a version bump for any packages. If these changes should not result in a new version, you're good to go. If these changes should result in a version bump, you need to add a changeset.

This PR includes no changesets

When changesets are added to this PR, you'll see the packages that this PR includes changesets for and the associated semver types

Click here to learn what changesets are, and how to add one.

Click here if you're a maintainer who wants to add a changeset to this PR

[eXamadeus]

• Replace openapi-freshness staleness check with live registry-compatibility type-check job #434 👈 (View in Graphite)
• Refresh OpenAPI registry snapshot #433
• main

This stack of pull requests is managed by Graphite. Learn more about stacking.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro Plus

Run ID: c65821b2-f8c0-45ec-9487-1f867087ce10

📥 Commits

Reviewing files that changed from the base of the PR and between 0a5729e and 4b22182.

📒 Files selected for processing (7)

• .circleci/AGENTS.md
• .circleci/development.yml
• .circleci/development/jobs/openapi-freshness.yml
• .circleci/development/jobs/registry-compatibility.yml
• .circleci/development/workflows/ci.yml
• packages/engine/AGENTS.md
• packages/engine/scripts/sync-registry-openapi.ts

💤 Files with no reviewable changes (1)

• .circleci/development/jobs/openapi-freshness.yml

---

📝 Walkthrough

Walkthrough

The OpenAPI freshness job is replaced by a registry-compatibility CircleCI job. It fetches and validates the live registry OpenAPI specification, regenerates registry TypeScript types, and runs bun turbo types. The sync script no longer supports freshness-check mode. CircleCI wiring and documentation now describe the new job, contexts, generated-output handling, and failure conditions.

Sequence Diagram(s)

sequenceDiagram
  participant CircleCI
  participant RegistrySync as sync-registry-openapi
  participant LiveRegistry as Live OpenAPI registry
  participant TypeCheck as bun turbo types
  CircleCI->>RegistrySync: run codegen:registry
  RegistrySync->>LiveRegistry: fetch OpenAPI YAML
  LiveRegistry-->>RegistrySync: return OpenAPI document
  RegistrySync->>RegistrySync: validate and generate registry types
  CircleCI->>TypeCheck: run monorepo type check
  TypeCheck->>TypeCheck: check regenerated registry types

Loading

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 66.67% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title clearly summarizes the main CI change from the stale OpenAPI check to the live registry compatibility job.
Description check	✅ Passed	The description follows the template with Why, Details, and Verification, and it explains the change and validation clearly.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch julian/07-20-replace_openapi-freshness_staleness_check_with_live_registry-compatibility_type-check_job

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[greptile-apps]

Greptile Summary

Replaces the advisory openapi-freshness CI job (which checked snapshot age offline) with a registry-compatibility job that fetches the live registry schema, regenerates types in the ephemeral checkout, and runs bun turbo types across the full monorepo. The committed snapshot remains unchanged and authoritative for offline builds.

• CI job replacement: openapi-freshness (small, offline staleness check) → registry-compatibility (medium, live fetch + full type-check); turbo-cache context added to the workflow.
• Script simplification: --check, --strict, and STALENESS_THRESHOLD_DAYS removed from sync-registry-openapi.ts; main() entry point replaced by a direct runSync() call.
• Documentation: .circleci/AGENTS.md and packages/engine/AGENTS.md updated to describe the new job semantics, network dependency, and non-failure conditions.

Confidence Score: 5/5

Safe to merge. Changes are limited to CI configuration and dev tooling — no runtime code or release artifacts are affected.

The job replacement is self-contained in CI: setup-mise already includes checkout and dependency installation, the two-step codegen → type-check sequence is straightforward, contexts are correctly propagated to both the packed development.yml and the component YAML files, and the script simplification removes dead code without touching any live paths. The introduced network dependency on the live registry is intentional and well-documented.

No files require special attention.

_{Reviews (2): Last reviewed commit: "Replace `openapi-freshness` staleness ch..." | Re-trigger Greptile}

[eXamadeus]

Merge activity

• Jul 20, 5:05 PM UTC: A user started a stack merge that includes this pull request via Graphite.
• Jul 20, 5:07 PM UTC: Graphite rebased this pull request as part of a merge.
• Jul 20, 5:08 PM UTC: @eXamadeus merged this pull request with Graphite.