Repository navigation
ci(core-api): freeze v1 broker OpenAPI baseline + oasdiff gate (Gate C Phase 1) - #620
1 commit merged into
Conversation
|
Claude Code Review — skipped: PR author 'Eldad-Caura' is not a public member of the 'caura-ai' org |
SummaryThis PR adds an API-versioning gate (Gate C / Phase 1) that enforces a frozen v1 broker OpenAPI contract via a freshness check and a breaking-change check using oasdiff. The script logic for transitive ref traversal and security scheme extraction is correct. Two real issues warrant attention before merge. Medium IssuesDocker image pinned by mutable tagSeverity: Medium 🤖 Claude Code PromptLow IssuesDenylist for top-level OpenAPI keys silently pollutes the frozen contractSeverity: Low 🤖 Claude Code Prompt🟠 High Fix All(no high issues) 🟡 Medium/Low Fix AllReviewed by |
07a0b9f to
eb83835
Compare
|
Claude Code Review — skipped: PR author 'Eldad-Caura' is not a public member of the 'caura-ai' org |
SummaryThis PR adds a CI gate for broker↔cloud API versioning: a generation script, a committed baseline ( Critical/High Issues(none) Medium/Low Issues
|
eb83835 to
331cc3e
Compare
|
Claude Code Review — skipped: PR author 'Eldad-Caura' is not a public member of the 'caura-ai' org |
331cc3e to
45d9ab0
Compare
|
Claude Code Review — skipped: PR author 'Eldad-Caura' is not a public member of the 'caura-ai' org |
|
Fixed the Low finding ( On the Medium (baseline advertises server-reserved Suggested order: merge #621 first (it's rebased onto main, clean, mergeable), then I'll rebase this PR and regenerate |
45d9ab0 to
b9e3490
Compare
|
Claude Code Review — skipped: PR author 'Eldad-Caura' is not a public member of the 'caura-ai' org |
b9e3490 to
08609e5
Compare
|
Claude Code Review — skipped: PR author 'Eldad-Caura' is not a public member of the 'caura-ai' org |
08609e5 to
3606812
Compare
|
Claude Code Review — skipped: PR author 'Eldad-Caura' is not a public member of the 'caura-ai' org |
|
@claude rebased onto main after #621 merged and regenerated the baseline — |
|
The script doesn't exist on disk yet (PR not merged), so I'm working from the diff alone. I have enough to complete the review. SummaryThis PR adds a CI gate (freshness + breaking-change check via Medium/Low IssuesBroker spec inherits unused global security schemes from the full specSeverity: Medium # Current
scheme_names = _security_scheme_names(paths, full.get("security"))The broker output spec never emits a top-level 🤖 Claude Code Prompt🟡 Medium/LowReviewed by |
|
@claude fixed: |
3606812 to
927228a
Compare
|
Claude Code Review — skipped: PR author 'Eldad-Caura' is not a public member of the 'caura-ai' org |
|
The script is new in this PR so I'll review from the diff alone. SummaryAdds a two-step CI gate that freezes the four broker-facing gateway endpoints as Medium/Low IssuesTop-level key passthrough uses a denylist instead of an allowlistSeverity: Low 🤖 Claude Code Prompt🟢 Fix All (Low)Reviewed by |
…ange gate Phase 1 of the broker<->cloud API-versioning RFC (freeze + enforce v1): commit the immutable v1 OpenAPI contract for core-api's four broker-facing gateway endpoints (POST /api/v1/memories/bulk, POST /api/v1/search, GET /api/v1/health, GET /api/v1/version) that memclawd calls against cloud, and gate PRs on it. - core-api/scripts/gen_broker_openapi.py: imports core_api.app offline, filters paths to the 4 broker endpoints (missing path = hard error), keeps only the transitively-reachable schemas + referenced security schemes, normalizes info to a frozen contract identity (version "v1", decoupled from the rolling package semver so releases don't churn it), and emits deterministic JSON. --check fails if the committed baseline is stale vs the code. - core-api/openapi.broker.json: the frozen v1 baseline (4 paths, 14 schemas). - ci.yml: a stale-baseline guard + `oasdiff breaking --fail-on ERR` vs main's baseline (pinned tufin/oasdiff:v1.26.0). --fail-on ERR is required — plain `oasdiff breaking` exits 0 even on breaks. First-merge bootstrap skips the diff when main has no baseline yet. - core-api/scripts/README.md documents regeneration + the contract-bump rule. A breaking change to a shipped v1 broker endpoint now fails CI; per the RFC it must ship a new /vN version rather than edit the frozen baseline. Gate C / Phase 1 (Deliverables A+B). Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com> Signed-off-by: eldad-caura <eldad@caura.ai>
927228a to
38c0fc3
Compare
|
Claude Code Review — skipped: PR author 'Eldad-Caura' is not a public member of the 'caura-ai' org |
|
@claude fixed the Low: |
|
@erni-a please approve |
…625) ## Summary Executes all remaining OSS-side work from the 2026-07-26 product-coordination audit (enterprise-side fixes landed in the enterprise repo's #914). One commit per task, all DCO-signed. - **Canonical SKILL.md** (`static/skills/memclaw/SKILL.md`): documents the Interviewer (§3 — reflective server-side synthesis; realtime writes stay mandatory) and the Skill Factory (§8 — `staged` is governance not an error, `forge/`/`agent/` `doc_id` provenance, push delivery). Five new content-invariant pins in `tests/test_direct_mcp_skill.py`. Once merged, the enterprise nightly `sync-tools-json.yml` carries these sections to `memclaw.net/docs/agents.md` via its pin-bump PR — no manual step. - **core-operations docstring**: `app.py` no longer claims "this scaffold registers nothing" — it names the nine registered cron jobs (six daily lifecycle ticks, daily/weekly agent digests, hourly interviewer-schedule), each verified against its `scheduler.register` call. - **README**: new **MemClaw Broker** section (identity headers, `broker:<install>` namespace, frozen v1 wire contract + oasdiff gate from #620); agent-digests bullet (`agent_digest.enabled`, `GET /api/v1/reports*`); a deployment-topology table stating exactly what `docker compose up` starts (db, redis, core-storage-api, core-api; `tei` only with `--profile embed-local`) vs what is managed-only (core-worker, platform tier, Pub/Sub); clarifies the `core-worker` backfill variant isn't in the stock compose stack. - **Plugin SKILL.md variant**: ports both notes, with the Interviewer explicitly distinguished from the plugin's `MEMCLAW_AUTO_WRITE_TURNS` auto-write layer (both are floors, not substitutes); adds a mirroring content-invariant test to `plugin/src/tool-definitions.test.ts`. - **Component registry** (P2): `docs/component-registry.yaml` (4 services, 9 cron ticks, 5 event-topic families, Forge external-scheduler requirement) + `tests/test_component_registry.py`, an AST-based two-way drift gate between `scheduler.register(...)` calls and the registry — F5-class drift now fails a test. ## Test plan - `python3 -m pytest tests/test_direct_mcp_skill.py -q` → 10 passed - `python3 -m pytest tests/test_component_registry.py -q` → 3 passed - `cd plugin && npm test` → 378 passed, 0 failed - Full root suite: 3964 passed; 5 failures are local-env only (missing `google-cloud-pubsub`, stray `.claude/worktrees` copies) — none touch this diff - `ruff check` / `ruff format --check` clean on the touched Python files; no `core-api`/`core-storage-api` src changes, so CI ruff/mypy surfaces are untouched 🤖 Generated with [Claude Code](https://claude.com/claude-code) --------- Signed-off-by: Ran Taig <ran@caura.ai> Co-authored-by: Claude Fable 5 <noreply@anthropic.com>
What
Freeze the v1 broker↔cloud OpenAPI contract for core-api and enforce it on every PR with an
oasdiffbreaking-change gate. Phase 1 (Deliverables A+B) of the broker API-versioning RFC (docs/design/broker-cloud-api-versioning.md, enterprise repo).Why
v1 was a label, not an enforced contract — breaking changes shipped inside
/v1and silently broke installed brokers (the Phase-0 incident). This commits the broker-facing contract as an artifact and fails CI on any breaking change to it, so a break must ship a new/vN.Contents
core-api/scripts/gen_broker_openapi.py— importscore_api.appoffline, filterspathsto the 4 broker endpoints (POST /api/v1/memories/bulk,POST /api/v1/search,GET /api/v1/health,GET /api/v1/version; a missing path is a hard error), keeps only the transitively-reachable schemas + referenced security schemes, normalizesinfoto a frozen contract version (v1) decoupled from the rolling package semver (so releases don't churn the baseline), and emits deterministic JSON.--checkfails if the committed baseline is stale.core-api/openapi.broker.json— the frozen v1 baseline (4 paths, 14 schemas,APIKeyHeader).ci.yml— stale-baseline guard +oasdiff breaking --fail-on ERRvsmain's baseline (pinnedtufin/oasdiff:v1.26.0;--fail-on ERRrequired — plainoasdiff breakingexits 0 even on breaks). First-merge bootstrap skips the diff when main has no baseline yet.core-api/scripts/README.md— regeneration + contract-bump rules.Validation
--checkclean and deterministic (byte-identical across runs); proof the gate bites: a synthetic required field onBulkMemoryCreate→oasdiffreportsnew-required-request-property, exit 1 — then reverted.ruffclean on the script.Regenerate after an intentional broker contract change:
python core-api/scripts/gen_broker_openapi.py.Gate C / Phase 1. Companion to the enterprise auth/audit gate (#889) and the Phase-0 fixes.