From b3857c052ecba5fc45d8a68834fd9f82e55a646a Mon Sep 17 00:00:00 2001 From: mikemolinet Date: Mon, 4 May 2026 09:37:48 -0700 Subject: [PATCH] chore: seed parity-manifest.json (Layer 2 of parity discipline) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit First-pass audit of cueapi-sdk coverage against the hosted CueAPI API. Catalogues which endpoints + model fields the SDK covers, and which have drifted out of sync. The manifest is the audit checklist. New PRs in the private monorepo that touch covered surfaces flag this manifest in their Parity Impact section (see private repo's `.github/pull_request_template.md`). Monthly full sweep updates `last_full_audit`. Notable drift surfaced: - 12 endpoints missing (cue.fire, execution.replay, worker registration + claim flow, usage, webhook-secret retrieval, plus the entire messaging primitive surface from Phase 12.1.5 — Identity / Messages / Inbox). - Cue model missing 8 fields shipped in private over the last few months: delivery, alerts, catch_up, verification, on_success_fire, require_payload_override, required_payload_keys, stats. CueDetailResponse shape (executions list + pagination) also missing. - Execution has no dedicated model class — SDK returns dicts. Should promote to a typed class along with the outcome / evidence / heartbeat / chain attribution fields. - Worker, Agent, Message classes missing entirely. Two PRs from 2026-05-03 (private repo #589 expose payload on GET executions; #590 require_payload_override enforcement) have explicit Backlog rows pending port to this SDK; both are priority=now once their source PRs merge. Co-Authored-By: Claude Opus 4.7 (1M context) --- parity-manifest.json | 94 ++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 94 insertions(+) create mode 100644 parity-manifest.json diff --git a/parity-manifest.json b/parity-manifest.json new file mode 100644 index 0000000..67751cc --- /dev/null +++ b/parity-manifest.json @@ -0,0 +1,94 @@ +{ + "manifest_version": 1, + "description": "Parity tracking for cueapi-sdk against the hosted CueAPI API. Enumerates which API surfaces this SDK covers and which it doesn't, so drift becomes visible at audit time. Per the 3-layer parity discipline (PR template + this manifest + Backlog rows for each port).", + "private_source_repo": "https://github.com/cueapi/cueapi", + "private_source_paths": [ + "app/routers/", + "app/schemas/" + ], + "last_full_audit": "2026-05-04", + "sdk_version_at_audit": "0.1.3", + "audit_methodology": "Walk every endpoint in private cueapi/app/routers/ and check coverage in cueapi/resources/. For each covered endpoint, walk the corresponding schemas/*.py to verify field-level coverage in cueapi/models/. Drift goes in `missing_endpoints` or `missing_fields` keyed by endpoint.", + "audit_cadence": "Monthly full sweep. Per-PR diffs handled via the .github/pull_request_template.md `Parity Impact` section in the private repo.", + + "endpoints_covered": { + "POST /v1/auth/register": {"sdk": "client.register (utility, not on a resource)"}, + "POST /v1/cues": {"sdk": "client.cues.create"}, + "GET /v1/cues": {"sdk": "client.cues.list"}, + "GET /v1/cues/{id}": {"sdk": "client.cues.get"}, + "PATCH /v1/cues/{id}": {"sdk": "client.cues.update"}, + "DELETE /v1/cues/{id}": {"sdk": "client.cues.delete"}, + "POST /v1/cues/{id} (pause)": {"sdk": "client.cues.pause"}, + "POST /v1/cues/{id} (resume)": {"sdk": "client.cues.resume"}, + "POST /v1/executions/{id}/outcome": {"sdk": "client.executions.report_outcome"}, + "GET /v1/executions": {"sdk": "client.executions.list"}, + "GET /v1/executions/{id}": {"sdk": "client.executions.get"}, + "POST /v1/executions/{id}/heartbeat": {"sdk": "client.executions.heartbeat"}, + "POST /v1/executions/{id}/verification-pending": {"sdk": "client.executions.mark_verification_pending"}, + "POST /v1/executions/{id}/verify": {"sdk": "client.executions.mark_verified"} + }, + + "endpoints_missing": { + "POST /v1/cues/{id}/fire": { + "blocker": "Real ergonomic gap. Team-comm convention requires payload_override per fire; SDK users currently fall back to raw httpx.", + "tracking": "Backlog row: priority=now after the audit ships. Should pair with the PR #590 require_payload_override port since cue-fire is the primary surface for that enforcement." + }, + "POST /v1/executions/{id}/replay": {"blocker": "Used for retry-from-failure flows; not in any current SDK release."}, + "GET /v1/executions/claimable": {"blocker": "Worker-pull endpoint; some SDK users want to write Python workers directly without using cueapi-worker."}, + "POST /v1/executions/{id}/claim": {"blocker": "Same as above — worker-pull surface missing."}, + "POST /v1/worker/heartbeat": {"blocker": "Worker registration endpoint; same justification."}, + "GET /v1/workers": {"blocker": "List workers + heartbeat status; useful for fleet visibility."}, + "GET /v1/usage": {"blocker": "Plan, cue count, execution usage, rate limit info. Currently SDK users hit /v1/auth/me only."}, + "POST /v1/billing/checkout": {"blocker": "Hosted-only — wrap if/when hosted users need programmatic checkout."}, + "POST /v1/billing/portal": {"blocker": "Hosted-only."}, + "POST /v1/auth/key/regenerate": {"blocker": "Risky destructive op; intentionally not surfaced. Re-evaluate."}, + "GET /v1/auth/webhook-secret": {"blocker": "Webhook-secret retrieval — SDK users running their own webhook servers want this."}, + "POST /v1/auth/webhook-secret/regenerate": {"blocker": "Destructive; re-evaluate."}, + "Messaging primitive (all of /v1/agents, /v1/messages, /v1/agents/{id}/inbox)": { + "blocker": "Phase 12.1.5 messaging primitive is on prod but not yet exposed in the SDK. Significant new surface — agent identity, send_message, inbox poll, idempotency-keyed sends, reply threading.", + "tracking": "Major SDK extension. Should land before push delivery (v1.5) goes wide." + } + }, + + "model_drift": { + "Cue": { + "sdk_class": "cueapi.models.Cue", + "covered_fields": [ + "id", "name", "description", "status", "transport", "schedule", + "callback", "payload", "retry", "next_run", "last_run", "run_count", + "fired_count", "on_failure", "warning", "created_at", "updated_at" + ], + "missing_fields": [ + "delivery", "alerts", "catch_up", "verification", "on_success_fire", + "require_payload_override", "required_payload_keys", "stats" + ], + "missing_response_shape": "CueDetailResponse (cue + executions[] + execution_total/limit/offset)" + }, + "Execution": { + "sdk_class": "no dedicated model; SDK returns dicts from executions.get/list", + "needs_dedicated_class": true, + "missing_fields": [ + "payload (PR #589, just shipped)", + "outcome", + "outcome_state", + "triggered_by", + "evidence_external_id, evidence_result_url, evidence_result_type, evidence_summary, evidence_validation_state, evidence_assertions", + "claimed_by_worker, claimed_at, last_heartbeat_at", + "chain_parent_id, chain_depth" + ] + }, + "Worker": { + "sdk_class": "missing entirely", + "missing_fields": ["worker_id", "user_id", "handlers", "last_heartbeat", "heartbeat_status (active/stale/dead)"] + }, + "Agent (messaging)": {"sdk_class": "missing entirely (Phase 12.1.5)"}, + "Message (messaging)": {"sdk_class": "missing entirely (Phase 12.1.5)"} + }, + + "ported_pr_history": [ + "PR #589 (expose payload on GET /v1/executions): NOT YET PORTED — Backlog row 'Parity port: PR #589 → cueapi-python SDK' priority=now.", + "PR #590 (require_payload_override + required_payload_keys + cue.fire enforcement): NOT YET PORTED — Backlog row 'Parity port: PR #590 → cueapi-python SDK' priority=now." + ], + + "notes": "First seeded 2026-05-04 as Layer 2 of parity discipline (PR template + this manifest + Backlog rows). Schema may evolve based on what auditors actually need. The `endpoints_missing` and `model_drift` sections are deliberately verbose — they are the audit checklist for catching up the SDK to the hosted API." +}