Showing the changes to apps/docs/developer (2 of 30 files). Show all
Unified · Split
| @@ -83,6 +83,8 @@ That is intentional, but the direction is: · 82 unmodified lines | |||
| 83 | 83 | ||
| 84 | The goal is not to erase differences between formats. The goal is to stop those differences from dominating the core architecture. | 84 | The goal is not to erase differences between formats. The goal is to stop those differences from dominating the core architecture. |
| 85 | 85 | ||
| 86 | For the current fidelity tradeoffs and known lossy areas across adapters, see [Import Fidelity](/developer/import-fidelity). | ||
| 87 | |||
| 86 | ## What a good new adapter should do | 88 | ## What a good new adapter should do |
| 87 | 89 | ||
| 88 | A good new adapter should: | 90 | A good new adapter should: |
| @@ -0,0 +1,132 @@ | |||
| 1 | --- | ||
| 2 | title: "Import Fidelity" | ||
| 3 | description: "What executor preserves, normalizes, and currently loses when importing external formats." | ||
| 4 | --- | ||
| 5 | |||
| 6 | Executor should normalize syntax, not meaning. | ||
| 7 | |||
| 8 | That means the import pipeline can simplify surface differences between OpenAPI, GraphQL, Google Discovery, and MCP, but it should not silently erase semantics that change execution, trust, or user understanding. | ||
| 9 | |||
| 10 | The practical shape is: | ||
| 11 | |||
| 12 | - keep the raw source document or manifest | ||
| 13 | - keep adapter-native metadata that does not fit the common model cleanly | ||
| 14 | - promote execution-relevant semantics into first-class IR | ||
| 15 | |||
| 16 | ## The fidelity buckets | ||
| 17 | |||
| 18 | This audit uses four buckets: | ||
| 19 | |||
| 20 | - `Raw source`: the original imported document or manifest | ||
| 21 | - `Adapter/native`: typed provider data or native blobs attached during import | ||
| 22 | - `IR`: first-class catalog symbols and capability metadata | ||
| 23 | - `UI today`: what current inspection surfaces directly | ||
| 24 | |||
| 25 | Current inspection is still narrow. It mostly shows projected schemas plus `tool.executable.native[0]`, not all preserved native blobs or capability-native metadata. | ||
| 26 | |||
| 27 | ## OpenAPI | ||
| 28 | |||
| 29 | | Source detail | Raw source | Adapter/native | IR | UI today | Notes | | ||
| 30 | | --- | --- | --- | --- | --- | --- | | ||
| 31 | | Operation auth requirements and security schemes | Yes | No | No | No | Operation `security` is not promoted; imported capabilities currently use `auth: none`. | | ||
| 32 | | Exact response variants, status codes, and headers | Yes | Partial | No | Partial | Import chooses one preferred response, then projects one synthetic `2XX` response set. | | ||
| 33 | | Parameter serialization (`style`, `explode`, `allowReserved`, content-based params) | Yes | Mostly no | No | No | The IR can model these, but the OpenAPI importer currently only takes parameter `schema`. | | ||
| 34 | | Multiple request and response media types | Yes | Partial | Partial | Partial | Import picks a preferred content entry for typing; response docs keep content types only for the chosen response. | | ||
| 35 | | `servers` defaults | Yes | No | No | No | The IR can represent scope server defaults, but OpenAPI import does not populate them. | | ||
| 36 | | Rich schema semantics beyond the importer subset | Yes | Partial | Partial | Partial | Unsupported JSON Schema shapes fall back to `unknown` plus native preservation. | | ||
| 37 | |||
| 38 | ## GraphQL | ||
| 39 | |||
| 40 | | Source detail | Raw source | Adapter/native | IR | UI today | Notes | | ||
| 41 | | --- | --- | --- | --- | --- | --- | | ||
| 42 | | Subscription root fields as tools | Yes | Partial | No | No | The manifest records `subscriptionTypeName`, but tool generation only materializes query and mutation fields. | | ||
| 43 | | Full field result shapes for generated field tools | Yes | Partial | Partial | Partial | Field-tool outputs are heuristic projections, not full result types. | | ||
| 44 | | Union and deep nested selections | Yes | Partial | Partial | Partial | Unions degrade to `__typename`; nested selection stops after depth 2 in generated field tools. | | ||
| 45 | | Arbitrary caller-selected field projections | Yes | Partial | No | No | Generated field tools are compiled with fixed selections; the raw `request` tool is the escape hatch. | | ||
| 46 | | Deprecation reasons | Yes | Partial | Partial | No | GraphQL schemas emit `deprecated: true` plus `x-deprecationReason`, but the generic schema importer only keeps `deprecated` as first-class shape metadata. | | ||
| 47 | |||
| 48 | GraphQL is a special case: the main loss is not the raw source being discarded, but the generated field-tool projection being intentionally narrower than the schema. That tradeoff is reasonable for discoverability, but only if the system continues to preserve and expose the raw request path. | ||
| 49 | |||
| 50 | ## Google Discovery | ||
| 51 | |||
| 52 | | Source detail | Raw source | Adapter/native | IR | UI today | Notes | | ||
| 53 | | --- | --- | --- | --- | --- | --- | | ||
| 54 | | OAuth scope descriptions | Yes | Partial | No | No | Document-level scope descriptions are extracted, but the IR security scheme rewrites scopes to `{ scope: scope }`. | | ||
| 55 | | Rich media upload metadata | Yes | Partial | Partial | Partial | Upload support is collapsed to booleans such as `supportsMediaUpload` and `supportsMediaDownload`. | | ||
| 56 | | Service-level metadata (`title`, `description`, `batchPath`, `documentationLink`) | Yes | Partial | No | No | The extracted manifest has these fields, but per-operation provider data does not carry them into the catalog. | | ||
| 57 | | Parameter descriptions, repeated-ness, enums, defaults | Yes | Yes | Mostly yes | Mostly yes | This area is comparatively good. | | ||
| 58 | | Request and response schemas | Yes | Yes | Yes | Yes | Core schema structure is preserved reasonably well. | | ||
| 59 | |||
| 60 | Google Discovery is less lossy than OpenAPI on request and response typing, but it still loses useful service metadata and the human meaning attached to OAuth scopes. | ||
| 61 | |||
| 62 | ## MCP | ||
| 63 | |||
| 64 | | Source detail | Raw source | Adapter/native | IR | UI today | Notes | | ||
| 65 | | --- | --- | --- | --- | --- | --- | | ||
| 66 | | Non-tool MCP resources such as prompts or resources | No | No | No | No | The adapter only discovers `listTools()`. Anything outside the tool list never enters import. | | ||
| 67 | | Extra tool metadata beyond `name`, `description`, `inputSchema` or `parameters`, and `outputSchema` | Partial | Partial | No | No | The manifest schema keeps only a narrow subset of listed tool fields. | | ||
| 68 | | Tool-level safety or effect hints, if present | Partial | No | No | No | Imported MCP operations are currently hardcoded to `effect: action`. | | ||
| 69 | | Tool input and output schemas | Yes | Yes | Yes | Yes | This is the strongest part of the current MCP import. | | ||
| 70 | | Server-level metadata outside the tool list | No | No | No | No | The stored MCP "document" is a synthesized tool manifest, not a richer upstream server description. | | ||
| 71 | |||
| 72 | MCP is the most structurally lossy adapter today because the discovery step itself only imports tools and already narrows their metadata aggressively. | ||
| 73 | |||
| 74 | ## Cross-cutting UI caveat | ||
| 75 | |||
| 76 | Even when data is preserved natively, the current inspection UI often does not show it directly. | ||
| 77 | |||
| 78 | Today inspection primarily exposes: | ||
| 79 | |||
| 80 | - projected call and result schemas | ||
| 81 | - capability summary text | ||
| 82 | - the first executable native blob | ||
| 83 | |||
| 84 | That means "preserved in native data" and "visible to a user" are still different states. | ||
| 85 | |||
| 86 | ## What should be first-class in IR | ||
| 87 | |||
| 88 | These semantics are worth promoting into the common model because they affect execution or trust: | ||
| 89 | |||
| 90 | - auth and security requirements described by the source format | ||
| 91 | - response and status variants | ||
| 92 | - HTTP parameter serialization | ||
| 93 | - upload, download, and streaming traits | ||
| 94 | - GraphQL selection and subscription semantics | ||
| 95 | - source-provided safety or idempotency hints | ||
| 96 | |||
| 97 | By contrast, many provider-specific labels, service metadata fields, and raw source extras are fine to keep in adapter-native metadata as long as they remain inspectable. | ||
| 98 | |||
| 99 | ## Recommended priority order | ||
| 100 | |||
| 101 | ### P0 | ||
| 102 | |||
| 103 | - OpenAPI auth and security requirements | ||
| 104 | - OpenAPI response variants and status distinctions | ||
| 105 | - Google Discovery scope descriptions | ||
| 106 | - MCP discovery breadth: decide whether executor intends to import only tools or broader MCP surface area | ||
| 107 | |||
| 108 | ### P1 | ||
| 109 | |||
| 110 | - OpenAPI parameter serialization | ||
| 111 | - GraphQL subscription modeling | ||
| 112 | - GraphQL field-tool projection metadata so the fixed-selection behavior is explicit | ||
| 113 | - Google Discovery service metadata surfacing | ||
| 114 | - MCP tool metadata preservation beyond the current narrow manifest | ||
| 115 | |||
| 116 | ### P2 | ||
| 117 | |||
| 118 | - Better UI fallback to native/provider metadata | ||
| 119 | - Richer diagnostics for intentionally lossy normalization | ||
| 120 | - A fixture-backed audit matrix test per adapter | ||
| 121 | |||
| 122 | ## The IR boundary | ||
| 123 | |||
| 124 | The right boundary is: | ||
| 125 | |||
| 126 | - `raw source` remains the source of truth | ||
| 127 | - `adapter-native metadata` keeps source-specific details close to their format | ||
| 128 | - `IR` stays unified, but it must be lossless for downstream semantics | ||
| 129 | |||
| 130 | If executor keeps that line clear, a standardized representation is a strength. | ||
| 131 | |||
| 132 | If executor lets semantically important details live only in hidden native blobs, the standardized representation becomes misleading. | ||