refactor(sdk): move GraphQL error policy out of the transport seam [#354 Rung 3]

[Danielmoraisg]

What

Rung 3 of #354: move GraphQL error policy out of the transport seam.

Rung 2 collapsed the seam to one protocol and one result type. This rung takes the two decisions the seam still baked in (raise-on-error and how to format the error) out of the transport layer and into the pure core, and deletes the [code=...] [correlation_id=...] string envelope round-trip.

• Add PipefyGraphQLError (owned, carries the raw structured errors list) and the pure data_or_raise(GraphQLResult) -> dict.
• execute_query is now data_or_raise over the execute primitive and raises PipefyGraphQLError for every endpoint. No gql transport type leaks to services, CLI, or MCP.
• Drop the per-endpoint on_graphql_error formatter and delete internal_api_errors.py.
• Delete the [code=...] [correlation_id=...] envelope and its three parsers in the MCP tool layer. Codes and correlation ids now come off the structured errors for both endpoints (extract_graphql_correlation_id reads errors[].extensions, mirroring extract_graphql_error_codes). This removes a serialize-then-reparse round-trip: the envelope only existed to encode codes into a string that the tool layer regexed back out.
• Migrate the except TransportQueryError sites (SDK services + CLI) to except PipefyGraphQLError, and unify portal_service's two permission mappers into one structured mapper.
• Export PipefyGraphQLError from pipefy_sdk.

Why the seam keeps two methods

The protocol still exposes execute (the primitive) and execute_query (the raise-on-error convenience). Collapsing to a single execute was considered and rejected: with no static type checker in this repo, (await ex.execute(...)).data would silently drop GraphQL errors, and ~140 of ~142 call sites want raise-on-error. Keeping execute_query as the ergonomic default means those callers cannot forget to raise, and it is not a second transport capability (it does no I/O; it is data_or_raise over execute).

Behavior

• The ~152 execute_query callers are unchanged at the call site. On GraphQL errors they now catch PipefyGraphQLError instead of a gql TransportQueryError / a ValueError envelope.
• Debug output is preserved: MCP tools still surface error codes and correlation ids under debug=True, now read from the structured errors.
• Genuine transport failures (non-2xx, timeouts) still propagate as gql TransportError subclasses, unchanged.
• One deliberate CLI change: a non-permission internal-API GraphQL error now exits 1 (with the clean message (code) format) instead of 2. Exit 2 is the usage-error code, so a server-side GraphQL failure exiting 2 was wrong; this aligns internal-API CLI errors with public-API ones. Permission errors are unchanged. No CLI test pinned the old exit 2 (every exit-2 assertion is a client-side validation path that never reaches the API).

Testing

• Full suite green: uv run pytest packages -m "not integration" -> 3068 passed, 5 skipped. Ruff check + format clean.
• Added data_or_raise / PipefyGraphQLError unit tests; converted the error-simulation tests across SDK, MCP, and CLI to raise PipefyGraphQLError with structured errors.

Stacking

Stacked on #382 (Rung 2); this PR targets that branch so its diff is only the Rung 3 delta. It retargets to dev automatically once #382 merges. Tracked under #354.