Document list_executions and read_execution context actions

SI
5d ago
+64-2

Summary

Documents the two already-merged, read-only execution trace actions of the shared POST /api/context operation so an external reviewer can discover the trace contract: list_executions (saved executions of one request) and read_execution (one execution's immutable plan, policy version, node outcomes and claim states). The description states that a claimed node without an outcome reads as unknown and needs reconciliation, that reading never retries, dispatches or spends, and that per-node cost, timing and prompts are not recorded (cost is unknown, not zero). Two request examples are added. No new MDX pages (frontmatter-only pattern) and no nav change.

Refs recoupable/app#2146 (child of epic recoupable/app#2116).

Merge sequencing

docs (this PR) → database (none: read_context_execution / list_context_request_executions shipped in database PR77) → api (none: both actions are already on main in lib/context/processContextOperation.ts) → app (recoupable/app#2219, the /releases Execution traces panel that consumes these actions). No dependency on open api#981/#983/#985; this change adds only two anchored oneOf entries, so a rebase against other context.json edits stays trivial.

Verification

  • Ran: python3 -c "import json;d=json.load(open('api-reference/openapi/context.json'));s=json.dumps(d);assert 'list_executions' in s and 'read_execution' in s;print('ok')" → ok
  • Ran: variant listing after the edit → ['ingest','read','brief','save_brief','read_brief','list_executions','read_execution']; examples → ['twoSongBrief','saveBrief','readBrief','listExecutions','readExecution']
  • Ran: git diff --stat origin/main -- api-reference/openapi/context.json → 1 file changed, 64 insertions(+), 2 deletions(-); the two deletions are the operation and 200-response description strings extended in place. git diff --numstat origin/main shows no other file.
  • Red → green: not applicable (documentation only; JSON parse check passed after the anchored insert).
  • Not verified: Mintlify rendering (mintlify dev not run), hosted docs deployment, live providers, production database.

Out of scope / known gaps

  • Release-case and company_onboarding actions remain undocumented in context.json (other tickets).
  • No MCP tool-name documentation (list_music_context_executions / read_music_context_execution) beyond the HTTP contract.
  • The private React Flow inspector and Business reference docs are out of scope per the ticket's ownership statement.

🤖 Generated with Claude Code