chore: seed parity-manifest.json (Layer 2 of parity discipline) (#24)

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) <noreply@anthropic.com>

Author: mikemolinet

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."
+}