parity-manifest.json

{
  "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-12",
  "sdk_version_at_audit": "0.2.x (head; pre-0.3.0 cut — heavy PR-1b + body-verify + inline_body activity 2026-05-09 → 2026-05-12)",
  "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/cues/{id}/fire": {"sdk": "client.cues.fire (PR #23; send_at + exit_criteria + idempotency_key shipped in #33 on 2026-05-09)"},
    "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"},
    "POST /v1/executions/{id}/replay": {"sdk": "client.executions.replay (PR #25)"},
    "GET /v1/executions/claimable": {"sdk": "client.executions.list_claimable (PR #23)"},
    "POST /v1/executions/{id}/claim": {"sdk": "client.executions.claim (PR #23)"},
    "POST /v1/executions/claim": {"sdk": "client.executions.claim_next (PR #23)"},
    "GET /v1/workers": {"sdk": "client.workers.list (PR #26)"},
    "DELETE /v1/workers/{id}": {"sdk": "client.workers.delete (PR #26)"},
    "GET /v1/usage": {"sdk": "client.usage.get (PR #26)"},
    "POST /v1/agents": {"sdk": "client.agents.create (PR #27)"},
    "GET /v1/agents": {"sdk": "client.agents.list (PR #27)"},
    "GET /v1/agents/{ref}": {"sdk": "client.agents.get (PR #27)"},
    "PATCH /v1/agents/{ref}": {"sdk": "client.agents.update (PR #27)"},
    "DELETE /v1/agents/{ref}": {"sdk": "client.agents.delete (PR #27)"},
    "GET /v1/agents/{ref}/webhook-secret": {"sdk": "client.agents.get_webhook_secret (PR #27)"},
    "GET /v1/agents/{ref}/inbox": {"sdk": "client.agents.inbox (PR #27)"},
    "GET /v1/agents/{ref}/sent": {"sdk": "client.agents.sent (PR #27)"},
    "GET /v1/agents/roster": {"sdk": "client.agents.roster (PR #35; cueapi #630 parity, shipped 2026-05-09)"},
    "GET /v1/agents/{ref}/presence": {"sdk": "client.agents.presence (PR #35; cueapi #662 parity, shipped 2026-05-09)"},
    "POST /v1/messages": {"sdk": "client.messages.send (PR #28; send_at shipped in #34 on 2026-05-09; auto_verify body-verify Phase 2 shipped in #39 + #40 on 2026-05-11 — defense against caller-side shell expansion, cueapi/cueapi#795 + #798 parity)"},
    "GET /v1/messages/{id}": {"sdk": "client.messages.get (PR #28)"},
    "POST /v1/messages/{id}/read": {"sdk": "client.messages.mark_read (PR #28)"},
    "POST /v1/messages/{id}/ack": {"sdk": "client.messages.ack (PR #28)"},
    "POST /v1/agents/{ref}/subscriptions": {"sdk": "client.agents.subscriptions_create (PR #38, PR-1b event-emit primitive, shipped 2026-05-11; inline_body kwarg shipped in PR #42 on 2026-05-12, cueapi/cueapi#791 / Item 1 parity)"},
    "GET /v1/agents/{ref}/subscriptions": {"sdk": "client.agents.subscriptions_list (PR #38, shipped 2026-05-11)"},
    "DELETE /v1/agents/{ref}/subscriptions/{sub_id}": {"sdk": "client.agents.subscriptions_delete (PR #38, shipped 2026-05-11)"},
    "GET /v1/agents/{ref}/events": {"sdk": "client.agents.events_pull (PR #38, shipped 2026-05-11)"}
  },

  "endpoints_missing": {
    "POST /v1/worker/heartbeat": {"blocker": "Worker registration endpoint; users typically run cueapi-worker package which handles this internally."},
    "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."},
    "GET /v1/auth/webhook-secret": {"blocker": "Webhook-secret retrieval — could surface if SDK users want to verify signatures programmatically. Re-evaluate."},
    "POST /v1/auth/webhook-secret/regenerate": {"blocker": "Destructive; intentionally not surfaced."},
    "POST /v1/agents/{ref}/webhook-secret/regenerate": {"blocker": "Destructive; needs --confirm-destructive pattern. Tracked on Backlog (Drift-audit deferred 2026-05-07)."},
    "DELETE /v1/messages bulk (cueapi #650)": {"blocker": "Server-side shipped; not yet in cueapi-cli. SDK can port directly. Tracked on Backlog (Drift-audit deferred 2026-05-07)."},
    "POST /v1/executions/{id}/live-claim (cueapi #664)": {"blocker": "P0 Live-claim attestation endpoint. Handler-runtime concern, not SDK control-plane. Re-evaluate if SDK users build live-attached handlers in Python."}
  },

  "ports_shipped_2026_05_08_to_2026_05_12": {
    "PR #30 (closed superseded by #33)": "client.cues.fire(send_at) — closed unmerged in favor of #33's broader scope",
    "PR #31 (merged 2026-05-11)": "Execution + Worker + Agent + Message additive Pydantic model classes (drift backfill)",
    "PR #33 (merged 2026-05-09)": "client.cues.fire(send_at, exit_criteria, idempotency_key) — covers cueapi #618 + #632 + #683",
    "PR #34 (merged 2026-05-09)": "client.messages.send(send_at) — covers cueapi #623",
    "PR #35 (merged 2026-05-09)": "client.agents.roster() + client.agents.presence() — covers cueapi #630 + #662",
    "PR #38 (merged 2026-05-11)": "client.agents.subscriptions_create/list/delete + events_pull — PR-1b event-emit primitive, covers cueapi/cueapi #731 (substrate ports as cueapi-core #71)",
    "PR #39 (merged 2026-05-11)": "client.messages.send(auto_verify=True default) — Phase 2 body-verify defense-in-depth, covers cueapi/cueapi #795",
    "PR #40 (merged 2026-05-11)": "messages.send body_received-is-dict isinstance fix — cueapi/cueapi #797 dict-shape window",
    "PR #42 (merged 2026-05-12)": "client.agents.subscriptions_create(inline_body=...) — covers cueapi/cueapi #791 (Item 1)"
  },

  "ports_in_flight_2026_05_12": {
    "comment": "Empty as of audit time. Future port candidates (already filed as Backlog rows): cueapi-action Phase 2 verify wiring (might already be in by #14/#15 ports); cueapi-mcp body-verify Phase 2 just shipped as cueapi-mcp#35."
  },

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