Expose scoped context document lineage reads

SI
5d ago
+387-1

Summary

Adds the read_document_history action to the shared HTTP/MCP context operation, so a document's immutable revision history can be read with the same workspace scoping as every other read.

  • Operation. processContextOperation delegates to a new SRP processDocumentHistoryOperation. It calls the new read_context_document_history RPC through the allowlisted callContextRpc access layer, passing:
    • p_owner from authorizeContextOwner;
    • the exclusive before_revision cursor (1 or more, since revision 0 is never recorded);
    • a zod-bounded limit (1–100, default 50).
  • Not found. A null read (another workspace's document, or an unknown one) becomes state: "not_found" without confirming that the document exists.
  • MCP. The standard MCP context tool exposes this as the read-only read_music_context_document_history operation. That brings the delegated OAuth catalog to 85 tools. There is no new route or tool file.

document_id comes from a brief response (documents[].id or input_manifest.documents[].documentId). A superseded brief's manifest (documentId, version, resultId) can then be resolved to the result that was current at that revision.

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

Merge sequencing

Order: docs → database → api → app.

  • Sibling PRs for this ticket: docs recoupable/docs#362 (contract) and database recoupable/database#99.
  • database#99 is a draft whose production apply waits for the CE01 deployed-schema verification (recoupable/app#2117, open as recoupable/database#103). This API change must not be released before that migration is applied; until then the action fails with the standard 409.
  • No app PR in this slice.
  • Branches from current main (c72887a).
  • Overlap with open api#981/#983/#985 is limited to one appended string in the callContextRpc allowlist, one localized two-line branch beside the release-case delegation, and one MCP entry.
  • The MCP catalog count in fullOAuthCatalog.test.ts (84 → 85) also changes in other open PRs that add context actions (e.g. api#1008/#1017/#1019). Whichever merges later must rebase and bump the count again.

Verification

  • pnpm exec vitest run lib/context → 69 files passed / 8 skipped; 335 tests passed / 8 skipped; 0 failed.
  • pnpm exec vitest run lib/supabase/context_requests lib/mcp app/api/context → 41 files, 198 tests passed, 0 failed.
  • pnpm test:mcp-oauth (the compatibility suite) → 34 files passed / 1 skipped; 195 tests passed / 1 skipped; 0 failed. The previous head failed this suite with "expected 84 tools, got 85".
  • GitHub CI on head e834c8d: test → 1177 files passed / 11 skipped, 6334 tests passed / 13 skipped, 0 failed. compatibility, lint and format also pass. The previous head failed test and compatibility on the catalog count.
  • New lib/supabase/context_requests/__tests__/documentHistoryContextRpc.test.ts sends the action through the real callContextRpc with a mocked server client and checks two things: the exact p_owner/p_document/p_before/p_limit params, and null → not_found plus storage-error propagation.
    • Mutation check: deleting the read_context_document_history allowlist entry makes both tests fail (2 failed), and the entry was restored before commit.
  • Transport tests: with the action schema disabled, both tests fail. These are the HTTP/MCP parity test and the forged-identity test, which now asserts the account_id unrecognized_keys issue and that no operation runs.
  • pnpm exec tsc --noEmit → 198 error lines repository-wide, all in unrelated __tests__ files (lib/credits, lib/chats, lib/messages, lib/agents, …). There are 0 errors in lib/context, lib/supabase/context_requests, lib/mcp/oauth, lib/mcp/tools/context or app/api/context. pnpm exec tsc --noEmit --project tsconfig.oauth.json → exit 0.
  • pnpm exec eslint on the changed TypeScript files → 0 problems. pnpm exec prettier --check on those files plus lib/context/README.md → clean.
  • Red → green: before implementation, documentHistoryOperation.test.ts failed with Cannot find module '../processDocumentHistoryOperation', and the transport tests failed as described above. They pass now.
  • Repository automation: the Vercel integration built a preview deployment of this branch. That is automatic, not an agent action, and no hosted call of the action was made.
  • Not verified: hosted HTTP/MCP calls of the action, production database (the RPC is exercised only through the database PR's local fixtures), live providers.

Out of scope / known gaps

  • No correction/withdrawal writes (#2124), no broader lifecycle exposure (#2125), no chat UI for lineage, no new npm dependency.
  • The operation returns history as the database projects it (snake_case, newest first). It does not join brief snapshots or reconstruct document text.

🤖 Generated with Claude Code